chapA.txt

  
  A Some Tools for Database Handling
  
  Two aims of the tools described in this appendix are
  
      speeding   up   selection  functions  such  as  AllCharacterTableNames
        (CTblLib:  AllCharacterTableNames)  for  certain data libraries of GAP
        (with  not  too  many entries), in the sense that users can extend the
        list of attributes that are treated in a special way
  
      and  a  programmatic  extension for rendering overviews of information
        about        the        contents       of       databases,       using
        BrowseTableFromDatabaseIdEnumerator (A.2-2).
  
  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.
  
    Example  
    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.
  
    Example  
    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.
  
    Example  
    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.
  
    Example  
    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.)
  
    Example  
    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.
  
    Example  
    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.
  
    Example  
    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.
  
      The  strings  "true" and "false" shown for the Boolean valued database
        attributes  can be replaced by the perhaps more suggestive strings "+"
        and "-" (or perhaps an empty string instead of "-").
  
      The alignment of values inside their columns can be customized.
  
      When  the  browse  table is categorized by a column then the values in
        this  column  do  usually  not  provide suitable category rows; we can
        prescribe individual category values.
  
      The column labels can be customized.
  
      Where  the  lexicographic  order  is not appropriate for sorting table
        entries, we can prescribe an individual comparison function.
  
      Sort parameters can be customized.
  
      We  can  prescribe  the  width  of  a  column, and thus distribute the
        attribute  values  for this column to several rows when the values are
        too long.
  
      Finally,  in  the call of BrowseTableFromDatabaseIdEnumerator (A.2-2),
        we can add a header to the browse table.
  
  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.
  
    Example  
    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.
  
    Example  
    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.)
  
    Example  
    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.
  
    Example  
    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).
  
    Example  
    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.
  
    Example  
    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 );