Goto Chapter: Top 1 2 3 4 5 6 A Bib Ind
 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 

A Some Tools for Database Handling
 A.1 GAP Objects for Database Handling
 A.2 Using Database Attributes for Browse Tables
 A.3 Example: Database Id Enumerators and Database Attributes
 A.4 Example: An Overview of the GAP Library of Tables of Marks

A Some Tools for Database Handling

Two aims of the tools described in this appendix are

The GAP objects introduced for that are database id enumerators (see A.1-1) and database attributes (see A.1-2).

Contrary to the individual interfaces to the GAP manuals (see Section 6.6), the GAP bibliography (see Section 6.7), and the overviews of GAP packages, GAP methods, and Conway polynomials available in GAP (see Section 6.11), the approach that will be described here assumes a special way to access database entries. Thus it depends on the structure of a given database whether the tools described here are useful, or whether an individual interface fits better. Perhaps the example shown in Section A.3 gives an impression what is possible.

A.1 GAP Objects for Database Handling

A.1-1 Database Id Enumerators

A database id enumerator is a record r with at least the following components.

identifiers

a list of "identifiers" of the database entries, which provides a bijection with these entries,

entry

a function that takes r and an entry in the identifiers list, and returns the corresponding database entry,

attributes

the record whose components are the database attribute records (see Section A.1-2) for r; this components is automatically initialized when r is created with DatabaseIdEnumerator (A.1-4); database attributes can be entered with DatabaseAttributeAdd (A.1-5).

If the identifiers list may change over the time (because the database is extended or corrected) then the following components are supported. They are used by DatabaseIdEnumeratorUpdate (A.1-7).

version

a GAP object that describes the version of the identifiers component, this can be for example a string describing the time of the last change (this time need not coincide with the time of the last update); the default value (useful only for the case that the identifiers component is never changed) is an empty string,

update

a function that takes r as its argument, replaces its identifiers and version values by up-to-date versions if necessary (for example by downloading the data), and returns true or false, depending on whether the update process was successful or not; the default value is ReturnTrue (Reference: ReturnTrue),

The following component is optional.

isSorted

true means that the identifiers list is sorted w.r.t. GAP's ordering \<; the default is false.

The idea behind database id enumerator objects is that such an object defines the set of data covered by database attributes (see Section A.1-2), it provides the mapping between identifiers and the actual entries of the database, and it defines when precomputed data of database attributes are outdated.

A.1-2 Database Attributes

A database attribute is a record a whose components belong to the aspects of defining the attribute, accessing the attribute's data, computing (and recomputing) data, storing data on files, and checking data. (Additional parameters used for creating browse table columns from database attributes are described in Section A.2-1.)

The following components are defining, except description they are mandatory.

idenumerator

the database id enumerator to which the attribute a is related,

identifier

a string that identifies a among all database attributes for the underlying database id enumerator (this is used by BrowseTableFromDatabaseIdEnumerator (A.2-2) and when the data of a are entered with DatabaseAttributeSetData (A.1-9), for example when precomputed values are read from a file),

description

a string that describes the attribute in human readable form (currently just for convenience, the default is an empty string).

The following components are used for accessing data. Except type, they are optional, but enough information must be provided in order to make the database attribute meaningful. If an individual attributeValue function is available then this function decides what is needed; for the default function DatabaseAttributeValueDefault (A.1-6), at least one of the components name, data, datafile must be bound (see DatabaseAttributeValueDefault (A.1-6) for the behaviour in this case).

type

one of the strings "values" or "pairs"; the format of the component data is different for these cases,

name

if bound, a string that is the name of a GAP function such that the database attribute encodes the values of this function for the database entries; besides the computation of attribute values on demand (see DatabaseAttributeValueDefault (A.1-6)), this component can be used by selection functions such as OneCharacterTableName (CTblLib: OneCharacterTableName) or AllCharacterTableNames (CTblLib: AllCharacterTableNames), which take GAP functions and prescribed return values as their arguments –of course these functions must then be prepared to deal with database attributes.

data

