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.
Filenames have traditionally GAP 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, must be in lower case (the LoadPackage (76.2-1) command assumes this).
The GAP library consists of the following types of files, distinguished by their suffixes:
.g Files which contain parts of the "inner workings" of GAP. These files usually do not contain mathematical functionality, except for providing links to kernel functions.
.gd Declaration files. These files contain declarations of all categories, attributes, operations, and global functions. These files also contain the operation definitions in comments.
.gi 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 .gi files.
As a rule of thumb, all .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.
For a concretely given function, you can use FilenameFunc (5.1-4) and StartlineFunc (5.1-5) for finding the file where this function is defined, and the line in this file where the definition of this function starts. This does not work for arbitrary functions, see Section FilenameFunc (5.1-4) for the restrictions.
If you are interested in getting the function which implements a method for specific arguments, you can use 7.2-1. If FilenameFunc (5.1-4) does not work for this method then setting the print level of 7.2-1 higher will give you the installation string for this method, which can be used for searching in library files.
To find the occurrence of functions, methods, function names, and installation strings 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 global variables are usually declared only once, only few files will show up. The function installation is likely to occur in the corresponding .gi file.
To find a method from the known operation name and the installation string, search for the string "Method(" (this catches both InstallMethod (78.2-1) and InstallOtherMethod (78.2-2)) and the installation string or the operation name.
The following tools from the GAP package Browse can be used for accessing the code of functions.
BrowseGapMethods (Browse: BrowseGapMethods see BrowseGapData) shows an overview of GAP's operations and methods, and allows one to navigate through the files that contain the implementations of the methods, using a pager.
BrowseProfile (Browse: BrowseProfile) shows profiling results (similar to DisplayProfile (7.7-9)) and allows one to navigate through the files that contain the implementations of the functions that were actually used, using a pager.
For several global variables in GAP, no information is available via the help system (see Section Tutorial: Help, for a quick overview of the help system, or Chapter 2, 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 GAP functions that first compute many input parameters for the undocumented function), or it belongs to a part of GAP 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.
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 GAP.
Conversely, for documented variables, the definitions in the GAP manual can be relied on for future GAP versions (unless they turn out to be erroneous); if the GAP 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 GAP Forum what has been changed and why.
So on the one hand, the developers of GAP want to keep the freedom of changing undocumented GAP code. On the other hand, users may be interested in using undocumented variables.
In this case, whenever you write GAP code involving undocumented variables, and want to make sure that this code will work in future versions of GAP, you may ask at [email protected] for documentation about the variables in question. The GAP developers then decide whether these variables shall be documented or not, and if yes, what the definitions shall be.
In the former case, the new documentation is added to the GAP manual, this means that from then on, this definition is protected against changes.
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 GAP.
generated by GAPDoc2HTML