3 Private Extensions of the AtlasRep Package
  
  It  may  be  interesting  to use the functions of the GAP interface also for
  representations  or  programs  that  are  not  part  of  the  ATLAS of Group
  Representations. This chapter describes how to achieve this.
  
  The  main idea is that users can notify directories containing the "private"
  data files, which may consist of
  
  (1)   new  representations and programs for groups that are declared already
        in the "official" ATLAS of Group Representations,
  
  (2)   the  declaration  of  groups  that  are not declared in the "official"
        ATLAS  of  Group Representations, and representations and programs for
        them, and
  
  (3)   the definition of new kinds of representations and programs.
  
  The  first two kinds are dealt with in Section 3.1 and Section 3.2. The last
  is described in Section 5.5.
  
  Finally, an example of using private extensions is given in Section 3.3.
  
  Several  of  the sanity checks for the official part of the AtlasRep package
  make   sense   also   for  private  extensions,  see  Section 5.8  for  more
  information.
  
  
  3.1 Adding a Private Data Directory
  
  After the AtlasRep package has been loaded into the GAP session, one can add
  private  data.  However,  one should not add private files to the local data
  directories  of the package, or modify files in these directories. It should
  be  noted  that  a data file is fetched from a server only if the local data
  directories  do  not  contain  a  file  with  this  name, independent of the
  contents  of the files. (As a consequence, corrupted files in the local data
  directories are not automatically replaced by a correct server file.)
  
  3.1-1 AtlasOfGroupRepresentationsNotifyPrivateDirectory
  
  > AtlasOfGroupRepresentationsNotifyPrivateDirectory( dir[, dirid] ) function
  Returns:  true  if  none  of  the  filenames  with  admissible format in the
            directory  dir  is  contained in other data directories and if the
            data  belongs  to groups whose names have been declared, otherwise
            false.
  
  Let  dir  be a directory (see 'Reference: Directories') or a string denoting
  the  name of a directory (such that the GAP object describing this directory
  can  be  obtained  by  calling  Directory  (Reference:  Directory)  with the
  argument  dir).  In the following, let dirname be the name of the directory.
  So  dirname can be an absolute path or a path relative to the home directory
  of  the  user  (starting with a tilde character ~) or a path relative to the
  directory where GAP was started.
  
  If  the second argument dirid is given, it must be a string. This value will
  be  used  in  the  identifier components of the records that are returned by
  interface  functions  (see  Section 2.5) for data contained in the directory
  dir. Note that the directory name may be different in different GAP sessions
  or  for  different  users  who  want  to  access  the same data, whereas the
  identifier  components shall be independent of such differences. The default
  for dirid is dirname.
  
  AtlasOfGroupRepresentationsNotifyPrivateDirectory  notifies  the data in the
  directory  dir to the AtlasRep package. First the pair [ dirname, dirid ] is
  added  to  the private component of AtlasOfGroupRepresentationsInfo (5.1-5).
  If the directory contains a file with the name toc.g then this file is read;
  this  file  is  useful for adding new group names (see AGRGNAN (5.7-1)), for
  adding field information for characteristic zero representations (see AGRRNG
  (5.7-2)),  or for adding new data types (see Section 5.5). Next the table of
  contents  of the private directory is built from the list of files contained
  in the private directory or in its subdirectories (one layer deep).
  
  Only  those files are considered whose names match an admissible format (see
  Section 5.6). Filenames that are already contained in another data directory
  of  the AtlasRep package are ignored, and messages about these filenames are
  printed if the info level of InfoAtlasRep (5.1-1) is at least 1.
  
  Note  that  this implies that the files of the "official" (i.e. non-private)
  data directories have priority over files in private directories.
  
  If  the  directory  contains  files  for  groups  whose  names have not been
  declared  before and if the info level of InfoAtlasRep (5.1-1) is at least 1
  then a message about these names is printed.
  
  For  convenience,  the  user  may  collect the notifications of private data
  directories in the file .gaprc (see Section 'Reference: The .gaprc file').
  
  3.1-2 AtlasOfGroupRepresentationsForgetPrivateDirectory
  
  > AtlasOfGroupRepresentationsForgetPrivateDirectory( dirid ) _______function
  
  If  dirid  is  the  identifier  of  a  private  data directory that has been
  notified with AtlasOfGroupRepresentationsNotifyPrivateDirectory (3.1-1) then
  AtlasOfGroupRepresentationsForgetPrivateDirectory removes the directory from
  the  list of notified private directories; this means that from then on, the
  data in this directory cannot be accessed anymore in the current session.
  
  
  3.2 The Effect of Private Extensions on the User Interface
  
  First suppose that only new groups or new data for known groups are added.
  
  In this case, DisplayAtlasInfo (2.5-1) lists the private representations and
  programs  in  the same way as the "official" data, except that private parts
  are   marked  with  the  string  stored  in  the  component  markprivate  of
  AtlasOfGroupRepresentationsInfo  (5.1-5);  by default, this is a star *. The
  ordering of representations listed by DisplayAtlasInfo (2.5-1) (and referred
  to   by  AtlasGenerators  (2.5-2))  will  in  general  change  when  private
  directories  are  notified. If several private directories are used then the
  ordering  of data may depend on the ordering of notifications. For the other
  interface functions described in Chapter 2, the only difference is that also
  the   private  data  can  be  accessed.  In  particular  the  "free  format"
  groupnameGi-XdescrWn  for  straight  line  programs (see Section 5.6) may be
  used  in  private  directories;  the  data can be accessed with AtlasProgram
  (2.5-3), where the last two arguments are the strings "other" and descr.
  
  If  also private data types are introduced (see Section 5.5) then additional
  columns  or  rows  can appear in the output of DisplayAtlasInfo (2.5-1), and
  new  inputs  can become meaningful for all interface functions. Examples for
  these changes can be found in Section 3.3.
  
  
  3.3 An Example of Extending the AtlasRep Package
  
  In the beginning we set the info level of InfoAtlasRep (5.1-1) to 1.
  
  ---------------------------  Example  ----------------------------
    gap> level:= InfoLevel( InfoAtlasRep );;
    gap> SetInfoLevel( InfoAtlasRep, 1 );
  ------------------------------------------------------------------
  
  Let  us assume that the directory privdir contains data for the cyclic group
  C_4  of  order  4 and for the symmetric group S_5 on 5 points, respectively.
  Note  that  it  is obvious what the term "standard generators" means for the
  group C_4.
  
  Further let us assume that privdir contains the following files.
  
  C4G1-p4B0.m1
        a faithful permutation representation of C_4 on 4 points,
  
  C4G1-max1W1
        the straight line program that returns the square of its unique input,
  
  C4G1-a2W1
        the  straight  line  program that applies an outer automorphism to its
        unique input,
  
  C4G1-XtestW1
        the straight line program that returns the square of its unique input,
  
  S5G1-p2B0.m1 and S5G1-p2B0.m2
        the  permutation representation of the commutator factor group of S_5,
        on 2 points.
  
  The directory and the files can be created as follows.
  
  ---------------------------  Example  ----------------------------
    gap> pkg:= Filename( DirectoriesPackageLibrary( "atlasrep", "" ), "" );;
    gap> prv:= DirectoryTemporary( "privdir" );;
    gap> FileString( Filename( prv, "C4G1-p4B0.m1" ),
    >                MeatAxeString( [ (1,2,3,4) ], 4 ) );;
    gap> FileString( Filename( prv, "C4G1-max1W1" ),
    >                "inp 1\npwr 2 1 2\noup 1 2\n" );;
    gap> FileString( Filename( prv, "C4G1-XtestW1" ),
    >                "inp 1\npwr 2 1 2\noup 1 2\n" );;
    gap> FileString( Filename( prv, "C4G1-a2W1" ),
    >                "inp 1\npwr 3 1 2\noup 1 2\n" );;
    gap> FileString( Filename( prv, "C4G1-Ar1aB0.g" ),
    >                "return rec( generators:= [ [[E(4)]] ] );\n" );;
    gap> FileString( Filename( prv, "S5G1-p2B0.m1" ),
    >                MeatAxeString( [ (1,2) ], 2 ) );;
    gap> FileString( Filename( prv, "S5G1-p2B0.m2" ),
    >                MeatAxeString( [ (1,2) ], 2 ) );;
  ------------------------------------------------------------------
  
  (We  could also introduce intermediate directories C4 and S5, say, each with
  the  data  for  one  group  only.  Here we do not show this because creating
  directories seems to be not possible without the GAP package IO.)
  
  Now  we create a file whose name is not admissible because it occurs already
  in the official part of the database. (This will cause an info line below.)
  
  ---------------------------  Example  ----------------------------
    gap> FileString( Filename( prv, "S5G1-p5B0.m1" ),
    >                MeatAxeString( [ (1,2) ], 5 ) );;
  ------------------------------------------------------------------
  
  The official part of the AtlasRep package does not contain information about
  C_4,  so  we  first notify this group, in the file privdir/toc.g. (The group
  S_5 is known with name A5.2 in the official part of the AtlasRep package, so
  it cannot be notified.)
  
  ---------------------------  Example  ----------------------------
    gap> FileString( Filename( prv, "toc.g" ),
    >                "AGRGNAN(\"C4\",\"C4\");\n" );;
  ------------------------------------------------------------------
  
  Then we notify the private directory.
  
  ---------------------------  Example  ----------------------------
    gap> AtlasOfGroupRepresentationsNotifyPrivateDirectory( prv, "priv" );
    #I  file `S5G1-p5B0.m1' was already in another t.o.c.
    false
  ------------------------------------------------------------------
  
  (The  nonadmissible  filename  S5G1-p5B0.m1  was  ignored  for  the  private
  directory.  If this file would not be present then the return value would be
  true.)  Now we can use the interface functions for accessing the data in the
  private directory.
  
  ---------------------------  Example  ----------------------------
    gap> DisplayAtlasInfo( [ "C4" ] );
    group    #  maxes  cl  cyc  out  find  check  pres
    --------------------------------------------------
    C4*      2      1   -    -    2     -      -     -
    gap> DisplayAtlasInfo( "C4" );
    Representations for G = C4:    (all refer to std. generators 1)
    ---------------------------
    1: G <= Sym(4)*
    2: G <= GL(1a,C)*
    
    Programs for G = C4:    (all refer to std. generators 1)
    --------------------
    available maxes of G:  [ 1 ]*
    available automorphisms:  [ "2" ]*
    available other scripts:
       "test"*
    gap> DisplayAtlasInfo( "C4", IsPermGroup, true );
    Representations for G = C4:    (all refer to std. generators 1)
    ---------------------------
    1: G <= Sym(4)*
    gap> DisplayAtlasInfo( "C4", IsMatrixGroup );
    Representations for G = C4:    (all refer to std. generators 1)
    ---------------------------
    2: G <= GL(1a,C)*
    gap> DisplayAtlasInfo( "C4", Dimension, 2 );
    gap> DisplayAtlasInfo( "A5.2", NrMovedPoints, 2 );
    Representations for G = A5.2:    (all refer to std. generators 1)
    -----------------------------
    4: G <= Sym(2)*
    gap> info:= OneAtlasGeneratingSetInfo( "C4" );
    rec( groupname := "C4", standardization := 1, repnr := 1, 
      identifier := [ [ "priv", "C4" ], [ "C4G1-p4B0.m1" ], 1, 4 ], p := 4, 
      id := "" )
    gap> AtlasGenerators( info.identifier );
    rec( generators := [ (1,2,3,4) ], groupname := "C4", standardization := 1,
      repnr := 1, identifier := [ [ "priv", "C4" ], [ "C4G1-p4B0.m1" ], 1, 4 ], 
      p := 4, id := "" )
    gap> AtlasProgram( "C4", 1 );
    rec( program := <straight line program>, standardization := 1, 
      identifier := [ [ "priv", "C4" ], "C4G1-max1W1", 1 ], groupname := "C4" )
    gap> AtlasProgram( "C4", "maxes", 1 );
    rec( program := <straight line program>, standardization := 1, 
      identifier := [ [ "priv", "C4" ], "C4G1-max1W1", 1 ], groupname := "C4" )
    gap> AtlasProgram( "C4", "maxes", 2 );
    fail
    gap> AtlasGenerators( "C4", 1 );
    rec( generators := [ (1,2,3,4) ], groupname := "C4", standardization := 1,
      repnr := 1, identifier := [ [ "priv", "C4" ], [ "C4G1-p4B0.m1" ], 1, 4 ], 
      p := 4, id := "" )
    gap> AtlasGenerators( "C4", 2 );
    rec( generators := [ [ [ E(4) ] ] ], groupname := "C4", standardization := 1,
      repnr := 2, identifier := [ [ "priv", "C4" ], "C4G1-Ar1aB0.g", 1, 1 ], 
      dim := 1, id := "a" )
    gap> AtlasGenerators( "C4", 3 );
    fail
    gap> AtlasProgram( "C4", "other", "test" );
    rec( program := <straight line program>, standardization := 1, 
      identifier := [ [ "priv", "C4" ], "C4G1-XtestW1", 1 ], groupname := "C4" )
  ------------------------------------------------------------------
  
  For  checking the data in the private directory, we apply some of the sanity
  checks (see Section 5.8).
  
  ---------------------------  Example  ----------------------------
    gap> AtlasOfGroupRepresentationsTestWords( "priv" );
    true
    gap> AtlasOfGroupRepresentationsTestFileHeaders( "priv" );
    true
  ------------------------------------------------------------------
  
  Finally, we "uninstall" the private directory, and reset the info level that
  had  been set to 1 in the beginning. (Also the group name C4 is removed this
  way,  which  is  an  advantage  of  using  a toc.g file over calling AGRGNAN
  (5.7-1)  directly.),  Note that we need not remove the data in the temporary
  directory, GAP will do this automatically.
  
  ---------------------------  Example  ----------------------------
    gap> AtlasOfGroupRepresentationsForgetPrivateDirectory( "priv" );
    gap> SetInfoLevel( InfoAtlasRep, level );
  ------------------------------------------------------------------