if bound, the data for this attribute; if the component type has the value "values" then the value is a list, where the entry at position i, if bound, belongs to the i-th entry of the identifiers list of idenumerator; if type is "pairs" then the value is a record with the components automatic and nonautomatic, and the values of these components are lists such that each entry is a list of length two whose first entry occurs in the identifiers list of a.idenumerator and whose second entry encodes the corresponding attribute value,

datafile

if bound, the absolute name of a file that contains the data for this attribute,

attributeValue

a function that takes a and an identifiers entry of its idenumerator value, and returns the attribute value for this identifier; typically this is not a table cell data object that can be shown in a browse table, cf. the viewValue component; the default is DatabaseAttributeValueDefault (A.1-6) (Note that using individual attributeValue functions, one can deal with database attributes independent of actually stored data, for example without precomputed values, such that the values are computed on demand and afterwards are cached.),

dataDefault

a GAP object that is regarded as the attribute value for those database entries for which data, datafile, and name do not provide values; the default value is an empty string "",

eval

if this component is bound, the value is assumed to be a function that takes a and a value from its data component, and returns the actual attribute value; this can be useful if one does not want to create all attribute values in advance, because this would be space or time consuming; another possible aspect of the eval component is that it may be used to strip off comments that are perhaps contained in data entries,

isSorted

if this component is bound to true and if type is "pairs" then it is assumed that the two lists in the data record of a are sorted w.r.t. GAP's ordering \<; the default is false,

The following optional components are needed for computing (or recomputing) data with DatabaseAttributeCompute (A.1-8). This is useful mainly for databases which can change over the time.

version

the GAP object that is the version component of the idenumerator component at the time when the stored data were entered; this value is used by DatabaseIdEnumeratorUpdate (A.1-7) for deciding whether the attribute values are outdated; if a.datafile is bound then it is assumed that the version component is set when this file is read, for example in the function DatabaseAttributeSetData (A.1-9),

update

a function that takes a as its argument, adjusts its data components to the current values of a.dbidenum if necessary, sets the version component to that of a.dbidenum, and returns true or false, depending on whether the update process was successful or not; the default value is ReturnTrue (Reference: ReturnTrue),

neededAttributes

a list of attribute identifier strings such that the values of these attributes are needed in the computations for the current one, and therefore these should be updated/recomputed in advance; it is assumed that the neededAttributes components of all database attributes of a.idenumerator define a partial ordering; the default is an empty list,

prepareAttributeComputation

a function with argument a that must be called before the computations for the current attribute are started; the default value is ReturnTrue (Reference: ReturnTrue),

cleanupAfterAttibuteComputation

a function with argument a that must be called after the computations for the current attribute are finished; the default value is ReturnTrue (Reference: ReturnTrue), and

create

a function that takes a database attribute and an entry in the identifiers list of its database id enumerator, and returns either the entry that shall be stored in the data component, as the value for the given identifier (if this value shall be stored in the data component of a) or the dataDefault component of a (if this value shall not be stored); in order to get the actual attribute value, the eval function of a, if bound, must be called with the return value. This function may assume that the prepareAttributeComputation function has been called in advance, and that the cleanupAfterAttibuteComputation function will be called later. The create function is not intended to compute an individual attribute value on demand, use a name component for that. (A stored name function is used to provide a default for the create function; without name component, there is no default for create.)

The following optional component is needed for storing data on files.

string

if bound, a function that takes the pair consisting of an identifier and the return value of the create function for this identifier, and returns a string that shall represent this value when the data are printed to a file; the default function returns the String (Reference: String) value of the second argument.

The following optional component is needed for checking stored data.

check

a function that takes a string that occurs in the identifiers list of the idenumerator record, and returns true if the attribute value stored for this string is reasonable, and something different from true if an error was detected. (One could argue that these tests can be performed also when the values are computed, but consistency checks may involve several entries; besides that, checking may be cheaper than recomputing.)

A.1-3 How to Deal with Database Id Enumerators and Database Attributes

