gap-online-help 4r7p9-1 / usr / share / gap / doc / ref / chap83.txt

  
  83 Library Files
  
  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).
  
  
  83.1 File Types
  
  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.
  
  
  83.2 Finding Implementations in the Library
  
  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  (BrowseGapMethods???)  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  (BrowseProfile???)  shows profiling results (similar to
        DisplayProfile  (7.7-8))  and allows one to navigate through the files
        that  contain  the implementations of the functions that were actually
        used, using a pager.
  
  
  83.3 Undocumented Variables
  
  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  mailto:support@gap-system.org 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.