This chapter describes some of the conventions used in the GAP 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 --GAP itself will not bother with the formatting of files.
All filenames used by GAP adhere to the 8+3 convention (this makes it possible to use the same filenames even on a MS-DOS file system) and are in lower case (systems that do not recognize lower case in file names will convert them automatically to upper case).
The GAP library consists of the following types of files, distinguished by their suffixes:
.g
:
.gd
:
.gi
: gi
files.
gd
files are read in before the gi
files
are read.
Therefore a gi
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 gi
files
are read.
.co
: 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.
This is followed by a revision entry:
Revision.file_suf := "@(#)$Id: libform.tex,v 4.5 1999/07/05 11:34:27 ahulpke Exp $";where
file.suf
is the file name. The revision control system used for the
development will automatically append text to the string ``Id:
'' which
indicates the version number. The reason for these revision entries is to
give the possibility to check from within GAP for revision numbers of a
file. (Do not mistake these revision numbers for the version number of
GAP itself.)
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).
Every declaration or method or function installation which is not only of local scope is introduced by a function header of the following type.
############################################################################# ## #X ExampleFunction(<A>,<B>) ## ## This function does nothing.The initial letter (
X
in the example) has the same meaning as at the end
of a declaration line in the Reference Manual (see tut:Manual Conventions
in the Tutorial),
it indicates whether the object declared will be a category, representation
and so forth.
Additionally M
is used in .gi
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 used by the process to build the
Reference Manual source.
Indentation in functions and the use of decorative spaces in the code are left to the decision of the authors of each file.
The file ends with an
#Ecomment section that may be used to store formatting descriptions for an editor.
3.3 Finding Implementations in the Library
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:
You can use ApplicableMethod
(see ref:ApplicableMethod 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.
To find the occurrence of functions and methods in the library, one can use
the grep
tool under UNIX. To find a function, search for the function name
in the gd
files (as it is declared only once, only one file will show up),
the function installation is likely to occur in the corresponding gi
file.
To find a method search for Method(
(this catches InstallMethod
and
InstallOtherMethod
) and the installation string or the operation name.
[Top] [Previous] [Up] [Next] [Index]
GAP 4 manual