The idea is to start with a database id enumerator (see A.1-1), constructed with DatabaseIdEnumerator (A.1-4), and to define database attributes for it (see A.1-2), using DatabaseAttributeAdd (A.1-5). The attribute values can be precomputed and stored on files, or they are computed when the attribute gets defined, or they are computed on demand.

The function DatabaseAttributeCompute (A.1-8) can be used to "refresh" the attribute values, that is, all values or selected values can be recomputed; this can be necessary for example when the underlying database id enumerator gets extended.

In data files, the function DatabaseAttributeSetData (A.1-9) can be used to fill the data component of the attribute.

A.1-4 DatabaseIdEnumerator
‣ DatabaseIdEnumerator( arec )( function )

Returns: a shallow copy of the record arec, extended by default values.

For a record arec, DatabaseIdEnumerator checks whether the mandatory components of a database id enumerator (see Section A.1-1) are present, initializes the attributes component, sets the defaults for unbound optional components (see A.2-1), and returns the resulting record.

A special database attribute (see Section A.1-2) with identifier value "self" is constructed automatically for the returned record by DatabaseIdEnumerator; its attributeValue function simply returns its second argument (the identifier). The optional components of this attribute are derived from components of the database id enumerator, so these components (see A.2-1) are supported for arec. A typical use of the "self" attribute is to provide the first column in browse tables constructed by BrowseTableFromDatabaseIdEnumerator (A.2-2).

A.1-5 DatabaseAttributeAdd
‣ DatabaseAttributeAdd( dbidenum, arec )( function )

For a database id enumerator dbidenum and a record arec, DatabaseAttributeAdd checks whether the mandatory components of a database attribute, except idenumerator, are present in arec (see Section A.1-2), sets the idenumerator component, and sets the defaults for unbound optional components (see A.2-1).

A.1-6 DatabaseAttributeValueDefault
‣ DatabaseAttributeValueDefault( attr, id )( function )

Returns: the value of the database attribute attr at id.

For a database attribute attr and an entry id of the identifiers list of the underlying database id enumerator, DatabaseAttributeValueDefault takes the data entry for id, applies the eval function of attr to it if available and returns the result.

So the question is how to get the data entry.

First, if the data component of attr is not bound then the file given by the datafile component of attr, if available, is read, and otherwise DatabaseAttributeCompute (A.1-8) is called; afterwards it is assumed that the data component is bound.

The further steps depend on the type value of attr.

If the type value of attr is "pairs" then the data entry for id is either contained in the automatic or in the nonautomatic list of attr.data, or it is given by the dataDefault value of attr. (So a perhaps available name function is not used to compute the value for a missing data entry.)

If the type value of attr is "values" then the data entry for id is computed as follows. Let n be the position of id in the identifiers component of the database id enumerator. If the n-th entry of the data component of attr is bound then take it; otherwise if the name component is bound then apply it to id and take the return value; otherwise take the dataDefault value.

If one wants to introduce a database attribute where this functionality is not suitable then another –more specific– function must be entered as the component attributeValue of such an attribute.

A.1-7 DatabaseIdEnumeratorUpdate
‣ DatabaseIdEnumeratorUpdate( dbidenum )( function )

Returns: true or false.

For a database id enumerator dbidenum (see Section A.1-1), DatabaseIdEnumeratorUpdate first calls the update function of dbidenum. Afterwards, the update components of those of its attributes records are called for which the version component differs from that of dbidenum.

The order in which the database attributes are updates is determined by the neededAttributes component.

The return value is true if all these functions return true, and false otherwise.

When DatabaseIdEnumeratorUpdate has returned true, the data described by dbidenum and its database attributes are consistent and up to date.

A.1-8 DatabaseAttributeCompute
‣ DatabaseAttributeCompute( dbidenum, attridentifier[, what] )( function )

Returns: true or false.

This function returns false if dbidenum is not a database id enumerator, or if it does not have a database attribute with identifier value attridentifier, or if this attribute does not have a create function.

Otherwise the prepareAttributeComputation function is called, the data entries for the database attribute are (re)computed, the cleanupAfterAttibuteComputation function is called, and true is returned.

The optional argument what determines which values are computed. Admissible values are

"all"

all identifiers entries of dbidenum,

