Dear GAP users,
At various times the following problem has been brought up in GAP-
trouble and in private mail:
In addition to the GAP functions that are described in the manual, GAP
contains many 'undocumented' functions, which have been used by the
developers of GAP to separate their code into pieces that e.g. can be
called from different places. Advanced users who have looked at the
source have often found it useful to know about such functions in
writing their own code, and the request has been put forward to give
better help for finding such 'undocumented' functions. Recently for
instance Charles Wright in a private letter to me has suggested to
give at least their names in the manual.
We have always maintained that GAP is an open system which in
particular allows and supports modifying existing code for special
purposes, and hence the request to know ways of finding information
also about 'undocumented' functions is most legitimate. On the other
hand we must emphazise:
*********************************************************************** *** It is impossible to give any warranty that 'undocumented'* *** functions may not change or even vanish from one update to the* *** next. Also very often such functions deal with very special* *** situations which are much too complicated to fully describe for* *** general safe understanding. Hence using such functions in own* *** programs is extremely dangerous and must certainly completely* *** remain under the user's responsibility, who must make sure that* *** such a function does what (s)he supposes, and must make sure that* *** (s)he is not falling into a trap when such function is changed* *** without warning. As opposed to problems with functions documented* *** in the manual, we cannot even promise help if a user is getting* *** into trouble by directly calling undocumented functions. * ***********************************************************************
We are afraid that listing even just the names in the manual might let
users forget about this warning, and therefore we do not want to
follow the above suggestion. However we want to point out that indeed
it is not too difficult to get hold of the names and information about
'undocumented' functions at the level of using operating systems to
study the source which in any case will be necessary if one wants to
use them in one's own code.
* In fact, because of the missing guarantee for their unchanged
* survival of updates, they should be copied under a modified name
* into private code rather than called from the main GAP library.
So here are some suggestions how to find 'undocumented' functions:
Martin Schoenert suggests:
One can get a list of most available GAP functions, together with a
short description what each function does, simply by collecting the
lines that start with '#F' from the library files.
Under UNIX this can be done with the program 'grep'
grep -h '^#F' <gap-directory>/lib/*.g
the option '-h' tells 'grep' not to precede each line that begins with
'#F' with the filename.
Of course one can restrict the search to a certain class of files,
e.g., to search only in the files related to permutation groups use
grep -h '^#F' <gap-directory>/lib/perm*.g
One can further restrict the search by specifying additional keywords
grep -h '^#F.*central' <gap-directory>/lib/perm*.g
The last command results in the following output
#F CentralCompositionSeriesPPermGroup(<G>) . central composition series
#F PermGroupOps.Centralizer(<G>,<g>) . . . centralizer of a permutation
#F CentralizerNormalCSPG() . . . . . . centralizer of a normal subgroup
#F CentralizerNormalTransCSPG() . centralizer of normal in transitive G
#F CentralizerTransSymmCSPG() . . . centralizer of transitive G in S_n
Further the file "permstbc.g" contains some functions for permutation
groups which are not caught this way but must be looked up
individually.
Furthermore there are some local functions inside large functions
which are used to structure the code but it is impossible to provide
any means to find them.
Some share packages like GAUVA follow the coding convention of GAP
closely, so you can use the same mechanism for these packages by
replacing
<gap-directory>/lib
by
<gap-directory>/pkg/<pkg-name>/lib
in the above examples.
Alexander Hulpke further suggests:
Sometimes you will want to see not only the first line of a functions
header (the line including the '#F') but also the complete header. The
following shell script will run through all library files and print
you all comment paragraphs including a given string. To use it (it
works *only* on UNIX systems):
1. copy the text between the two 'cut here' lines (but excluding the
lines themselves) to a new file 'gaphelp'
2. put this file in a directory that is given in your 'PATH'
environment variable (If not, you will have to call it with an
absolute path name)
3. Edit the file to replace '/usd/gap/3.5/lib' by the path of your gap
library directory.
4. change this file to executable by using 'chmod 755 gaphelp'
5. To use the program, execute a search by calling 'gaphelp group' to
se all library comments refering to 'group'. (Of course you can
replace 'group' by any other string.) Note that the search is case
sensitive.
------------- cut here --------------------
#!/bin/sh
echo 'BEGIN{c=0;i=1;f=0;}
{a=substr($0,1,2);
if ((a=="##")||(a=="#A")||(a=="#F")) {c=1}
else {if ((c==1)&&(f==1)) {
for (j=1; j<i; j++) print s[j];
print"#################################################";
};
c=0;f=0;i=1}
if ((c==1)&&(substr($0,1,3)!="###")) {s[i++]=substr($0,4,80);
if ($0 ~ /'$1'/ ) f=1}
}' > /tmp/GaLiAwK.$$
# replace the path in the next line
for i in /usd/gap/3.5/lib/*
do
awk -f /tmp/GaLiAwK.$$ $i | more
done
rm /tmp/GaLiAwK.$$
------------- cut here --------------------
Keep in mind that some functions might be kept in the group library
files. So if you don't succeed, you might want to replace 'lib' by
'grp' in above commands.
You can replace the wildcard '*' in above paths by single
filenames. You can get the names of GAPs library files by running 'ls'
in your GAP distributions 'lib' directory.
ls <gap-directory>/lib/*.g
At present the files are
algmat.g field.g matring.g permutat.g abattoir.g cdaggrp.g finfield.g matrix.g polyfin.g agcent.g chartabl.g fpgrp.g module.g polyfld.g agclass.g classfun.g fpsgpres.g monomial.g polynom.g agcomple.g combinat.g fptietze.g morpheus.g polyrat.g agcoset.g ctautoms.g galois.g numfield.g polystff.g agctbl.g ctbasic.g gaussian.g numtheor.g pq.g aggroup.g ctcharac.g group.g onecohom.g ratclass.g aghall.g ctfilter.g grpcoset.g operatio.g rational.g aghomomo.g ctgapmoc.g grpctbl.g permag.g ring.g aginters.g ctgeneri.g grpelms.g permbckt.g rowmodul.g agnorm.g ctlattic.g grphomom.g permcose.g rowspace.g agprops.g ctmapcon.g grplatt.g permcser.g saggroup.g agsubgrp.g ctmapusi.g grpprods.g permctbl.g sagsbgrp.g agwords.g ctpermch.g init.g permgrp.g sq.g algebra.g ctpgrp.g integer.g permhomo.g sqstuff.g algfac.g ctsymmet.g lattperf.g permnorm.g string.g algfld.g cyclotom.g list.g permoper.g tom.g algfp.g dispatch.g mapping.g permprod.g vecspace.g alghomom.g domain.g matgrp.g permstbc.g
Hope this is of some help for now, in the future we intend to put some
of this and related help into the manual.
Joachim Neubueser