<html><head><title>[ext] 3 Library Files</title></head>
<body text="#000000" bgcolor="#ffffff">
[<a href="../index.htm">Top</a>] [<a href = "chapters.htm">Up</a>] [<a href ="CHAP002.htm">Previous</a>] [<a href ="CHAP004.htm">Next</a>] [<a href = "theindex.htm">Index</a>]
<h1>3 Library Files</h1><p>
<P>
<H3>Sections</H3>
<oL>
<li> <A HREF="CHAP003.htm#SECT001">File Types</a>
<li> <A HREF="CHAP003.htm#SECT002">File Structure</a>
<li> <A HREF="CHAP003.htm#SECT003">Finding Implementations in the Library</a>
<li> <A HREF="CHAP003.htm#SECT004">Undocumented Variables</a>
</ol><p>
<p>
This chapter describes some of the conventions used in the <font face="Gill Sans,Helvetica,Arial">GAP</font>
library files.
These conventions are intended as a help on how to read library files and
how to find information in them.
So everybody is recommended to follow these conventions,
although they do not prescribe a compulsory programming style
-- <font face="Gill Sans,Helvetica,Arial">GAP</font> itself will not bother with the formatting of files.
<p>
Filenames have traditionally <font face="Gill Sans,Helvetica,Arial">GAP</font> adhered to the 8+3 convention (to make it
possible to use the same filenames even on a MS-DOS file system) and been in
lower case (systems that do not recognize lower case in file names will
convert them automatically to upper case). It is no longer so important to
adhere to these conventions, but at the very least filenames should adhere
to a 16+5 convention, and be distinct even after identifying upper and lower
case. Directory names of packages, however, <strong>must</strong> be in lower case (the
<code>LoadPackage</code> command (see <a href="../ref/CHAP074.htm#SSEC002.1">LoadPackage</a> in the Reference manual)
assumes this).
<p>
<p>
<h2><a name="SECT001">3.1 File Types</a></h2>
<p><p>
The <font face="Gill Sans,Helvetica,Arial">GAP</font> library consists of the following types of files, distinguished
by their suffixes:
<p>
<p>
<dl compact>
<dt><code>.g</code> <dd>
Files which contain parts of the ``inner workings'' of <font face="Gill Sans,Helvetica,Arial">GAP</font>.
These files usually do not contain mathematical functionality,
except for providing links to kernel functions.
<p>
<dt><code>.gd</code> <dd>
Declaration files.
These files contain declarations of all categories, attributes,
operations, and global functions.
These files also contain the operation definitions in comments.
<p>
<dt><code>.gi</code> <dd>
Implementation files.
These files contain all installations of methods and global functions.
Usually declarations of representations are also considered to be
part of the implementation and are therefore found in the <code>.gi</code> files.
<p>
<dt> <dd>
As a rule of thumb, all <code>.gd</code> files are read in before the <code>.gi</code> files
are read.
Therefore a <code>.gi</code> file usually may use any operation or global function
(it has been declared before),
and no care has to be taken towards the order in which the <code>.gi</code> files
are read.
<p>
<dt><code>.co</code> <dd>
Completion files.
They are used only to speed up loading
(see <a href="../ref/CHAP003.htm#SECT005">Completion Files</a> in the Reference Manual).
</dl>
<p>
<p>
<h2><a name="SECT002">3.2 File Structure</a></h2>
<p><p>
Every file starts with a header that lists the filename, copyright, a short
description of the file contents and the original authors of this file.
<p>
This is followed by a revision entry:
<pre>
Revision.file_suf :=
"@(#)$Id: libform.tex,v 4.13.2.1 2004/01/27 11:37:59 stefan Exp $";
</pre>
where <code>file.suf</code> is the file name. The revision control system used for the
development will automatically append text to the string ``<code>Id: </code>'' which
indicates the version number. The reason for these revision entries is to
give the possibility to check from within <font face="Gill Sans,Helvetica,Arial">GAP</font> for revision numbers of a
file. (Do not mistake these revision numbers for the version number of
<font face="Gill Sans,Helvetica,Arial">GAP</font> itself.)
<p>
Global comments usually are indented by two hash marks and two blanks.
If a section of such a comment is introduced by a line containing
a hash mark and a number it will be used for the manual
(stripped of the hash marks and leading two blanks; see
Section <a href="CHAP002.htm#SECT014">Using buildman.pe</a>).
<p>
Every declaration or method or function installation which is not only of
local scope is introduced by a function header of the following type.
<br><code>#############################################################################</code>
<br><code>##</code>
<br><code>#</code><var>X</var><code> ExampleFunction(<A>,<B>)</code>
<br><code>##</code>
<br><code>## This function does nothing.</code>
<p>
The <var>X</var> in the example is one of the letters: <code>F</code>, <code>A</code>, <code>P</code>, <code>O</code>,
<code>C</code>, <code>R</code> or <code>V</code>, and has the same meaning as at the end
of a declaration line in the Reference Manual (see <a href="../ref/CHAP001.htm#SECT001">Manual Conventions</a>
in the Reference Manual);
it indicates whether the object declared will be a function, attribute,
property, operation, category, representation or variable, respectively.
Additionally <code>M</code> is used in <code>.gi</code> files for method installations.
The line then gives a sample usage of the function.
This is followed by a comment which describes the identifier.
This description will automatically be extracted to build the
Reference Manual source, if there is a <code>\Declaration</code> line in some
<code>.msk</code> file together with an appropriate configuration file (see
Section <a href="CHAP002.htm#SECT014">Using buildman.pe</a>).
<p>
Indentation in functions and the use of decorative spaces in the code are
left to the decision of the authors of each file.
<p>
The file ends with an
<pre>
#E
</pre>
comment section that may be used to store formatting descriptions for an
editor.
<p>
<p>
<h2><a name="SECT003">3.3 Finding Implementations in the Library</a></h2>
<p><p>
There is no general browsing tool that would point you to the place in the
library where a certain method or global function is installed. However the
following remarks might be of help:
<p>
You can use <code>ApplicableMethod</code> (see <a href="../ref/CHAP007.htm#SSEC002.1">ApplicableMethod</a> in the reference
manual) to get the function which implements a method for specific
arguments. Setting its print level higher will also give you the
installation string for this method.
<p>
To find the occurrence of functions and methods in the library, one can use
the <code>grep</code> tool under UNIX. To find a function, search for the function name
in the <code>.gd</code> files (as it is declared only once, only one file will show up),
the function installation is likely to occur in the corresponding <code>.gi</code> file.
<p>
To find a method search for <code>Method(</code> (this catches <code>InstallMethod</code> and
<code>InstallOtherMethod</code>) and the installation string or the operation name.
<p>
<p>
<h2><a name="SECT004">3.4 Undocumented Variables</a></h2>
<p><p>
For several global variables in <font face="Gill Sans,Helvetica,Arial">GAP</font>,
no information is available via the help system
(see Section <a href="../tut/CHAP002.htm#SECT008">Help</a> in the Tutorial, for a quick overview of the
help system, or Chapter <a href="../ref/CHAP002.htm">The Help System</a> in the reference manual,
for details).
There are various reasons for ``hiding'' a variable from the user;
namely, the variable may be regarded as of minor importance
(for example, it may be a function called by documented <font face="Gill Sans,Helvetica,Arial">GAP</font>
functions that first compute many input parameters for the undocumented
function),
or it belongs to a part of <font face="Gill Sans,Helvetica,Arial">GAP</font> that is still experimental in the sense
that the meaning of the variable has not yet been fixed or even that it is
not clear whether the variable will vanish in a more developed version.
<p>
As a consequence, it is dangerous to use undocumented variables because
they are not guaranteed to exist or to behave the same in future versions
of <font face="Gill Sans,Helvetica,Arial">GAP</font>.
<p>
Conversely, for <strong>documented</strong> variables, the definitions in the <font face="Gill Sans,Helvetica,Arial">GAP</font>
manual can be relied on for future <font face="Gill Sans,Helvetica,Arial">GAP</font> versions (unless they turn out
to be erroneous);
if the <font face="Gill Sans,Helvetica,Arial">GAP</font> developers find that some piece of minor, but documented
functionality is an insurmountable obstacle to important developments,
they may make the smallest possible incompatible change to the functionality
at the time of a major release.
However, in any such case it will be announced clearly in the <font face="Gill Sans,Helvetica,Arial">GAP</font> Forum
what has been changed and why.
<p>
So on the one hand, the developers of <font face="Gill Sans,Helvetica,Arial">GAP</font> want to keep the freedom
of changing undocumented <font face="Gill Sans,Helvetica,Arial">GAP</font> code.
On the other hand, users may be interested in using undocumented
variables.
<p>
In this case, whenever you write <font face="Gill Sans,Helvetica,Arial">GAP</font> code involving undocumented
variables,
and want to make sure that this code will work in future versions of <font face="Gill Sans,Helvetica,Arial">GAP</font>,
you may ask at <a href="mailto:support@gap-system.org">support@gap-system.org</a> for documentation
about the variables in question.
The <font face="Gill Sans,Helvetica,Arial">GAP</font> developers then decide whether these variables shall be
documented or not, and if yes, what the definitions shall be.
<p>
In the former case, the new documentation is added to the <font face="Gill Sans,Helvetica,Arial">GAP</font> manual,
this means that from then on, this definition is protected against
changes.
<p>
In the latter case (which may occur for example if the variables
in question are still experimental), you may add the current
values of these variables to your private code if you want to
be sure that nothing will be broken later due to changes in <font face="Gill Sans,Helvetica,Arial">GAP</font>.
<p>
<p>
[<a href="../index.htm">Top</a>] [<a href = "chapters.htm">Up</a>] [<a href ="CHAP002.htm">Previous</a>] [<a href ="CHAP004.htm">Next</a>] [<a href = "theindex.htm">Index</a>]
<P>
<font face="Gill Sans,Helvetica,Arial">GAP 4 manual<br>December 2008
</font></body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
5e1854624d3bc613bdd0dd13d1ef9ac7
>
files
>
29