"automatic" (the default)

the same as "all" if the type value of the database attribute is "values", otherwise only the values for the "automatic" component are computed,

"new"

stored values are not recomputed.

A.1-9 DatabaseAttributeSetData
‣ DatabaseAttributeSetData( dbidenum, attridentifier, version, data )( function )

Let dbidenum be a database id enumerator (see Section A.1-1), attridentifier be a string that is the identifier value of a database attribute of dbidenum, data be the data list or record for the database attribute (depending on its type value), and version be the corresponding version value.

DatabaseAttributeSetData sets the data and version components of the attribute. This function can be used for example in data files.

A.2 Using Database Attributes for Browse Tables

A.2-1 Browse Relevant Components of Database Attributes

The following optional components of database id enumerators and database attributes are used by BrowseTableFromDatabaseIdEnumerator (A.2-2).

viewLabel

if bound, a table cell data object (see BrowseData.IsBrowseTableCellData (4.2-1)) that gives a short description of the attribute, which is used as the column label in browse tables created with BrowseTableFromDatabaseIdEnumerator (A.2-2); the default for database attributes is the name component, if bound, and otherwise the identifier component; the default for database id enumerators is the string "name",

viewValue

if bound, a function that takes the output of the attributeValue function and returns a table cell data object (see BrowseData.IsBrowseTableCellData (4.2-1)) that is used as the entry of the corresponding column in browse tables created with BrowseTableFromDatabaseIdEnumerator (A.2-2); the default is String (Reference: String),

viewSort

if bound, a comparison function that takes two database attribute values and returns true if the first value is regarded as smaller than the second when the column corresponding to the attribute in the browse table constructed by BrowseTableFromDatabaseIdEnumerator (A.2-2) gets sorted, and false otherwise; the default is GAP's \< operation,

sortParameters

if bound, a list in the same format as the last argument of BrowseData.SetSortParameters, which is used for the column corresponding to the attribute in the browse table constructed by BrowseTableFromDatabaseIdEnumerator (A.2-2); the default is an empty list,

widthCol

if bound, the width of the column in the browse table constructed by BrowseTableFromDatabaseIdEnumerator (A.2-2); if a column width is prescribed this way then the function stored in the attributeValue component must return either a list of attribute lines that fit into the column or a plain string (which then gets formatted as required); there is no default for this component, meaning that the column width is computed as the maximum of the widths of the column label and of all entries in the column if no value is bound,

align

if bound, the alignment of the values in the column of the browse table constructed by BrowseTableFromDatabaseIdEnumerator (A.2-2); admissible values are substrings of "bclt", see BrowseData.IsBrowseTableCellData (4.2-1); the default is right and vertically centered, but note that if the viewValues function returns a record (see BrowseData.IsBrowseTableCellData (4.2-1)) then the alignment prescribed by this record is preferred,

categoryValue

if bound, a function that is similar to the viewValue component but may return a different value; for example if the column in the browse table belongs to a property and the viewValue function returns something like "+" or "-", it may be useful that the category rows show a textual description of the property values; the default value is the viewValue component; if the value is a record then its rows component is taken for forming category rows, if the value is an attribute line (see NCurses.IsAttributeLine (2.2-3)) then there is exactly this category row, and otherwise the value is regarded as a list of attribute lines, which is either concatenated to one category row or turned into individual category rows, depending on the sortParameters value.

A.2-2 BrowseTableFromDatabaseIdEnumerator
‣ BrowseTableFromDatabaseIdEnumerator( dbidenum, labelids, columnids[, header[, footer[, choice]]] )( function )

Returns: a record that can be used as the input of NCurses.BrowseGeneric (4.3-1).

For a database id enumerator dbidenum (see Section A.1-1) and two lists labelids and columnids of identifier values of database attributes stored in dbidenum, BrowseTableFromDatabaseIdEnumerator returns a browse table (see BrowseData.IsBrowseTable (4.2-3)) whose columns are given by the values of the specified database attributes. The columns listed in labelids are used to provide row label columns of the browse table, the columns listed in columnids yield main table columns. columnids must be nonempty.

