1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %W libform.tex GAP documentation Alexander Hulpke -->
<!-- %% -->
<!-- %% -->
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Chapter Label="Library Files">
<Heading>Library Files</Heading>
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.
<P/>
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, <E>must</E> be in lower case
(the <Ref Func="LoadPackage"/> command assumes this).
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="File Types">
<Heading>File Types</Heading>
The &GAP; library consists of the following types of files, distinguished
by their suffixes:
<P/>
<List>
<Mark><C>.g</C> </Mark>
<Item>
Files which contain parts of the <Q>inner workings</Q> of &GAP;.
These files usually do not contain mathematical functionality,
except for providing links to kernel functions.
</Item>
<Mark><C>.gd</C> </Mark>
<Item>
Declaration files.
These files contain declarations of all categories, attributes,
operations, and global functions.
These files also contain the operation definitions in comments.
</Item>
<Mark><C>.gi</C> </Mark>
<Item>
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 <C>.gi</C> files.
</Item>
</List>
<P/>
As a rule of thumb, all <C>.gd</C> files are read in before the <C>.gi</C>
files are read.
Therefore a <C>.gi</C> 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 <C>.gi</C> files
are read.
</Section>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Finding Implementations in the Library">
<Heading>Finding Implementations in the Library</Heading>
For a concretely given function, you can use
<Ref Func="FilenameFunc"/> and <Ref Func="StartlineFunc"/> 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 <Ref Func="FilenameFunc"/> for the restrictions.
<P/>
If you are interested in getting the function which implements a method
for specific arguments, you can use <Ref Sect="ApplicableMethod"/>.
If <Ref Func="FilenameFunc"/> does not work for this method then
setting the print level of <Ref Sect="ApplicableMethod"/> higher will give
you the installation string for this method, which can be used for searching
in library files.
<P/>
To find the occurrence of functions, methods, function names,
and installation strings in the library,
one can use the <C>grep</C> tool under UNIX.
To find a function, search for the function name in the <C>.gd</C> 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
<C>.gi</C> file.
<P/>
To find a method from the known operation name and the installation string,
search for the string <Q><C>Method(</C></Q>
(this catches both <Ref Func="InstallMethod"/> and
<Ref Func="InstallOtherMethod"/>)
and the installation string or the operation name.
<P/>
The following tools from the &GAP; package <Package>Browse</Package>
can be used for accessing the code of functions.
<P/>
<List>
<Item>
<Ref Func="BrowseGapMethods" BookName="browse"/> 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.
</Item>
<Item>
<Ref Func="BrowseProfile" BookName="browse"/> shows profiling results
(similar to <Ref Func="DisplayProfile"/>) and allows one to navigate
through the files that contain the implementations of the functions
that were actually used, using a pager.
</Item>
</List>
</Section>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Undocumented Variables">
<Heading>Undocumented Variables</Heading>
For several global variables in &GAP;,
no information is available via the help system
(see Section <Ref Sect="Help" BookName="tut"/>,
for a quick overview of the help system,
or Chapter <Ref Chap="The Help System"/>,
for details).
There are various reasons for <Q>hiding</Q> 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.
<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 &GAP;.
<P/>
Conversely, for <E>documented</E> 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.
<P/>
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.
<P/>
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>support@gap-system.org</Email> 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.
<P/>
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.
<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 &GAP;.
</Section>
</Chapter>
|
