<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>GAP (Browse) - Appendix A: Some Tools for Database Handling</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="generator" content="GAPDoc2HTML" />
<link rel="stylesheet" type="text/css" href="manual.css" />
</head>
<body>
<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a> <a href="chap1.html">1</a> <a href="chap2.html">2</a> <a href="chap3.html">3</a> <a href="chap4.html">4</a> <a href="chap5.html">5</a> <a href="chap6.html">6</a> <a href="chapA.html">A</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<div class="chlinkprevnexttop"> <a href="chap0.html">Top of Book</a> <a href="chap6.html">Previous Chapter</a> <a href="chapBib.html">Next Chapter</a> </div>
<p><a id="X85D4199E82A7DFA5" name="X85D4199E82A7DFA5"></a></p>
<div class="ChapSects"><a href="chapA.html#X85D4199E82A7DFA5">A <span class="Heading">Some Tools for Database Handling</span></a>
<div class="ContSect"><span class="nocss"> </span><a href="chapA.html#X17A0B84C317CB9DFA3">A.1 <span class="Heading"><strong class="pkg">GAP</strong> Objects for Database Handling</span></a>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chapA.html#X17999CF7F179ACA240">A.1-1 <span class="Heading">Database Id Enumerators</span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chapA.html#X17D2804F917EE18BA5">A.1-2 <span class="Heading">Database Attributes</span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chapA.html#X17B3913E28493563F">A.1-3 <span class="Heading">How to Deal with Database Id Enumerators and
Database Attributes</span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chapA.html#X17AE32F2117CF16EDF">A.1-4 DatabaseIdEnumerator</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chapA.html#X8573522782D939FE">A.1-5 DatabaseAttributeAdd</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chapA.html#X17C8DB23E179567A60">A.1-6 DatabaseAttributeValueDefault</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chapA.html#X80A9097217E3C8311">A.1-7 DatabaseIdEnumeratorUpdate</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chapA.html#X812075CE17A01EA04">A.1-8 DatabaseAttributeCompute</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chapA.html#X87A8B19C82E9FF0B">A.1-9 DatabaseAttributeSetData</a></span>
</div>
<div class="ContSect"><span class="nocss"> </span><a href="chapA.html#X80E9CFA117EE7817A">A.2 <span class="Heading">Using Database Attributes for Browse Tables</span></a>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chapA.html#X17A2DD78217CBBD735">A.2-1 <span class="Heading">Browse Relevant Components of Database Attributes</span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chapA.html#X17F25A3E586653911">A.2-2 BrowseTableFromDatabaseIdEnumerator</a></span>
</div>
<div class="ContSect"><span class="nocss"> </span><a href="chapA.html#X808BDD24857F3904">A.3 <span class="Heading">Example: Database Id Enumerators and Database Attributes</span></a>
</div>
<div class="ContSect"><span class="nocss"> </span><a href="chapA.html#X81A5F37B81E0968C">A.4 <span class="Heading">Example: An Overview of the <strong class="pkg">GAP</strong> Library of Transitive Groups
</span></a>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chapA.html#X832846F486391385">A.4-1 BrowseTransitiveGroupsInfo</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chapA.html#X17FA5513D84EE81AB">A.4-2 TransitiveGroupsData.AllTransitiveGroups</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chapA.html#X17AC0308217D5CDE03">A.4-3 TransitiveGroupsData</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chapA.html#X83E9FAAE85F80223">A.4-4 <span class="Heading">Additional Database Attributes for Transitive Groups</span></a>
</span>
</div>
</div>
<h3>A <span class="Heading">Some Tools for Database Handling</span></h3>
<p>Two aims of the tools described in this appendix are</p>
<ul>
<li><p>speeding up selection functions such as <code class="func">AllCharacterTableNames</code> (<a href="../../../pkg/ctbllib/htm/CHAP002.htm#SECT002"><b>CTblLib: AllCharacterTableNames</b></a>) for certain data libraries of <strong class="pkg">GAP</strong> (with not too many entries), in the sense that users can extend the list of attributes that are treated in a special way</p>
</li>
<li><p>and a programmatic extension for rendering overviews of information about the contents of databases, using <code class="func">BrowseTableFromDatabaseIdEnumerator</code> (<a href="chapA.html#X17F25A3E586653911"><b>A.2-2</b></a>).</p>
</li>
</ul>
<p>The <strong class="pkg">GAP</strong> objects introduced for that are <em>database id enumerators</em> (see <a href="chapA.html#X17999CF7F179ACA240"><b>A.1-1</b></a>) and <em>database attributes</em> (see <a href="chapA.html#X17D2804F917EE18BA5"><b>A.1-2</b></a>).</p>
<p>Contrary to the individual interfaces to the <strong class="pkg">GAP</strong> manuals (see Section <a href="chap6.html#X17CF9992917B331E01"><b>6.5</b></a>), the <strong class="pkg">GAP</strong> bibliography (see Section <a href="chap6.html#X17CD8EEF2179F984D2"><b>6.6</b></a>), and the overviews of <strong class="pkg">GAP</strong> packages, <strong class="pkg">GAP</strong> methods, and Conway polynomials available in <strong class="pkg">GAP</strong> (see Section <a href="chap6.html#X86C730A017855238D"><b>6.7</b></a>), 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 examples shown in Sections <a href="chapA.html#X808BDD24857F3904"><b>A.3</b></a> and <a href="chapA.html#X81A5F37B81E0968C"><b>A.4</b></a> give an impression what is possible.</p>
<p><a id="X17A0B84C317CB9DFA3" name="X17A0B84C317CB9DFA3"></a></p>
<h4>A.1 <span class="Heading"><strong class="pkg">GAP</strong> Objects for Database Handling</span></h4>
<p><a id="X17999CF7F179ACA240" name="X17999CF7F179ACA240"></a></p>
<h5>A.1-1 <span class="Heading">Database Id Enumerators</span></h5>
<p>A <em>database id enumerator</em> is a record <var class="Arg">r</var> with at least the following components.</p>
<dl>
<dt><strong class="Mark"><code class="code">identifiers</code></strong></dt>
<dd><p>a list of "identifiers" of the database entries, which provides a bijection with these entries,</p>
</dd>
<dt><strong class="Mark"><code class="code">entry</code></strong></dt>
<dd><p>a function that takes <var class="Arg">r</var> and an entry in the <code class="code">identifiers</code> list, and returns the corresponding database entry,</p>
</dd>
<dt><strong class="Mark"><code class="code">attributes</code></strong></dt>
<dd><p>the record whose components are the database attribute records (see Section <a href="chapA.html#X17D2804F917EE18BA5"><b>A.1-2</b></a>) for <var class="Arg">r</var>; this components is automatically initialized when <var class="Arg">r</var> is created with <code class="func">DatabaseIdEnumerator</code> (<a href="chapA.html#X17AE32F2117CF16EDF"><b>A.1-4</b></a>); database attributes can be entered with <code class="func">DatabaseAttributeAdd</code> (<a href="chapA.html#X8573522782D939FE"><b>A.1-5</b></a>).</p>
</dd>
</dl>
<p>If the <code class="code">identifiers</code> list may change over the time (because the database is extended or corrected) then the following components are supported. They are used by <code class="func">DatabaseIdEnumeratorUpdate</code> (<a href="chapA.html#X80A9097217E3C8311"><b>A.1-7</b></a>).</p>
<dl>
<dt><strong class="Mark"><code class="code">version</code></strong></dt>
<dd><p>a <strong class="pkg">GAP</strong> object that describes the version of the <code class="code">identifiers</code> 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 <code class="code">identifiers</code> component is never changed) is an empty string,</p>
</dd>
<dt><strong class="Mark"><code class="code">update</code></strong></dt>
<dd><p>a function that takes <var class="Arg">r</var> as its argument, replaces its <code class="code">identifiers</code> and <code class="code">version</code> values by up-to-date versions if necessary (for example by downloading the data), and returns <code class="keyw">true</code> or <code class="keyw">false</code>, depending on whether the update process was successful or not; the default value is <code class="func">ReturnTrue</code> (<a href="../../../doc/ref/chap5.html#X17DB422A2876CCC4D"><b>Reference: ReturnTrue</b></a>),</p>
</dd>
</dl>
<p>The following component is optional.</p>
<dl>
<dt><strong class="Mark"><code class="code">isSorted</code></strong></dt>
<dd><p><code class="keyw">true</code> means that the <code class="code">identifiers</code> list is sorted w.r.t. <strong class="pkg">GAP</strong>'s ordering <code class="code">\<</code>; the default is <code class="keyw">false</code>.</p>
</dd>
</dl>
<p>The idea behind database id enumerator objects is that such an object defines the set of data covered by database attributes (see Section <a href="chapA.html#X17D2804F917EE18BA5"><b>A.1-2</b></a>), it provides the mapping between identifiers and the actual entries of the database, and it defines when precomputed data of database attributes are outdated.</p>
<p><a id="X17D2804F917EE18BA5" name="X17D2804F917EE18BA5"></a></p>
<h5>A.1-2 <span class="Heading">Database Attributes</span></h5>
<p>A <em>database attribute</em> is a record <var class="Arg">a</var> whose components belong to the aspects of <em>defining</em> the attribute, <em>accessing</em> the attribute's data, <em>computing</em> (and recomputing) data, <em>storing</em> data on files, and <em>checking</em> data. (Additional parameters used for creating browse table columns from database attributes are described in Section <a href="chapA.html#X17A2DD78217CBBD735"><b>A.2-1</b></a>.)</p>
<p>The following components are <em>defining</em>, except <code class="code">description</code> they are mandatory.</p>
<dl>
<dt><strong class="Mark"><code class="code">idenumerator</code></strong></dt>
<dd><p>the database id enumerator to which the attribute <var class="Arg">a</var> is related,</p>
</dd>
<dt><strong class="Mark"><code class="code">identifier</code></strong></dt>
<dd><p>a string that identifies <var class="Arg">a</var> among all database attributes for the underlying database id enumerator (this is used by <code class="func">BrowseTableFromDatabaseIdEnumerator</code> (<a href="chapA.html#X17F25A3E586653911"><b>A.2-2</b></a>) and when the data of <var class="Arg">a</var> are entered with <code class="func">DatabaseAttributeSetData</code> (<a href="chapA.html#X87A8B19C82E9FF0B"><b>A.1-9</b></a>), for example when precomputed values are read from a file),</p>
</dd>
<dt><strong class="Mark"><code class="code">description</code></strong></dt>
<dd><p>a string that describes the attribute in human readable form (currently just for convenience, the default is an empty string).</p>
</dd>
</dl>
<p>The following components are used for <em>accessing</em> data. Except <code class="code">type</code>, they are optional, but enough information must be provided in order to make the database attribute meaningful. If an individual <code class="code">attributeValue</code> function is available then this function decides what is needed; for the default function <code class="func">DatabaseAttributeValueDefault</code> (<a href="chapA.html#X17C8DB23E179567A60"><b>A.1-6</b></a>), at least one of the components <code class="code">name</code>, <code class="code">data</code>, <code class="code">datafile</code> must be bound (see <code class="func">DatabaseAttributeValueDefault</code> (<a href="chapA.html#X17C8DB23E179567A60"><b>A.1-6</b></a>) for the behaviour in this case).</p>
<dl>
<dt><strong class="Mark"><code class="code">type</code></strong></dt>
<dd><p>one of the strings <code class="code">"values"</code> or <code class="code">"pairs"</code>; the format of the component <code class="code">data</code> is different for these cases,</p>
</dd>
<dt><strong class="Mark"><code class="code">name</code></strong></dt>
<dd><p>if bound, a string that is the name of a <strong class="pkg">GAP</strong> 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 <code class="func">DatabaseAttributeValueDefault</code> (<a href="chapA.html#X17C8DB23E179567A60"><b>A.1-6</b></a>)), this component can be used by selection functions such as <code class="func">OneCharacterTableName</code> (<a href="../../../pkg/ctbllib/htm/CHAP002.htm#SECT002"><b>CTblLib: OneCharacterTableName</b></a>) or <code class="func">AllCharacterTableNames</code> (<a href="../../../pkg/ctbllib/htm/CHAP002.htm#SECT002"><b>CTblLib: AllCharacterTableNames</b></a>), which take <strong class="pkg">GAP</strong> functions and prescribed return values as their arguments –of course these functions must then be prepared to deal with database attributes.</p>
</dd>
<dt><strong class="Mark"><code class="code">data</code></strong></dt>
<dd><p>if bound, the data for this attribute; if the component <code class="code">type</code> has the value <code class="code">"values"</code> then the value is a list, where the entry at position <var class="Arg">i</var>, if bound, belongs to the <var class="Arg">i</var>-th entry of the <code class="code">identifiers</code> list of <code class="code">idenumerator</code>; if <code class="code">type</code> is <code class="code">"pairs"</code> then the value is a record with the components <code class="code">automatic</code> and <code class="code">nonautomatic</code>, and the values of these components are lists such that each entry is a list of length two whose first entry occurs in the <code class="code">identifiers</code> list of <var class="Arg">a</var><code class="code">.idenumerator</code> and whose second entry encodes the corresponding attribute value,</p>
</dd>
<dt><strong class="Mark"><code class="code">datafile</code></strong></dt>
<dd><p>if bound, the absolute name of a file that contains the data for this attribute,</p>
</dd>
<dt><strong class="Mark"><code class="code">attributeValue</code></strong></dt>
<dd><p>a function that takes <var class="Arg">a</var> and an <code class="code">identifiers</code> entry of its <code class="code">idenumerator</code> value, and returns the attribute value for this identifier; typically this is <em>not</em> a table cell data object that can be shown in a browse table, cf. the <code class="code">viewValue</code> component; the default is <code class="func">DatabaseAttributeValueDefault</code> (<a href="chapA.html#X17C8DB23E179567A60"><b>A.1-6</b></a>) (Note that using individual <code class="code">attributeValue</code> functions, one can deal with database attributes independent of actually stored date, for example without precomputed values, such that the values are computed on demand and afterwards are cached.),</p>
</dd>
<dt><strong class="Mark"><code class="code">dataDefault</code></strong></dt>
<dd><p>a <strong class="pkg">GAP</strong> object that is regarded as the attribute value for those database entries for which <code class="code">data</code>, <code class="code">datafile</code>, and <code class="code">name</code> do not provide values; the default value is an empty string <code class="code">""</code>,</p>
</dd>
<dt><strong class="Mark"><code class="code">eval</code></strong></dt>
<dd><p>if this component is bound, the value is assumed to be a function that takes <var class="Arg">a</var> and a value from its <code class="code">data</code> 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 <code class="code">eval</code> component is that it may be used to strip off comments that are perhaps contained in <code class="code">data</code> entries,</p>
</dd>
<dt><strong class="Mark"><code class="code">isSorted</code></strong></dt>
<dd><p>if this component is bound to <code class="keyw">true</code> and if <code class="code">type</code> is <code class="code">"pairs"</code> then it is assumed that the two lists in the <code class="code">data</code> record of <var class="Arg">a</var> are sorted w.r.t. <strong class="pkg">GAP</strong>'s ordering <code class="code">\<</code>; the default is <code class="keyw">false</code>,</p>
</dd>
</dl>
<p>The following optional components are needed for <em>computing</em> (or recomputing) data with <code class="func">DatabaseAttributeCompute</code> (<a href="chapA.html#X812075CE17A01EA04"><b>A.1-8</b></a>). This is useful mainly for databases which can change over the time.</p>
<dl>
<dt><strong class="Mark"><code class="code">version</code></strong></dt>
<dd><p>the <strong class="pkg">GAP</strong> object that is the <code class="code">version</code> component of the <code class="code">idenumerator</code> component at the time when the stored data were entered; this value is used by <code class="func">DatabaseIdEnumeratorUpdate</code> (<a href="chapA.html#X80A9097217E3C8311"><b>A.1-7</b></a>) for deciding whether the attribute values are outdated; if <var class="Arg">a</var><code class="code">.datafile</code> is bound then it is assumed that the <code class="code">version</code> component is set when this file is read, for example in the function <code class="func">DatabaseAttributeSetData</code> (<a href="chapA.html#X87A8B19C82E9FF0B"><b>A.1-9</b></a>),</p>
</dd>
<dt><strong class="Mark"><code class="code">update</code></strong></dt>
<dd><p>a function that takes <var class="Arg">a</var> as its argument, adjusts its data components to the current values of <var class="Arg">a</var><code class="code">.dbidenum</code> if necessary, sets the <code class="code">version</code> component to that of <var class="Arg">a</var><code class="code">.dbidenum</code>, and returns <code class="keyw">true</code> or <code class="keyw">false</code>, depending on whether the update process was successful or not; the default value is <code class="func">ReturnTrue</code> (<a href="../../../doc/ref/chap5.html#X17DB422A2876CCC4D"><b>Reference: ReturnTrue</b></a>),</p>
</dd>
<dt><strong class="Mark"><code class="code">neededAttributes</code></strong></dt>
<dd><p>a list of attribute <code class="code">identifier</code> 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 <code class="code">neededAttributes</code> components of all database attributes of <var class="Arg">a</var><code class="code">.idenumerator</code> define a partial ordering; the default is an empty list,</p>
</dd>
<dt><strong class="Mark"><code class="code">prepareAttributeComputation</code></strong></dt>
<dd><p>a function with argument <var class="Arg">a</var> that must be called before the computations for the current attribute are started; the default value is <code class="func">ReturnTrue</code> (<a href="../../../doc/ref/chap5.html#X17DB422A2876CCC4D"><b>Reference: ReturnTrue</b></a>),</p>
</dd>
<dt><strong class="Mark"><code class="code">cleanupAfterAttibuteComputation</code></strong></dt>
<dd><p>a function with argument <var class="Arg">a</var> that must be called after the computations for the current attribute are finished; the default value is <code class="func">ReturnTrue</code> (<a href="../../../doc/ref/chap5.html#X17DB422A2876CCC4D"><b>Reference: ReturnTrue</b></a>), and</p>
</dd>
<dt><strong class="Mark"><code class="code">create</code></strong></dt>
<dd><p>a function that takes a database attribute and an entry in the <code class="code">identifiers</code> list of its database id enumerator, and returns either the entry that shall be stored in the <code class="code">data</code> component, as the value for the given identifier (if this value shall be stored in the <code class="code">data</code> component of <var class="Arg">a</var>) or the <code class="code">dataDefault</code> component of <var class="Arg">a</var> (if this value shall <em>not</em> be stored); in order to get the actual attribute value, the <code class="code">eval</code> function of <var class="Arg">a</var>, if bound, must be called with the return value. This function may assume that the <code class="code">prepareAttributeComputation</code> function has been called in advance, and that the <code class="code">cleanupAfterAttibuteComputation</code> function will be called later. The <code class="code">create</code> function is <em>not</em> intended to compute an individual attribute value on demand, use a <code class="code">name</code> component for that. (A stored <code class="code">name</code> function is used to provide a default for the <code class="code">create</code> function; without <code class="code">name</code> component, there is no default for <code class="code">create</code>.)</p>
</dd>
</dl>
<p>The following optional component is needed for <em>storing</em> data on files.</p>
<dl>
<dt><strong class="Mark"><code class="code">string</code></strong></dt>
<dd><p>if bound, a function that takes the pair consisting of an identifier and the return value of the <code class="code">create</code> 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 <code class="func">String</code> (<a href="../../../doc/ref/chap25.html#X81FB5BE217903EC32"><b>Reference: String</b></a>) value of the second argument.</p>
</dd>
</dl>
<p>The following optional component is needed for <em>checking</em> stored data.</p>
<dl>
<dt><strong class="Mark"><code class="code">check</code></strong></dt>
<dd><p>a function that takes a string that occurs in the <code class="code">identifiers</code> list of the <code class="code">idenumerator</code> record, and returns <code class="keyw">true</code> if the attribute value stored for this string is reasonable, and something different from <code class="keyw">true</code> 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.)</p>
</dd>
</dl>
<p><a id="X17B3913E28493563F" name="X17B3913E28493563F"></a></p>
<h5>A.1-3 <span class="Heading">How to Deal with Database Id Enumerators and
Database Attributes</span></h5>
<p>The idea is to start with a database id enumerator (see <a href="chapA.html#X17999CF7F179ACA240"><b>A.1-1</b></a>), constructed with <code class="func">DatabaseIdEnumerator</code> (<a href="chapA.html#X17AE32F2117CF16EDF"><b>A.1-4</b></a>), and to define database attributes for it (see <a href="chapA.html#X17D2804F917EE18BA5"><b>A.1-2</b></a>), using <code class="func">DatabaseAttributeAdd</code> (<a href="chapA.html#X8573522782D939FE"><b>A.1-5</b></a>). 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.</p>
<p>The function <code class="func">DatabaseAttributeCompute</code> (<a href="chapA.html#X812075CE17A01EA04"><b>A.1-8</b></a>) 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.</p>
<p>In data files, the function <code class="func">DatabaseAttributeSetData</code> (<a href="chapA.html#X87A8B19C82E9FF0B"><b>A.1-9</b></a>) can be used to fill the <code class="code">data</code> component of the attribute.</p>
<p><a id="X17AE32F2117CF16EDF" name="X17AE32F2117CF16EDF"></a></p>
<h5>A.1-4 DatabaseIdEnumerator</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> DatabaseIdEnumerator</code>( <var class="Arg">arec</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>a shallow copy of the record <var class="Arg">arec</var>, extended by default values.</p>
<p>For a record <var class="Arg">arec</var>, <code class="func">DatabaseIdEnumerator</code> checks whether the mandatory components of a database id enumerator (see Section <a href="chapA.html#X17999CF7F179ACA240"><b>A.1-1</b></a>) are present, initializes the <code class="code">attributes</code> component, sets the defaults for unbound optional components (see <a href="chapA.html#X17A2DD78217CBBD735"><b>A.2-1</b></a>), and returns the resulting record.</p>
<p>A special database attribute (see Section <a href="chapA.html#X17D2804F917EE18BA5"><b>A.1-2</b></a>) with <code class="code">identifier</code> value <code class="code">"self"</code> is constructed automatically for the returned record by <code class="func">DatabaseIdEnumerator</code>; its <code class="code">attributeValue</code> 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 href="chapA.html#X17A2DD78217CBBD735"><b>A.2-1</b></a>) are supported for <var class="Arg">arec</var>. A typical use of the <code class="code">"self"</code> attribute is to provide the first column in browse tables constructed by <code class="func">BrowseTableFromDatabaseIdEnumerator</code> (<a href="chapA.html#X17F25A3E586653911"><b>A.2-2</b></a>).</p>
<p><a id="X8573522782D939FE" name="X8573522782D939FE"></a></p>
<h5>A.1-5 DatabaseAttributeAdd</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> DatabaseAttributeAdd</code>( <var class="Arg">dbidenum, arec</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>For a database id enumerator <var class="Arg">dbidenum</var> and a record <var class="Arg">arec</var>, <code class="func">DatabaseAttributeAdd</code> checks whether the mandatory components of a database attribute, except <code class="code">idenumerator</code>, are present in <var class="Arg">arec</var> (see Section <a href="chapA.html#X17D2804F917EE18BA5"><b>A.1-2</b></a>), sets the <code class="code">idenumerator</code> component, and sets the defaults for unbound optional components (see <a href="chapA.html#X17A2DD78217CBBD735"><b>A.2-1</b></a>).</p>
<p><a id="X17C8DB23E179567A60" name="X17C8DB23E179567A60"></a></p>
<h5>A.1-6 DatabaseAttributeValueDefault</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> DatabaseAttributeValueDefault</code>( <var class="Arg">attr, id</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>the value of the database attribute <var class="Arg">attr</var> at <var class="Arg">id</var>.</p>
<p>For a database attribute <var class="Arg">attr</var> and an entry <var class="Arg">id</var> of the <code class="code">identifiers</code> list of the underlying database id enumerator, <code class="func">DatabaseAttributeValueDefault</code> takes the <code class="code">data</code> entry for <var class="Arg">id</var>, applies the <code class="code">eval</code> function of <var class="Arg">attr</var> to it if available and returns the result.</p>
<p>So the question is how to get the <code class="code">data</code> entry.</p>
<p>First, if the <code class="code">data</code> component of <var class="Arg">attr</var> is not bound then the file given by the <code class="code">datafile</code> component of <var class="Arg">attr</var>, if available, is read, and otherwise <code class="func">DatabaseAttributeCompute</code> (<a href="chapA.html#X812075CE17A01EA04"><b>A.1-8</b></a>) is called; afterwards it is assumed that the <code class="code">data</code> component is bound.</p>
<p>The further steps depend on the <code class="code">type</code> value of <var class="Arg">attr</var>.</p>
<p>If the <code class="code">type</code> value of <var class="Arg">attr</var> is <code class="code">"pairs"</code> then the <code class="code">data</code> entry for <var class="Arg">id</var> is either contained in the <code class="code">automatic</code> or in the <code class="code">nonautomatic</code> list of <var class="Arg">attr</var><code class="code">.data</code>, or it is given by the <code class="code">dataDefault</code> value of <var class="Arg">attr</var>. (So a perhaps available <code class="code">name</code> function is <em>not</em> used to compute the value for a missing <code class="code">data</code> entry.)</p>
<p>If the <code class="code">type</code> value of <var class="Arg">attr</var> is <code class="code">"values"</code> then the <code class="code">data</code> entry for <var class="Arg">id</var> is computed as follows. Let n be the position of <var class="Arg">id</var> in the <code class="code">identifiers</code> component of the database id enumerator. If the n-th entry of the <code class="code">data</code> component of <var class="Arg">attr</var> is bound then take it; otherwise if the <code class="code">name</code> component is bound then apply it to <var class="Arg">id</var> and take the return value; otherwise take the <code class="code">dataDefault</code> value.</p>
<p>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 <code class="code">attributeValue</code> of such an attribute.</p>
<p><a id="X80A9097217E3C8311" name="X80A9097217E3C8311"></a></p>
<h5>A.1-7 DatabaseIdEnumeratorUpdate</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> DatabaseIdEnumeratorUpdate</code>( <var class="Arg">dbidenum</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b><code class="keyw">true</code> or <code class="keyw">false</code>.</p>
<p>For a database id enumerator <var class="Arg">dbidenum</var> (see Section <a href="chapA.html#X17999CF7F179ACA240"><b>A.1-1</b></a>), <code class="func">DatabaseIdEnumeratorUpdate</code> first calls the <code class="code">update</code> function of <var class="Arg">dbidenum</var>. Afterwards, the <code class="code">update</code> components of those of its <code class="code">attributes</code> records are called for which the <code class="code">version</code> component differs from that of <var class="Arg">dbidenum</var>.</p>
<p>The order in which the database attributes are updates is determined by the <code class="code">neededAttributes</code> component.</p>
<p>The return value is <code class="keyw">true</code> if all these functions return <code class="keyw">true</code>, and <code class="keyw">false</code> otherwise.</p>
<p>When <code class="func">DatabaseIdEnumeratorUpdate</code> has returned <code class="keyw">true</code>, the data described by <var class="Arg">dbidenum</var> and its database attributes are consistent and up to date.</p>
<p><a id="X812075CE17A01EA04" name="X812075CE17A01EA04"></a></p>
<h5>A.1-8 DatabaseAttributeCompute</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> DatabaseAttributeCompute</code>( <var class="Arg">dbidenum, attridentifier</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b><code class="keyw">true</code> or <code class="keyw">false</code>.</p>
<p>This function returns <code class="keyw">false</code> if <var class="Arg">dbidenum</var> is not a database id enumerator, or if it does not have a database attribute with <code class="code">identifier</code> value <var class="Arg">attridentifier</var>, or if this attribute does not have a <code class="code">create</code> function.</p>
<p>Otherwise the <code class="code">prepareAttributeComputation</code> function is called, the <code class="code">data</code> entries for the database attribute are (re)computed, the <code class="code">cleanupAfterAttibuteComputation</code> function is called, and <code class="keyw">true</code> is returned.</p>
<p>If the <code class="code">type</code> value of the database attribute is <code class="code">"pairs"</code> then only the values of the <code class="code">data.automatic</code> list are recomputed, the <code class="code">data.nonautomatic</code> list is left unchanged. If the <code class="code">type</code> value is <code class="code">"values"</code> then all values are recomputed.</p>
<p><a id="X87A8B19C82E9FF0B" name="X87A8B19C82E9FF0B"></a></p>
<h5>A.1-9 DatabaseAttributeSetData</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> DatabaseAttributeSetData</code>( <var class="Arg">dbidenum, attridentifier, version, data</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Let <var class="Arg">dbidenum</var> be a database id enumerator (see Section <a href="chapA.html#X17999CF7F179ACA240"><b>A.1-1</b></a>), <var class="Arg">attridentifier</var> be a string that is the <code class="code">identifier</code> value of a database attribute of <var class="Arg">dbidenum</var>, <var class="Arg">data</var> be the <code class="code">data</code> list or record for the database attribute (depending on its <code class="code">type</code> value), and <var class="Arg">version</var> be the corresponding <code class="code">version</code> value.</p>
<p><code class="func">DatabaseAttributeSetData</code> sets the <code class="code">data</code> and <code class="code">version</code> components of the attribute. This function can be used for example in data files.</p>
<p><a id="X80E9CFA117EE7817A" name="X80E9CFA117EE7817A"></a></p>
<h4>A.2 <span class="Heading">Using Database Attributes for Browse Tables</span></h4>
<p><a id="X17A2DD78217CBBD735" name="X17A2DD78217CBBD735"></a></p>
<h5>A.2-1 <span class="Heading">Browse Relevant Components of Database Attributes</span></h5>
<p>The following optional components of database id enumerators and database attributes are used by <code class="func">BrowseTableFromDatabaseIdEnumerator</code> (<a href="chapA.html#X17F25A3E586653911"><b>A.2-2</b></a>).</p>
<dl>
<dt><strong class="Mark"><code class="code">viewLabel</code></strong></dt>
<dd><p>if bound, a table cell data object (see <code class="func">BrowseData.IsBrowseTableCellData</code> (<a href="chap4.html#X82157A2684969A5F"><b>4.2-1</b></a>)) that gives a <em>short</em> description of the attribute, which is used as the column label in browse tables created with <code class="func">BrowseTableFromDatabaseIdEnumerator</code> (<a href="chapA.html#X17F25A3E586653911"><b>A.2-2</b></a>); the default for database attributes is the <code class="code">name</code> component, if bound, and otherwise the <code class="code">identifier</code> component; the default for database id enumerators is the string <code class="code">"name"</code>,</p>
</dd>
<dt><strong class="Mark"><code class="code">viewValue</code></strong></dt>
<dd><p>if bound, a function that takes the output of the <code class="code">attributeValue</code> function and returns a table cell data object (see <code class="func">BrowseData.IsBrowseTableCellData</code> (<a href="chap4.html#X82157A2684969A5F"><b>4.2-1</b></a>)) that is used as the entry of the corresponding column in browse tables created with <code class="func">BrowseTableFromDatabaseIdEnumerator</code> (<a href="chapA.html#X17F25A3E586653911"><b>A.2-2</b></a>); the default is <code class="func">String</code> (<a href="../../../doc/ref/chap25.html#X81FB5BE217903EC32"><b>Reference: String</b></a>),</p>
</dd>
<dt><strong class="Mark"><code class="code">viewSort</code></strong></dt>
<dd><p>if bound, a comparison function that takes two database attribute values and returns <code class="keyw">true</code> if the first value is regarded as smaller than the second when the column corresponding to the attribute in the browse table constructed by <code class="func">BrowseTableFromDatabaseIdEnumerator</code> (<a href="chapA.html#X17F25A3E586653911"><b>A.2-2</b></a>) gets sorted, and <code class="keyw">false</code> otherwise; the default is <strong class="pkg">GAP</strong>'s <code class="code">\<</code> operation,</p>
</dd>
<dt><strong class="Mark"><code class="code">sortParameters</code></strong></dt>
<dd><p>if bound, a list in the same format as the last argument of <code class="code">BrowseData.SetSortParameters</code>, which is used for the column corresponding to the attribute in the browse table constructed by <code class="func">BrowseTableFromDatabaseIdEnumerator</code> (<a href="chapA.html#X17F25A3E586653911"><b>A.2-2</b></a>); the default is an empty list,</p>
</dd>
<dt><strong class="Mark"><code class="code">widthCol</code></strong></dt>
<dd><p>if bound, the width of the column in the browse table constructed by <code class="func">BrowseTableFromDatabaseIdEnumerator</code> (<a href="chapA.html#X17F25A3E586653911"><b>A.2-2</b></a>); if a column width is prescribed this way then the function stored in the <code class="code">attributeValue</code> 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,</p>
</dd>
<dt><strong class="Mark"><code class="code">align</code></strong></dt>
<dd><p>if bound, the alignment of the values in the column of the browse table constructed by <code class="func">BrowseTableFromDatabaseIdEnumerator</code> (<a href="chapA.html#X17F25A3E586653911"><b>A.2-2</b></a>); admissible values are substrings of <code class="code">"bclt"</code>, see <code class="func">BrowseData.IsBrowseTableCellData</code> (<a href="chap4.html#X82157A2684969A5F"><b>4.2-1</b></a>); the default is right and vertically centered, but note that if the <code class="code">viewValues</code> function returns a record (see <code class="func">BrowseData.IsBrowseTableCellData</code> (<a href="chap4.html#X82157A2684969A5F"><b>4.2-1</b></a>)) then the alignment prescribed by this record is preferred,</p>
</dd>
<dt><strong class="Mark"><code class="code">categoryValue</code></strong></dt>
<dd><p>if bound, a function that is similar to the <code class="code">viewValue</code> component but may return a different value; for example if the column in the browse table belongs to a property and the <code class="code">viewValue</code> function returns something like <code class="code">"+"</code> or <code class="code">"-"</code>, it may be useful that the category rows show a textual description of the property values; the default value is the <code class="code">viewValue</code> component; if the value is a record then its <code class="code">rows</code> component is taken for forming category rows, if the value is an attribute line (see <code class="func">NCurses.IsAttributeLine</code> (<a href="chap2.html#X81D1FC9217C455AEB"><b>2.2-3</b></a>)) 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 <code class="code">sortParameters</code> value.</p>
</dd>
</dl>
<p><a id="X17F25A3E586653911" name="X17F25A3E586653911"></a></p>
<h5>A.2-2 BrowseTableFromDatabaseIdEnumerator</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> BrowseTableFromDatabaseIdEnumerator</code>( <var class="Arg">dbidenum, labelids, columnids[, header[, footer]]</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>a record that can be used as the input of <code class="func">NCurses.BrowseGeneric</code> (<a href="chap4.html#X85FC163D87FAFD12"><b>4.3-1</b></a>).</p>
<p>For a database id enumerator <var class="Arg">dbidenum</var> (see Section <a href="chapA.html#X17999CF7F179ACA240"><b>A.1-1</b></a>), a list <var class="Arg">labelids</var> and a nonempty list <var class="Arg">columnids</var> of <code class="code">identifier</code> values of database attributes stored in <var class="Arg">dbidenum</var> which are used to provide row label columns and main table columns, <code class="func">BrowseTableFromDatabaseIdEnumerator</code> returns a browse table (see <code class="func">BrowseData.IsBrowseTable</code> (<a href="chap4.html#X81007E2F8552523B"><b>4.2-3</b></a>)) whose columns are given by the values of the specified database attributes.</p>
<p>If the optional arguments <var class="Arg">header</var> and <var class="Arg">footer</var> are given then they must be lists or functions or records such that they are admissible for the <code class="code">header</code> and <code class="code">footer</code> components of the <code class="code">work</code> record of the browse table, see <code class="func">BrowseData.IsBrowseTable</code> (<a href="chap4.html#X81007E2F8552523B"><b>4.2-3</b></a>).</p>
<p><a id="X808BDD24857F3904" name="X808BDD24857F3904"></a></p>
<h4>A.3 <span class="Heading">Example: Database Id Enumerators and Database Attributes</span></h4>
<p>As an example for the functions introduced in this appendix, we introduce the <em>database of small integers</em>. 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.</p>
<table class="example">
<tr><td><pre>
gap> n:= 100;;
gap> smallintenum1:= DatabaseIdEnumerator( rec(
> identifiers:= [ 1 .. n ],
> entry:= function( dbidenum, id ) return id; end,
> ) );;
</pre></td></tr></table>
<p>Examples of attributes for this database are the properties whether or not an integer is a prime or a prime power. There are global <strong class="pkg">GAP</strong> functions <code class="func">IsPrimeInt</code> (<a href="../../../doc/ref/chap14.html#X178FDA44317EDCA70C"><b>Reference: IsPrimeInt</b></a>) and <code class="func">IsPrimePowerInt</code> (<a href="../../../doc/ref/chap14.html#X8443125D17FD6F2A6"><b>Reference: IsPrimePowerInt</b></a>) for computing these properties, so we can define these database attributes via a <code class="code">name</code> component; we choose <code class="code">"values"</code> as the <code class="code">type</code> value, so the values (<code class="keyw">true</code> or <code class="keyw">false</code>) are stored in a list of length n for each of the two database attributes.</p>
<table class="example">
<tr><td><pre>
gap> DatabaseAttributeAdd( smallintenum1, rec(
> identifier:= "primes",
> type:= "values",
> name:= "IsPrimeInt",
> ) );
gap> DatabaseAttributeAdd( smallintenum1, rec(
> identifier:= "prime powers",
> type:= "values",
> name:= "IsPrimePowerInt",
> ) );
</pre></td></tr></table>
<p>Similarly, we consider the prime factors as a database attribute.</p>
<table class="example">
<tr><td><pre>
gap> DatabaseAttributeAdd( smallintenum1, rec(
> identifier:= "factors",
> type:= "values",
> name:= "Factors",
> ) );
</pre></td></tr></table>
<p>Another example of an attribute of integers is the residue modulo 11. We do not want to introduce a global <strong class="pkg">GAP</strong> function for computing the value, so we use the <code class="code">create</code> component in order to define the attribute; again, the values (integers from 0 to 10) are stored in a list of length n.</p>
<table class="example">
<tr><td><pre>
gap> DatabaseAttributeAdd( smallintenum1, rec(
> identifier:= "residue mod 11",
> type:= "values",
> create:= function( attr, id ) return id mod 11; end,
> ) );
</pre></td></tr></table>
<p>Some integers are values of <code class="func">Factorial</code> (<a href="../../../doc/ref/chap16.html#X87665F748594BF29"><b>Reference: Factorial</b></a>), 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 <code class="code">type</code> value <code class="code">"pairs"</code> and precompute the information for the <code class="code">data</code> component. (The default for the <code class="code">dataDefault</code> component is an empty string, which is fine; so we need not prescribe this component.)</p>
<table class="example">
<tr><td><pre>
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,
> ) );
</pre></td></tr></table>
<p>We use this setup for creating a browse table. The integers are shown as the first column, using the <code class="code">"self"</code> 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.</p>
<table class="example">
<tr><td><pre>
gap> t1:= BrowseTableFromDatabaseIdEnumerator( smallintenum1,
> [ "self" ],
> [ "primes", "prime powers", "factors", "residue mod 11",
> "inverse factorial" ] );;
</pre></td></tr></table>
<p>The following session shows some of the features of the browse table.</p>
<table class="example">
<tr><td><pre>
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 );
</pre></td></tr></table>
<p>(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.</p>
<ul>
<li><p>The strings <code class="code">"true"</code> and <code class="code">"false"</code> shown for the Boolean valued database attributes can be replaced by the perhaps more suggestive strings <code class="code">"+"</code> and <code class="code">"-"</code> (or perhaps an empty string instead of <code class="code">"-"</code>).</p>
</li>
<li><p>The alignment of values inside their columns can be customized.</p>
</li>
<li><p>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.</p>
</li>
<li><p>The column labels can be customized.</p>
</li>
<li><p>Where the lexicographic order is not appropriate for sorting table entries, we can prescribe an individual comparison function.</p>
</li>
<li><p>Sort parameters can be customized.</p>
</li>
<li><p>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.</p>
</li>
<li><p>Finally, in the call of <code class="func">BrowseTableFromDatabaseIdEnumerator</code> (<a href="chapA.html#X17F25A3E586653911"><b>A.2-2</b></a>), we can add a header to the browse table.</p>
</li>
</ul>
<p>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 <code class="code">n</code> and <code class="code">factorialdata</code> are already available.</p>
<table class="example">
<tr><td><pre>
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 ) );;
</pre></td></tr></table>
<p>We run the same session as with the browse table for <code class="code">smallintenum1</code>.</p>
<table class="example">
<tr><td><pre>
gap> BrowseData.SetReplay( sample_session );
gap> NCurses.BrowseGeneric( t2 );
gap> BrowseData.SetReplay( false );
gap> Unbind( t2.dynamic.replay );
</pre></td></tr></table>
<p>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 <code class="code">"+"</code> 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 <a href="chap2.html#X1793D897483674294"><b>2.1-7</b></a>), 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 <code class="code">++</code>, <code class="code">+-</code>, <code class="code">--</code> for primes, prime powers, and non-prime-powers, respectively. (We see that besides these issues, the required <strong class="pkg">GAP</strong> code is more involved than what is needed for the examples above.)</p>
<table class="example">
<tr><td><pre>
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 );
</pre></td></tr></table>
<p>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 <code class="code">version</code> value of the database id enumerator, and provide <code class="code">version</code> and <code class="code">update</code> components for all attributes.</p>
<p>Again, we start the construction from scratch.</p>
<table class="example">
<tr><td><pre>
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,
> ) );
</pre></td></tr></table>
<p>Now we can change the set of database entries by assigning a new value to the variable <code class="code">n</code>, and then calling <code class="func">DatabaseIdEnumeratorUpdate</code> (<a href="chapA.html#X80A9097217E3C8311"><b>A.1-7</b></a>).</p>
<table class="example">
<tr><td><pre>
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 );
</pre></td></tr></table>
<p><a id="X81A5F37B81E0968C" name="X81A5F37B81E0968C"></a></p>
<h4>A.4 <span class="Heading">Example: An Overview of the <strong class="pkg">GAP</strong> Library of Transitive Groups
</span></h4>
<p>The example shown in this section deals with <strong class="pkg">GAP</strong>'s Library of Transitive Permutation Groups, see <a href="../../../doc/ref/chap48.html#X17FBB970F17D110FDB"><b>Reference: Transitive Permutation Groups</b></a>. Section <a href="chapA.html#X832846F486391385"><b>A.4-1</b></a> introduces a browse table application for viewing information about the contents of this library, which is based on database attributes. Section <a href="chapA.html#X17FA5513D84EE81AB"><b>A.4-2</b></a> introduces functions based on database attributes that can be used to select groups from the library. Finally, Section <a href="chapA.html#X17AC0308217D5CDE03"><b>A.4-3</b></a> describes how these two functionalities are implemented.</p>
<p><a id="X832846F486391385" name="X832846F486391385"></a></p>
<h5>A.4-1 BrowseTransitiveGroupsInfo</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> BrowseTransitiveGroupsInfo</code>( <var class="Arg">[arec]</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>the list of "clicked" groups.</p>
<p>This function shows the contents of the <strong class="pkg">GAP</strong> Library of Transitive Permutation Groups in a browse table.</p>
<p>The table rows correspond to the groups. If no argument is given then the columns of the table contain information about the degree of the permutation representation, group order, names for the group, primitivity, transitivity, and sign. Otherwise, the argument <var class="Arg">arec</var> must be a record; the component <code class="code">choice</code> of <var class="Arg">arec</var> can be used to prescribe columns, the value of this component must then be a list of strings that are <code class="code">identifier</code> values of database attributes (see <a href="chapA.html#X17D2804F917EE18BA5"><b>A.1-2</b></a>) for the <code class="code">IdEnumerator</code> component of <code class="func">TransitiveGroupsData</code> (<a href="chapA.html#X17AC0308217D5CDE03"><b>A.4-3</b></a>), see Section <a href="chapA.html#X83E9FAAE85F80223"><b>A.4-4</b></a> for examples.</p>
<p>The return value is the list of transitive groups whose table rows have been "clicked" in visual mode.</p>
<p>The full functionality of the function <code class="func">NCurses.BrowseGeneric</code> (<a href="chap4.html#X85FC163D87FAFD12"><b>4.3-1</b></a>) is available.</p>
<table class="example">
<tr><td><pre>
gap> c:= [ NCurses.keys.ENTER ];;
gap> BrowseData.SetReplay( Concatenation(
> "scrrrr/5", c, # search for transitivity 5,
> "nn", c, # go to the third occurrence, click on it,
> "Q" ) );; # and quit the browse table
gap> BrowseTransitiveGroupsInfo();
[ M(12) ]
gap> BrowseData.SetReplay( false );
</pre></td></tr></table>
<p><a id="X17FA5513D84EE81AB" name="X17FA5513D84EE81AB"></a></p>
<h5>A.4-2 TransitiveGroupsData.AllTransitiveGroups</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> TransitiveGroupsData.AllTransitiveGroups</code>( <var class="Arg">fun, res[, ...]</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> TransitiveGroupsData.OneTransitiveGroup</code>( <var class="Arg">fun, res[, ...]</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><b>Returns: </b>the list of groups from the <strong class="pkg">GAP</strong> Library of Transitive Permutation Groups with the given properties, or one such group, or <code class="keyw">fail</code>.</p>
<p>These functions are analogues of <code class="func">AllTransitiveGroups</code> (<a href="../../../doc/ref/chap48.html#X82676ED5826E9E2E"><b>Reference: AllTransitiveGroups</b></a>) and <code class="func">OneTransitiveGroup</code> (<a href="../../../doc/ref/chap48.html#X82676ED5826E9E2E"><b>Reference: OneTransitiveGroup</b></a>). The only difference is that they are based on the database attributes that are defined in <code class="func">TransitiveGroupsData</code> (<a href="chapA.html#X17AC0308217D5CDE03"><b>A.4-3</b></a>).</p>
<p>Besides those <strong class="pkg">GAP</strong> attributes such as <code class="func">Size</code> (<a href="../../../doc/ref/chap28.html#X858ADA3B17A684421"><b>Reference: Size</b></a>) and <code class="func">IsPrimitive</code> (<a href="../../../doc/ref/chap39.html#X84C19AD68247B760"><b>Reference: IsPrimitive</b></a>) for which special support is provided in <code class="func">AllTransitiveGroups</code> (<a href="../../../doc/ref/chap48.html#X82676ED5826E9E2E"><b>Reference: AllTransitiveGroups</b></a>) and <code class="func">OneTransitiveGroup</code> (<a href="../../../doc/ref/chap48.html#X82676ED5826E9E2E"><b>Reference: OneTransitiveGroup</b></a>), database attributes are defined for some other <strong class="pkg">GAP</strong> properties, see <a href="chapA.html#X83E9FAAE85F80223"><b>A.4-4</b></a>. One could speed up <code class="func">TransitiveGroupsData.AllTransitiveGroups</code> for given conditions by adding further precomputed database attributes.</p>
<p>After defining a database attribute, it is automatically used in calls to <code class="func">TransitiveGroupsData.AllTransitiveGroups</code>. In order to make the values appear in the table shown by <code class="func">BrowseTransitiveGroupsInfo</code> (<a href="chapA.html#X832846F486391385"><b>A.4-1</b></a>), one has to enter an argument record that contains the name of the database attributes in its <code class="code">choice</code> list.</p>
<table class="example">
<tr><td><pre>
gap> TransitiveGroupsData.AllTransitiveGroups(
> NrMovedPoints, [ 5 .. 28 ],
> IsSimpleGroup, true, IsAbelian, true );
[ C(5) = 5, C(7) = 7, C(11)=11, C(13)=13, C(17)=17, C(19)=19, C(23) ]
</pre></td></tr></table>
<p><a id="X17AC0308217D5CDE03" name="X17AC0308217D5CDE03"></a></p>
<h5>A.4-3 TransitiveGroupsData</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">> TransitiveGroupsData</code></td><td class="tdright">( global variable )</td></tr></table></div>
<p>This is a record that contains the data needed by <code class="func">BrowseTransitiveGroupsInfo</code> (<a href="chapA.html#X832846F486391385"><b>A.4-1</b></a>), <code class="func">TransitiveGroupsData.AllTransitiveGroups</code> (<a href="chapA.html#X17FA5513D84EE81AB"><b>A.4-2</b></a>), and <code class="func">TransitiveGroupsData.OneTransitiveGroup</code> (<a href="chapA.html#X17FA5513D84EE81AB"><b>A.4-2</b></a>). The component <code class="code">IdEnumerator</code> contains a database id enumerator (see <a href="chapA.html#X17999CF7F179ACA240"><b>A.1-1</b></a>) for the <strong class="pkg">GAP</strong> Library of Transitive Permutation Groups.</p>
<p>Note that although <code class="func">NrTransitiveGroups</code> (<a href="../../../doc/ref/chap48.html#X871C274217F11B123"><b>Reference: NrTransitiveGroups</b></a>) returns <code class="code">1</code> when it is called with the argument <code class="code">1</code>, <code class="func">TransitiveGroup</code> (<a href="../../../doc/ref/chap48.html#X17F062EC117EB8287D"><b>Reference: TransitiveGroup</b></a>) runs into an error when it is called with first argument equal to <code class="code">1</code>, and the degree <code class="code">1</code> is explicitly excluded from results of <code class="func">AllTransitiveGroups</code> (<a href="../../../doc/ref/chap48.html#X82676ED5826E9E2E"><b>Reference: AllTransitiveGroups</b></a>) and <code class="func">OneTransitiveGroup</code> (<a href="../../../doc/ref/chap48.html#X82676ED5826E9E2E"><b>Reference: OneTransitiveGroup</b></a>). For the sake of consistency with this inconsistency in the <strong class="pkg">GAP</strong> Library of Transitive Permutation Groups, we exclude the degree <code class="code">1</code> from <code class="func">TransitiveGroupsData</code>. (Those who want to include this degree can change the value of <code class="code">TransitiveGroupsData.MinimalDegree</code> from its default value <code class="code">2</code> to <code class="code">1</code> in the file <code class="file">app/transbrowse.g</code> of the package.)</p>
<p><a id="X83E9FAAE85F80223" name="X83E9FAAE85F80223"></a></p>
<h5>A.4-4 <span class="Heading">Additional Database Attributes for Transitive Groups</span></h5>
<p>Database attributes for the following <strong class="pkg">GAP</strong> properties are defined in <code class="func">TransitiveGroupsData</code> (<a href="chapA.html#X17AC0308217D5CDE03"><b>A.4-3</b></a>): <code class="func">IsAbelian</code> (<a href="../../../doc/ref/chap33.html#X830A4A4C1795FBC2D"><b>Reference: IsAbelian</b></a>), <code class="func">IsPerfectGroup</code> (<a href="../../../doc/ref/chap37.html#X8755147280C84DBB"><b>Reference: IsPerfectGroup</b></a>), <code class="func">IsSimpleGroup</code> (<a href="../../../doc/ref/chap37.html#X17A6685D7819AEC32"><b>Reference: IsSimpleGroup</b></a>), and <code class="func">IsSolvableGroup</code> (<a href="../../../doc/ref/chap37.html#X809C78D5877D31DF"><b>Reference: IsSolvableGroup</b></a>). The values of these database attributes are precomputed and stored in the file <code class="file">app/transdbattr.g</code> of the package.</p>
<p>So the above <strong class="pkg">GAP</strong> properties have special support as conditions in <code class="func">TransitiveGroupsData.AllTransitiveGroups</code> (<a href="chapA.html#X17FA5513D84EE81AB"><b>A.4-2</b></a>) and <code class="func">TransitiveGroupsData.OneTransitiveGroup</code> (<a href="chapA.html#X17FA5513D84EE81AB"><b>A.4-2</b></a>), contrary to <code class="func">AllTransitiveGroups</code> (<a href="../../../doc/ref/chap48.html#X82676ED5826E9E2E"><b>Reference: AllTransitiveGroups</b></a>) and <code class="func">OneTransitiveGroup</code> (<a href="../../../doc/ref/chap48.html#X82676ED5826E9E2E"><b>Reference: OneTransitiveGroup</b></a>). In practice, the difference is that the former functions need not construct and check those transitive groups that do not have the properties in question.</p>
<p>These database attributes can also be used as columns in the Browse table shown by <code class="func">BrowseTransitiveGroupsInfo</code> (<a href="chapA.html#X832846F486391385"><b>A.4-1</b></a>), for example as follows.</p>
<table class="example">
<tr><td><pre>
gap> n:= [ 14, 14, 14 ];; # ``do nothing'' input (means timeout)
gap> BrowseData.SetReplay( Concatenation(
> "scrrrsc", n, n, # categorize by solvability info
> "!", n, # reset
> "scrrrrsc", n, n, # categorize by abelianity info
> "Q" ) );; # quit the browse table
gap> BrowseTransitiveGroupsInfo( rec( choice:= [ "degree", "size",
> "names", "IsSolvableGroup", "IsAbelian", "IsPerfectGroup",
> "IsSimpleGroup" ] ) );;
gap> BrowseData.SetReplay( false );
</pre></td></tr></table>
<p>The data in the file <code class="file">app/transdbattr.g</code> are lists of Booleans, which are encoded as strings via <code class="code">HexStringBlistEncode</code>, and these strings are decoded with <code class="code">BlistStringDecode</code>. Note that for most of the groups in the library are not abelian, not perfect, not simple, but solvable; Therefore in fact the inverse values of the solvability info are actually stored –this yields a shorter string.</p>
<table class="example">
<tr><td><pre>
gap> TransitiveGroupsData.MinimalDegree;
2
gap> attrs:= TransitiveGroupsData.IdEnumerator.attributes;;
gap> oldlen:= SizeScreen();; SizeScreen( [ 60 ] );;
gap> HexStringBlistEncode( attrs.IsAbelian.data );
"D88400040Es0503s0480s040406s252010s0720s0C3EsF30803s7A040\
5s8B20s1302s0740E0sFFsFFsFFsFFsFFsFFsFFsFFsFFsFFsFFsFFs40C\
0s1910s0B1AsFFs2B18sE74040sFFsFF"
gap> SizeScreen( oldlen );;
</pre></td></tr></table>
<p>Removing the <code class="code">datafile</code> component from the four database attributes would yield the situation that attribute values are computed at runtime. Computing the values for all groups in the library –for example by categorizing the Browse table by one of the columns that correspond to these database attributes– will require several seconds. Note that if we assume that the information about solvability is already known, the test for <code class="func">IsPerfectGroup</code> (<a href="../../../doc/ref/chap37.html#X8755147280C84DBB"><b>Reference: IsPerfectGroup</b></a>) is needed only for the few nonsolvable groups in the library but each such test is expensive; on the other hand, each test for <code class="func">IsAbelian</code> (<a href="../../../doc/ref/chap33.html#X830A4A4C1795FBC2D"><b>Reference: IsAbelian</b></a>) is cheap but such tests are needed for the many solvable groups in the library, in particular these groups must be constructed for the tests.</p>
<div class="chlinkprevnextbot"> <a href="chap0.html">Top of Book</a> <a href="chap6.html">Previous Chapter</a> <a href="chapBib.html">Next Chapter</a> </div>
<div class="chlinkbot"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a> <a href="chap1.html">1</a> <a href="chap2.html">2</a> <a href="chap3.html">3</a> <a href="chap4.html">4</a> <a href="chap5.html">5</a> <a href="chap6.html">6</a> <a href="chapA.html">A</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<hr />
<p class="foot">generated by <a href="http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
91213ddcfbe7f54821d42c2d9e091326
>
files
>
24