If the optional arguments header and footer are given then they must be lists or functions or records that are admissible for the header and footer components of the work record of the browse table, see BrowseData.IsBrowseTable (4.2-3).

The optional argument choice, if given, must be a subset of dbidenum.identifiers. The rows of the returned browse table are then restricted to this subset.

The returned browse table does not support "Click" events or return values.

A.3 Example: Database Id Enumerators and Database Attributes

As an example for the functions introduced in this appendix, we introduce the database of small integers. For that, we fix a positive integer n and consider the integers from 1 to n as the entries of our database. Using these integers as their own identifiers, we construct the database id enumerator.

gap> n:= 100;;
gap> smallintenum1:= DatabaseIdEnumerator( rec(
>      identifiers:= [ 1 .. n ],
>      entry:= function( dbidenum, id ) return id; end,
>    ) );;

Examples of attributes for this database are the properties whether or not an integer is a prime or a prime power. There are global GAP functions IsPrimeInt (Reference: IsPrimeInt) and IsPrimePowerInt (Reference: IsPrimePowerInt) for computing these properties, so we can define these database attributes via a name component; we choose "values" as the type value, so the values (true or false) are stored in a list of length n for each of the two database attributes.

gap> DatabaseAttributeAdd( smallintenum1, rec(
>      identifier:= "primes",
>      type:= "values",
>      name:= "IsPrimeInt",
>    ) );
gap> DatabaseAttributeAdd( smallintenum1, rec(
>      identifier:= "prime powers",
>      type:= "values",
>      name:= "IsPrimePowerInt",
>    ) );

Similarly, we consider the prime factors as a database attribute.

gap> DatabaseAttributeAdd( smallintenum1, rec(
>      identifier:= "factors",
>      type:= "values",
>      name:= "Factors",
>    ) );

Another example of an attribute of integers is the residue modulo 11. We do not want to introduce a global GAP function for computing the value, so we use the create component in order to define the attribute; again, the values (integers from 0 to 10) are stored in a list of length n.

gap> DatabaseAttributeAdd( smallintenum1, rec(
>      identifier:= "residue mod 11",
>      type:= "values",
>      create:= function( attr, id ) return id mod 11; end,
>    ) );

Some integers are values of Factorial (Reference: Factorial), and we want to record this information and show it in a browse table. For most integers, nothing is stored and shown for this attribute, so we choose the type value "pairs" and precompute the information for the data component. (The default for the dataDefault component is an empty string, which is fine; so we need not prescribe this component.)

gap> factorialdata:= function( n )
>      local result, i, f;
>      result:= [];  i:= 1;  f:= 1;;
>      while f <= n do
>        Add( result, [ f, i ] );  i:= i + 1;  f:= f * i;
>      od;
>      return result;
>    end;;
gap> DatabaseAttributeAdd( smallintenum1, rec(
>      identifier:= "inverse factorial",
>      type:= "pairs",
>      data:= rec( automatic:= factorialdata( n ), nonautomatic:= [] ),
>      isSorted:= true,
>    ) );

We use this setup for creating a browse table. The integers are shown as the first column, using the "self" attribute. This attribute can be used as a column of row labels (useful if we want to keep the column visible when one scrolls the table to the right) or as a column in the main table (useful if we want to search for the values); here we choose the former possibility.

gap> t1:= BrowseTableFromDatabaseIdEnumerator( smallintenum1,
>           [ "self" ],
>           [ "primes", "prime powers", "factors", "residue mod 11",
>             "inverse factorial" ] );;

The following session shows some of the features of the browse table.

gap> nop:= [ 14, 14, 14, 14, 14, 14 ];;  # ``do nothing''
gap> sample_session:= Concatenation(
>         # categorize by the first column, expand categories, wait, reset
>         nop, "scsc", nop, "X", nop, "!",
>         # sort the residue column, wait, reset
>         "scrrrso", nop, "!",
>         # categorize by the inverse factorial column
>         "rscsrdx", nop, "!",
>         # and quit the application
>         "qQ" );;
gap> BrowseData.SetReplay( sample_session );
gap> NCurses.BrowseGeneric( t1 );
gap> BrowseData.SetReplay( false );
gap> Unbind( t1.dynamic.replay );

(Note that the last statement above is necessary to run the session more than once.) The result is not too bad but we can improve the table, using the optional components of database attributes, as follows.

We create a new database id enumerator and the corresponding browse table, in order to be able to compare the behaviour of the two objects. However, we assume that the variables n and factorialdata are already available.

gap> smallintenum2:= DatabaseIdEnumerator( rec(
>      identifiers:= [ 1 .. n ],
>      entry:= function( dbidenum, id ) return id; end,
>      viewLabel:= "",
>    ) );;
gap> DatabaseAttributeAdd( smallintenum2, rec(
>      identifier:= "primes",
>      type:= "values",
>      name:= "IsPrimeInt",
>      viewLabel:= "prime?",
>      viewValue:= value -> BrowseData.ReplacedEntry( value,
>          [ true, false ], [ "+", "-" ] ),
>      sortParameters:= [ "add counter on categorizing", "yes" ],
>      align:= "c",
>      categoryValue:= value -> BrowseData.ReplacedEntry( value,
>          [ true, false ], [ "prime", "nonprime" ] ),
>    ) );
gap> DatabaseAttributeAdd( smallintenum2, rec(
>      identifier:= "prime powers",
>      type:= "values",
>      name:= "IsPrimePowerInt",
>      viewLabel:= "prime power?",
>      viewValue:= value -> BrowseData.ReplacedEntry( value,
>          [ true, false ], [ "+", "-" ] ),
>      sortParameters:= [ "add counter on categorizing", "yes" ],
>      align:= "c",
>      categoryValue:= value -> BrowseData.ReplacedEntry( value,
>          [ true, false ], [ "prime power", "not prime power" ] ),
>    ) );
gap> DatabaseAttributeAdd( smallintenum2, rec(
>      identifier:= "factors",
>      type:= "values",
>      name:= "Factors",
>      viewLabel:= "factors",
>      viewValue:= value -> JoinStringsWithSeparator( List( value, String ),
>                                                     " * "),
>      widthCol:= 10,
>    ) );
gap> DatabaseAttributeAdd( smallintenum2, rec(
>      identifier:= "residue mod 11",
>      type:= "values",
>      create:= function( attr, id ) return id mod 11; end,
>      viewSort:= BrowseData.SortAsIntegers,
>      categoryValue:= res -> Concatenation( String( res ), " mod 11" ),
>    ) );
gap> DatabaseAttributeAdd( smallintenum2, rec(
>      identifier:= "inverse factorial",
>      type:= "pairs",
>      data:= rec( automatic:= factorialdata( n ), nonautomatic:= [] ),
>      isSorted:= true,
>      categoryValue:= function( k )
>        if k = "" then
>          return "(no factorial)";
>        else
>          return Concatenation( String( k ), "!" );
>        fi;
>      end,
>    ) );
gap> t2:= BrowseTableFromDatabaseIdEnumerator( smallintenum2,
>           [ "self" ],
>           [ "primes", "prime powers", "factors", "residue mod 11",
>             "inverse factorial" ],
>           t -> BrowseData.HeaderWithRowCounter( t, "Small integers", n ) );;

We run the same session as with the browse table for smallintenum1.

gap> BrowseData.SetReplay( sample_session );
gap> NCurses.BrowseGeneric( t2 );
gap> BrowseData.SetReplay( false );
gap> Unbind( t2.dynamic.replay );

Another possibility to change the look of the table is to combine the columns for the two Boolean valued database attributes in one column, by showing the string "+" for prime powers, as before, and showing this string in boldface red if the number in question is a prime. We implement this idea in the following database attribute. However, note that this can be a bad idea because text attributes may be not supported in the user's terminal (see Section 2.1-7), or the user may have difficulties to see or to distinguish colors; also, it must be documented which information is encoded in the table, and the column label might be not sufficient for explaining what the text attributes mean. Alternatively, we could show for example combined symbols such as ++, +-, -- for primes, prime powers, and non-prime-powers, respectively. (We see that besides these issues, the required GAP code is more involved than what is needed for the examples above.)

gap> DatabaseAttributeAdd( smallintenum2, rec(
>      identifier:= "primes & prime powers",
>      type:= "values",
>      create:= function( attr, id )
>        if   IsPrimeInt( id ) then
>          return 2;
>        elif IsPrimePowerInt( id ) then
>          return 1;
>        else
>          return 0;
>        fi;
>      end,
>      viewLabel:= [ NCurses.attrs.BOLD + NCurses.ColorAttr( "red", -1 ),
>                    "prime", NCurses.attrs.NORMAL, " power?" ],
>      viewValue:= value -> BrowseData.ReplacedEntry( value,
>          [ 0, 1, 2 ], [ "-", "+",
>                         [ NCurses.attrs.BOLD + NCurses.ColorAttr( "red", -1 ),
>                           true, "+",
>                           NCurses.ColorAttr( "red", -1 ), false ] ] ),
>      sortParameters:= [ "add counter on categorizing", "yes" ],
>      align:= "c",
>      categoryValue:= value -> BrowseData.ReplacedEntry( value,
>          [ 0, 1, 2 ],
>          [ "not prime power", "prime power, not prime", "prime" ] ),
>    ) );
gap> t3:= BrowseTableFromDatabaseIdEnumerator( smallintenum2,
>           [ "self" ],
>           [ "primes & prime powers", "residue mod 11",
>             "inverse factorial" ],
>           t -> BrowseData.HeaderWithRowCounter( t, "Small integers", n ) );;
gap> sample_session2:= Concatenation(
>         # categorize by the first column, expand categories, wait, reset
>         nop, "scsc", nop, "X", nop, "!", "Q" );;
gap> BrowseData.SetReplay( sample_session2 );
gap> NCurses.BrowseGeneric( t3 );
gap> BrowseData.SetReplay( false );
gap> Unbind( t3.dynamic.replay );

Now we want to consider the database as extendible, that is, we want to be able to increase n after constructing the database attributes. For that, we use n as the version value of the database id enumerator, and provide version and update components for all attributes.

Again, we start the construction from scratch.

gap> smallintenum3:= DatabaseIdEnumerator( rec(
>     identifiers:= [ 1 .. n ],
>     entry:= function( dbidenum, id ) return id; end,
>     viewLabel:= "",
>     version:= n,
>     update:= function( dbidenum )
>         dbidenum.identifiers:= [ 1 .. n ];
>         dbidenum.version:= n;
>         return true;
>       end,
>     ) );;
gap> updateByUnbindData:= function( attr )
>      Unbind( attr.data );
>      return true;
>    end;;
gap> DatabaseAttributeAdd( smallintenum3, rec(
>     identifier:= "primes",
>     type:= "values",
>     name:= "IsPrimeInt",
>     viewLabel:= "prime?",
>     viewValue:= value -> BrowseData.ReplacedEntry( value,
>         [ true, false ], [ "+", "-" ] ),
>     sortParameters:= [ "add counter on categorizing", "yes" ],
>     align:= "c",
>     categoryValue:= value -> BrowseData.ReplacedEntry( value,
>         [ true, false ], [ "prime", "nonprime" ] ),
>     version:= n,
>     update:= updateByUnbindData,
>     ) );
gap> DatabaseAttributeAdd( smallintenum3, rec(
>     identifier:= "prime powers",
>     type:= "values",
>     name:= "IsPrimePowerInt",
>     viewLabel:= "prime power?",
>     viewValue:= value -> BrowseData.ReplacedEntry( value,
>         [ true, false ], [ "+", "-" ] ),
>     sortParameters:= [ "add counter on categorizing", "yes" ],
>     align:= "c",
>     categoryValue:= value -> BrowseData.ReplacedEntry( value,
>         [ true, false ], [ "prime power", "not prime power" ] ),
>     version:= n,
>     update:= updateByUnbindData,
>     ) );
gap> DatabaseAttributeAdd( smallintenum3, rec(
>     identifier:= "factors",
>     type:= "values",
>     name:= "Factors",
>     viewLabel:= "factors",
>     viewValue:= value -> JoinStringsWithSeparator( List( value, String ),
>                                                    " * "),
>     widthCol:= 10,
>     version:= n,
>     update:= updateByUnbindData,
>     ) );
gap> DatabaseAttributeAdd( smallintenum3, rec(
>     identifier:= "residue mod 11",
>     type:= "values",
>     create:= function( attr, id ) return id mod 11; end,
>     viewSort:= BrowseData.SortAsIntegers,
>     categoryValue:= res -> Concatenation( String( res ), " mod 11" ),
>     version:= n,
>     update:= updateByUnbindData,
>     ) );
gap> DatabaseAttributeAdd( smallintenum3, rec(
>     identifier:= "inverse factorial",
>     type:= "pairs",
>     data:= rec( automatic:= factorialdata( n ), nonautomatic:= [] ),
>     isSorted:= true,
>     categoryValue:= function( k )
>       if k = "" then
>         return "(no factorial)";
>       else
>         return Concatenation( String( k ), "!" );
>       fi;
>     end,
>     version:= n,
>     update:= function( attr )
>         attr.data.automatic:= factorialdata( n );
>         return true;
>       end,
>     ) );

Now we can change the set of database entries by assigning a new value to the variable n, and then calling DatabaseIdEnumeratorUpdate (A.1-7).

gap> n:= 200;;
gap> DatabaseIdEnumeratorUpdate( smallintenum3 );
true
gap> t4:= BrowseTableFromDatabaseIdEnumerator( smallintenum3,
>   [ "self" ], [ "primes", "prime powers", "factors", "residue mod 11",
>     "inverse factorial" ],
>   t -> BrowseData.HeaderWithRowCounter( t, "Small integers", n ) );;
gap> BrowseData.SetReplay( sample_session );
gap> NCurses.BrowseGeneric( t4 );
gap> BrowseData.SetReplay( false );
gap> Unbind( t4.dynamic.replay );

A.4 Example: An Overview of the GAP Library of Tables of Marks

The example shown in this section deals with GAP's Library of Tables of Marks (the TomLib package [NMP13]).

A.4-1 BrowseTomLibInfo
‣ BrowseTomLibInfo( )( function )

Returns: nothing.

This function shows the contents of the GAP Library of Tables of Marks (the TomLib package, see [NMP13]) in a browse table.

The first call may take substantial time (about 40 seconds), because the data files of the TomLib package are evaluated. This could be improved by precomputing and caching the values. Another possibility would be to call BrowseTomLibInfo once before creating a GAP workspace. The subsequent calls are not expensive.

The table rows correspond to the tables of marks, one column of row labels shows the identifier of the table. The columns of the table contain information about the group order, the number of conjugacy classes of subgroups, the identifiers of tables of marks with fusions to and from the given table, and the name of the file that contains the table of marks data.

The full functionality of the function NCurses.BrowseGeneric (4.3-1) is available.

gap> c:= [ NCurses.keys.ENTER ];;
gap> n:= [ 14, 14, 14 ];;  # ``do nothing''
gap> BrowseData.SetReplay( Concatenation(
>        "scrrsc",   # categorize the list by source tables of fusions,
>        "srdd",     # choose a source table,
>        "x",        # expand the list of targets of fusions
>        n,
>        "!",        # revert the categorization
>        "q",        # leave the mode in which a row is selected
>        "scrrrrsc", # categorize the list by filenames
>        "X",        # expand all categories
>        n,
>        "!",        # revert the categorization
>        "scso",     # sort the list by group order
>        n,
>        "!q",       # revert the sorting and selection
>        "?",        # open the help window
>        n,
>        "Q",        # close the help window
>        "/A5", c,   # search for the first occurrence of "A5"
>        n,
>        "Q" ) );;   # and quit the browse table
gap> BrowseTomLibInfo();
gap> BrowseData.SetReplay( false );
 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 
Goto Chapter: Top 1 2 3 4 5 6 A Bib Ind

generated by GAPDoc2HTML