#############################################################################
##
#W  access.gd            GAP 4 package `atlasrep'               Thomas Breuer
##
#H  @(#)$Id: access.gd,v 1.47 2004/03/23 09:35:14 gap Exp $
##
#Y  Copyright (C)  2001,  Lehrstuhl D fuer Mathematik,  RWTH Aachen,  Germany
##
##  This file contains functions for low level access to data from the
##  {\ATLAS} of Group Representations.
##
Revision.( "atlasrep/gap/access_gd" ) :=
    "@(#)$Id: access.gd,v 1.47 2004/03/23 09:35:14 gap Exp $";


#############################################################################
##
#V  InfoAtlasRep
##
##  If the info level of `InfoAtlasRep' is at least $1$ then information
##  about `fail' results of functions in the AtlasRep package is printed.
##  If the info level is at least $2$ then information about calls to
##  external programs is printed.
##  The default level is $0$, no information is printed on this level.
##
DeclareInfoClass( "InfoAtlasRep" );


#############################################################################
##
##  Filenames Used in the Atlas of Group Representations
#1
##  The data of each local {\GAP} version of the {\ATLAS} of Group
##  Representations is either private
##  (see Chapter~"Private Extensions of the AtlasRep Package")
##  or is stored in the two directories `datagens' and `dataword'.
##  In the following, we describe the format of filenames in the latter two
##  directories, as a reference of the ``official'' part of the {\ATLAS}.
##
##  In the directory `datagens', the generators for the *representations*
##  available are stored, the directory `dataword' contains the *straight
##  line programs* to compute conjugacy class representatives,
##  \index{class representatives}
##  generators of maximal subgroups,
##  or images of generators under automorphisms
##  \index{automorphisms}
##  of a given group $G$ from standard generators of $G$
##  \index{maximal subgroups}
##  (see~"Standard Generators Used in the AtlasRep Package").
##
##  The name of each data file in the {\ATLAS} of Group Representations
##  describes the contents of the file.
##  This section lists the definitions of the filenames used.
##
##  Each filename consists of two parts, separated by a minus sign `-'.
##  The first part is always of the form `<groupname>G<i>', where the integer
##  <i> denotes the <i>-th set of standard generators for the group $G$, say,
##  with {\ATLAS}-file name <groupname>
##  (see~"Group Names Used in the AtlasRep Package").
##  The translations of the name <groupname> to the name(s) used within
##  {\GAP} is given by the list `AtlasOfGroupRepresentationsInfo.GAPnames'
##  (see~"AtlasOfGroupRepresentationsInfo").
##
##  The filenames in the directory `dataword' have one of the following
##  forms.
##  In each of these cases, the suffix `W<n>' means that <n> is the version
##  number of the straight line program.
##  \beginitems
##  `<groupname>G<i>-cycW<n>' &
##      In this case, the file contains a straight line program that returns
##      a list of representatives of generators
##      of maximally cyclic subgroups of $G$.
##      An example is `Co1G1-cycW1'.
##
##  `<groupname>G<i>-cclsW<n>' &
##      In this case, the file contains a straight line program that returns
##      a list of conjugacy class representatives of $G$.
##      An example is `RuG1-cclsW1'.
##
##  `<groupname>G<i>cycW<n>-cclsW<m>' &
##      In this case, the file contains a straight line program that takes
##      the return value of the program in the file `<groupname>G<i>-cycW<n>'
##      (see above),
##      and returns a list of conjugacy class representatives of $G$.
##      An example is `M11G1cycW1-cclsW1'.
##
##  `<groupname>G<i>-max<k>W<n>' &
##      In this case, the file contains a straight line program that takes
##      generators of $G$ w.r.t.~the <i>-th set of standard generators,
##      and returns a list of generators
##      (in general *not* standard generators)
##      for a subgroup $U$ in the <k>-th class of maximal subgroups of $G$.
##      An example is `J1G1-max7W1'.
##
##  `<groupname>G<i>max<k>W<n>-<subgroupname>G<j>W<m>' &
##      In this case, the file contains a straight line program that takes
##      the return value of the program in the file
##      `<groupname>G<i>-max<k>W<n>' (see above),
##      which are generators for a group $U$, say;
##      <subgroupname> is a name for $U$, and the return value is a list of
##      standard generators for $U$, w.r.t.~the <j>-th set of standard
##      generators.
##      (Of course this implies that the groups in the <k>-th class of
##      maximal subgroups of $G$ are isomorphic to the group with name
##      <subgroupname>.)
##      An example is `J1G1max1W1-L211G1W1';
##      the first class of maximal subgroups of the Janko group $J_1$
##      consists of groups isomorphic to the linear group $L_2(11)$,
##      for which standard generators are defined.
##
##  `<groupname>G<i>-a<outname>W<n>' &
##      In this case, the file contains a straight line program that takes
##      generators of $G$ w.r.t.~the <i>-th set of standard generators,
##      and returns the list of their images
##      under the outer automorphism $\alpha$ of $G$ given by the name
##      <outname>;
##      if this name is empty then $\alpha$ is the unique nontrivial outer
##      automorphism of $G$;
##      if it is a positive integer $k$ then $\alpha$ is a generator of the
##      unique cyclic order $k$ subgroup of the outer automorphism group of
##      $G$;
##      if it is of the form $2_1$ or $2a$, $4_2$ or $4b$, $3_3$ or $3c$
##      $\ldots$ then $\alpha$ generates the cyclic group of automorphisms
##      induced on $G$ by $G\.2_1$, $G\.4_2$, $G\.3_3$ $\ldots$;
##      finally, if it is of the form `<k>p<d>', with <k> one of the above
##      forms and <d> an integer then <d> denotes the number of dashes
##      appended to the automorphism described by <k>;
##      if $<d> = 1$ then <d> can be omitted.
##      Examples are `A5G1-aW1', `L34G1-a2_1W1', `U43G1-a2_3pW1', and
##      `O8p3G1-a2_2p5W1';
##      these file names describe the outer order $2$ automorphism of $A_5$
##      (induced by the action of $S_5$) and the order $2$ automorphisms of
##      $L_3(4)$, $U_4(3)$, and $O_8^+(3)$ induced by the actions of
##      $L_3(4)\.2_1$, $U_4(3)\.2_2^{\prime}$,
##      and $O_8^+(3)\.2_2^{\prime\prime\prime\prime\prime}$, respectively.
##
##  `<groupname>G<i>-G<j>W<n>' &
##      In this case, the file contains a straight line program that takes
##      generators of $G$ w.r.t.~the <i>-th set of standard generators,
##      and returns standard generators of $G$ w.r.t.~the <j>-th set of
##      standard generators.
##      An example is `L35G1-G2W1'.
##
##  `<groupname>G<i>-X<descr>W<n>' &
##      In this case, the file contains a straight line program that takes
##      generators of $G$ w.r.t.~the <i>-th set of standard generators,
##      and whose return value corresponds to <descr>.
##      This format is used only in private extensions
##      (see Chapter~"Private Extensions of the AtlasRep Package"),
##      such a script can be accessed with <descr> as the third argument of
##      `AtlasStraightLineProgram' (see~"AtlasStraightLineProgram").
##  \enditems
##
##  The filenames in the directory `datagens' have one of the following
##  forms.
##  In each of these cases,
##  <id> is a (possibly empty) string that starts with a lowercase alphabet
##  letter (see~"ref:IsLowerAlphaChar" in the {\GAP} Reference Manual),
##  and <m> is a nonnegative integer, meaning that the generators are
##  written w.r.t.~the <m>-th basis (the meaning is defined by the {\ATLAS}
##  developers).
##  \beginitems
##  `<groupname>G<i>-f<q>r<dim><id>B<m>.m<nr>' &
##      a file in {\MeatAxe} textfile format
##      containing the <nr>-th generator of a matrix representation
##      over the field with <q> elements, of dimension <dim>.
##      An example is `S5G1-f2r4aB0.m1'.
##
##  `<groupname>G<i>-p<n><id>B<m>.m<nr>' &
##      a file in {\MeatAxe} textfile format
##      containing the <nr>-th generator of a permutation representation
##      on <n> points.
##      An example is `M11G1-p11B0.m1'.
##
##  `<groupname>G<i>-Ar<dim><id>B<m>.g' &
##      a {\GAP} readable file
##      containing all generators of a matrix representation of dimension
##      <dim> over an algebraic number field not specified further.
##      An example is `A5G1-Ar3aB0.g'.
##
##  `<groupname>G<i>-Zr<dim><id>B<m>.g' &
##      a {\GAP} readable file
##      containing all generators of a matrix representation
##      over the integers, of dimension <dim>.
##      An example is `A5G1-Zr4B0.g'.
##
##  `<groupname>G<i>-Hr<dim><id>B<m>.g' &
##      a {\GAP} readable file
##      containing all generators of a matrix representation
##      over a quaternion algebra over an algebraic number field,
##      of dimension <dim>.
##      An example is `2A6G1-Hr2aB0.g'.
##
##  `<groupname>G<i>-Z<n>r<dim><id>B<m>.g' &
##      a {\GAP} readable file
##      containing all generators of a matrix representation of dimension
##      <dim> over the ring of integers mod <n>.
##      An example is `2A8G1-Z4r4aB0.g'.
##  \enditems
##


#############################################################################
##
#F  AGRParseFilenameFormat( <string>, <format> )
##
##  Let <string> be a filename, and <format> be a list
##  $[ [ c_1, c_2, \ldots, c_n ], [ f_1, f_2, \ldots, f_n ] ]$
##  such that each entry $c_i$ is a list of strings and of functions
##  that take a character as their argument and return `true' or `false',
##  and such that each entry $f_i$ is a function for parsing a filename,
##  such as `ParseForwards' and `ParseBackwards'.
#T add a cross-reference to gpisotyp!
##
##  `AGRParseFilenameFormat' returns a list of strings and integers such that
##  the concatenation of their `String' values yields <string> if <string>
##  matches <format>, and `fail' otherwise.
##  Matching is defined as follows.
##  Splitting <string> at each `-' character yields $m$ parts
##  $s_1, s_2, \ldots, s_m$.
##  The string <string> matches <format> if $s_i$ matches the conditions in
##  $c_i$, for $1 \leq i \leq n$, in the sense that applying $f_i$ to $s_i$
##  and $c_i$ yields a non-fail result.
##
DeclareGlobalFunction( "AGRParseFilenameFormat" );
#T As soon as `gpisotyp' is released, use `ParseBackwardsWithPrefix' here!


#############################################################################
##
#F  FilenameAtlas( <dirname>, <groupname>, <filename> )
##
##  Let <dirname>, <groupname>, and <filename> be strings,
##  where <dirname> is one of `\"datagens\"', `\"dataword\"'.
##  If <groupname> is the {\ATLAS}-file name of a group $G$
##  (see~"Group Names Used in the AtlasRep Package"),
##  and <filename> is the name of an accessible file in the <dirname>
##  directory of the {\ATLAS}, with data concerning $G$,
##  then `FilenameAtlas' returns the corresponding filename
##  (see~"ref:Filename" in the {\GAP} Reference Manual),
##  otherwise `fail' is returned.
##
##  A file is regarded as accessible either if it is already stored in the
##  <dirname> directory of the local installation or if the `remote'
##  component of the record `AtlasOfGroupRepresentationsInfo' has value
##  `true' (see~"AtlasOfGroupRepresentationsInfo") and the required file
##  is found on one of the relevant servers;
##  in the latter case, the file is transferred to the local directory
##  before `FilenameAtlas' returns the filename,
##  such that afterwards the file can be read into {\GAP} using `Read'
##  (see~"ref:Read" in the {\GAP} Reference Manual).
##
##  Note that if a file with name <filename> is already stored in the
##  <dirname> directory then `FilenameAtlas' does *not* check whether the
##  table of contents of the {\ATLAS} of Group Representations actually
##  contains <filename>.
##
DeclareGlobalFunction( "FilenameAtlas" );


#############################################################################
##
##  The Tables of Contents of the Atlas of Group Representations
#2
##  The list of data currently available is stored in two tables of contents,
##  one for the local {\GAP} installation, one for the remote servers.
##  They are created and accessed automatically when
##  `ReloadAtlasTableOfContents' (see~"ReloadAtlasTableOfContents")
##  is called.
##
##  The low level functions used by `ReloadAtlasTableOfContents' are
##  `AtlasTableOfContents',
##  which actually fetches and composes the necessary information,
##  and `StringOfAtlasTableOfContents',
##  which translates the filenames into appropriate function calls for
##  notifying them, and creates the string that is to be printed to a file.
##  These functions and the utilities for them can be found in the files
##  `access.gd' and `access.gi' in the `gap' directory of the package.
##
##  Note that it is assumed that the local data directories contain only
##  files that are also available on servers.
##  Private extensions to the database (cf.~"Extending the Atlas Database"
##  and Chapter~"Private Extensions of the AtlasRep Package")
##  cannot be handled by putting the data files into the local directories.
##


#############################################################################
##
#F  DirectoryTree( <string> )
##
##  Assumed that <string> is a string obtained as the output of a `ls -R'
##  call,
##  `DirectoryTree' returns a record containing for each plain file with name
##  <name> in the directory the component <name> with value an empty record,
##  and for each subdirectory with name <dir> a component <dir> with value a
##  record describing the contents of this subdirectory in the same way.
##
DeclareGlobalFunction( "DirectoryTree" );


#############################################################################
##
#F  AtlasFilesFromDirectoryTree( <tree> )
##
##  Let <tree> be a record as returned by `DirectoryTree' when this was
##  applied to the directory <path> of a server given by the pair
##  `[ <servername>, <path> ]' (see~"AtlasOfGroupRepresentationsInfo").
##
##  `AtlasFilesFromDirectoryTree' checks whether the names of the directories
##  containing the data files are notified correctly,
##  and whether new such directories have appeared that are not yet notified.
##  The return value is a list of triples of the form
##  `[ <dir>, <simp>, <file> ]'.
##  If an error happened then `fail' is returned.
##
##  Note that this function does *not* work for local installations of the
##  package
##  (see~"Local or Remote Installation of the AtlasRep Package").
##
DeclareGlobalFunction( "AtlasFilesFromDirectoryTree" );


#############################################################################
##
#F  AtlasFilesFromPrivateDirectoryTree( <tree> )
##
##  Let <tree> be a record as returned by `DirectoryTree' when this was
##  applied to a private data directory <private>, say.
##
##  `AtlasFilesFromPrivateDirectoryTree' returns the list of pairs
##  `[ <dirname>, <filename> ]' describing the files in the subdirectories
##  `datagens' and `dataword' of the directory <private>,
##  where <dirname> is the path of the file, relative to <private>.
##
DeclareGlobalFunction( "AtlasFilesFromPrivateDirectoryTree" );


#############################################################################
##
#F  GroupNamesOfAtlasOfGroupRepresentations( <list> )
##
##  Let <list> be the return value of `AtlasFilesFromDirectoryTree'
##  (see~"AtlasFilesFromDirectoryTree").
##
##  `GroupNamesOfAtlasOfGroupRepresentations' returns the sorted list of all
##  triples to be stored as value of the `groupnames' component of
##  `AtlasOfGroupRepresentationsInfo' (see~"AtlasOfGroupRepresentationsInfo")
##  if the `TableOfContents' component is replaced by the record to be
##  computed from <list>.
##
##  If <list> contains entries that describe files for a group name in
##  different directories then only those for the first directory are kept,
##  the others are unbound.
##
##  If the level of `InfoAtlasRep' (see~"InfoAtlasRep") is at least $1$
##  then information is printed about illegal names met.
##
DeclareGlobalFunction( "GroupNamesOfAtlasOfGroupRepresentations" );


#############################################################################
##
#F  AGRGNAN( <gapname>, <atlasname> )
##
##  Let <gapname> be a string denoting a {\GAP} group name,
##  and <atlasname> be a string denoting the corresponding {\ATLAS}-file name
##  used in filenames of the {\ATLAS} of Group Representations.
##  `AGRGNAN' adds the pair `[ <gapname>, <atlasname> ]' to the list
##  `AtlasOfGroupRepresentationsInfo.GAPnames'
##  (see~"AtlasOfGroupRepresentationsInfo"),
##  making the {\ATLAS} data involving <atlasname> accessible for
##  the group with name <gapname>.
##
##  An example of a valid call is
##  `AGRGNAN(\"A6.2_2\",\"PGL29\")'.
##
DeclareGlobalFunction( "AGRGNAN" );


#############################################################################
##
#F  AGRFLD( <filename>, <descr> )
##
##  Let <filename> be a string denoting the name of a file containing the
##  generators of a representation written over a proper extension of the
##  rational number field, and <descr> be a string describing the field
##  generated by the matrix entries.
##  `AGRFLD' adds the triple `[ <filename>, <descr>, <F> ]' to the list
##  `AtlasOfGroupRepresentationsInfo.fieldinfo'
##  (see~"AtlasOfGroupRepresentationsInfo"),
##  where <F> is the field given by <descr>.
##
##  An example of a valid call is
##  `AGRFLD(\"A5G1-Ar3aB0\",\"Field([Sqrt(5)])\")'.
##
DeclareGlobalFunction( "AGRFLD" );


#############################################################################
##
#F  AtlasDataCharacteristicZeroFile( <filename> )
##
##  Let <filename> be the name of a file containing the generators of a
##  representation in characteristic zero such that reading the file via
##  `ReadAsFunction' yields a record containing the list of the generators
##  and additional information.
##  Then `AtlasDataCharacteristicZeroFile' returns this record.
##
DeclareGlobalFunction( "AtlasDataCharacteristicZeroFile" );


#############################################################################
##
#F  AtlasStringOfFieldOfMatrixEntries( <mats> )
#F  AtlasStringOfFieldOfMatrixEntries( <filename> )
##
##  For a nonempty list <mats> of matrices of cyclotomics,
##  let $F$ be the field generated by all matrix entries.
##  `AtlasStringOfFieldOfMatrixEntries' returns a pair $[ F, <descr> ]$
##  where <descr> is a string describing $F$, as follows.
##  If $F$ is a quadratic field then <descr> is of the form
##  `\"Field([Sqrt(<n>)])\"' where <n> is an integer;
##  if $F$ is the <n>-th cyclotomic field, for a positive integer <n>
##  then <descr> is of the form `\"Field([E(<n>)])\"';
##  otherwise <descr> is the `String' value
##  (see~"ref:String" in the {\GAP} Reference Manual)
##  of the field object.
##
##  If the argument is a string <filename> then <mats> is obtained by reading
##  the file with name <filename> via `ReadAsFunction'.
##
DeclareGlobalFunction( "AtlasStringOfFieldOfMatrixEntries" );


#############################################################################
##
#F  AtlasTableOfContents( <dirname> )
##
##  `AtlasTableOfContents' returns a record with components `groupnames' and
##  `TableOfContents'.
##
##  If <dirname> is the string `\"local\"' or the name of a private data
##  directory then the value of the `groupnames' component is equal to the
##  value of `AtlasOfGroupRepresentationsInfo.groupnames';
##  if <dirname> is `\"remote\"' then the value of the `groupnames'
##  component is the union of this list and the list of triples corresponding
##  to the groups currently available on the servers
##  (see~"AtlasOfGroupRepresentationsInfo").
##
##  The value of the `TableOfContents' component is a record whose components
##  are `lastupdated' (date and time of the last update of this table of
##  contents) and the names that occur as the last entries in the
##  `groupnames' triples;
##  the value of each such component is a record with components
##  `perm', `matff', `matalg', `matint', `matmodn', `classes', `maxes',
##  and `maxstd', all lists.
##  If <dirname> is `\"local\"' or the name of a private data directory then
##  the contents of the local {\GAP} installation or of the data directory
##  with this name is considered, otherwise the data available on the servers
##  (see~"AtlasOfGroupRepresentationsInfo").
##
##  Once a (local or remote) table of contents has been computed using
##  `AtlasTableOfContents',
##  it is stored in `AtlasOfGroupRepresentationsInfo.TableOfContents'
##  (see~"AtlasOfGroupRepresentationsInfo"),
##  and is just fetched when `AtlasTableOfContents' is called again.
##  Recomputation can be forced using `ReloadAtlasTableOfContents'
##  (see~"ReloadAtlasTableOfContents").
##
##  If <dirname> is different from `\"remote\"' then
##  `AtlasTableOfContents' needs the system program `ls'.
##
DeclareGlobalFunction( "AtlasTableOfContents" );


#############################################################################
##
#F  ReloadAtlasTableOfContents( <dirname> )
##
##  Let <dirname> be a string, which must be `\"local\"', `\"remote\"' or the
##  name of a private data directory
##  (see Chapter~"Private Extensions of the AtlasRep Package").
##  `ReloadAtlasTableOfContents' replaces the table of contents of the
##  AtlasRep package that is described by <dirname> by the one obtained from
##  inspecting the actual contents of the data directories
##  (see~"The Tables of Contents of the Atlas of Group Representations").
##
##  The function returns `fail' if the required table of contents could not
##  be reloaded, otherwise `true' is returned.
##
##  If <dirname> is different from `\"remote\"' then
##  `ReloadAtlasTableOfContents' needs the system program `ls'.
##
DeclareGlobalFunction( "ReloadAtlasTableOfContents" );


#############################################################################
##
#F  StoreAtlasTableOfContents( <filename> )
##
##  Let <filename> be a string. 
##  `StoreAtlasTableOfContents' prints the loaded table of contents of the
##  servers to the file with name <filename>.
##
DeclareGlobalFunction( "StoreAtlasTableOfContents" );


#############################################################################
##  
#F  ReplaceAtlasTableOfContents( <filename> )
##  
##  Let <filename> be the name of a file that has been created with
##  `StoreAtlasTableOfContents' (see~"StoreAtlasTableOfContents").
##
##  `ReplaceAtlasTableOfContents' first removes the information that {\GAP}
##  has stored about the table of contents of the servers,
##  and then reads the file with name <filename>,
##  thus replacing the previous information by the stored one.
##
DeclareGlobalFunction( "ReplaceAtlasTableOfContents" );


#############################################################################
##
#F  AGRGRP( <dirname>, <simpname>, <groupname> )
#F  AGRTOC( <arg> )
##
##  These functions are used to create the initial table of contents for the
##  server data of the AtlasRep package when the file `atlasprm.g' in the
##  `gap' directory of the package is read.
##  Encoding the table of contents in terms of calls to `AGRGRP' and `AGRTOC'
##  is done by `StringOfAtlasTableOfContents'
##  (see~"StringOfAtlasTableOfContents").
##
##  Each call of `AGRGRP' notifies the group with name <groupname>,
##  which is related to the simple group with name <simpname>
##  and for which the data on the servers can be found in the directory
##  with name <dirname>.
##
##  Each call of `AGRTOC' notifies an entry to the `TableOfContents.remote'
##  component of the global variable `AtlasOfGroupRepresentationsInfo'.
##  The arguments must have one of the following forms,
##  which correspond to the possible forms of the names of the data files
##  described in
##  Section~"Filenames Used in the Atlas of Group Representations".
##  In any case <groupname> is a string appearing at third
##  position in an entry of `AtlasOfGroupRepresentationsInfo.groupnames'
##  (see~"AtlasOfGroupRepresentationsInfo"),
##  <gens> is a nonnegative integer denoting the set of standard generators
##  used,
##  and <bas> is an integer denoting that the generators are written
##  w.r.t.~the <bas>-th basis.
##  \beginitems
##  `AGRTOC(<groupname>,<gens>,\"p\",<degree>,<id>,<bas>,<filenames>);' &
##      permutation representation of degree <degree>, specified by <id>,
##      with generators in the files with names in the list <filenames>,
##
##  `AGRTOC(<groupname>,<gens>,\"f\",<q>,<dim>,<id>,<bas>,<filenames>);' &
##      matrix representation over the field with <q> elements,
##      of dimension <dim>, specified by <id>,
##      with generators in the files with names in the list <filenames>,
##
##  `AGRTOC(<groupname>,<gens>,\"Ar\",<dim>,<id>,<bas>,<filename>);' &
##      matrix representation of dimension <dim> over an algebraic number
##      field, specified by <id>,
##      with generators in the file with name <filename>,
##
##  `AGRTOC(<groupname>,<gens>,\"Zr\",<dim>,<id>,<bas>,<filename>);' &
##      matrix representation of dimension <dim> over the integers,
##      specified by <id>,
##      with generators in the file with name <filename>,
##
##  `AGRTOC(<groupname>,<gens>,\"R\",<n>,<dim>,<id>,<bas>,<filename>);' &
##      matrix representation of dimension <dim> over the residue class ring
##      of integers mod <n>, specified by <id>,
##      with generators in the file with name <filename>,
##
##  `AGRTOC(<groupname>,<gens>,\"M\",<n>,<filename>);' &
##      straight line program to compute generators of the <n>-th maximal
##      subgroup, stored in the file with name <filename>,
##
##  `AGRTOC(<groupname>,<gens>,\"MS\",<filename>);' &
##      straight line program to standardize generators of a maximal
##      subgroup, stored in the file with name <filename>,
##
##  `AGRTOC(<groupname>,<gens>,\"C\",<filename>);' &
##      straight line program to compute conjugacy class representatives,
##      or representatives of maximally cyclic subgroups,
##      stored in the file with name <filename>,
##
##  `AGRTOC(<groupname>,<gens>,\"O\",<outname>,<filename>);' &
##      straight line program to compute images of the standard generators
##      under the outer automorphism with name <outname>,
##      stored in the file with name <filename>.
##  \enditems
##
DeclareGlobalFunction( "AGRGRP" );
DeclareGlobalFunction( "AGRTOC" );


#############################################################################
##
#F  StringOfAtlasTableOfContents( \"remote\" )
##
##  If the argument is the string `\"remote\"' then
##  `StringOfAtlasTableOfContents' returns a string that encodes the
##  currently stored value of the table of contents for the remote data
##  of the {\ATLAS} of Group Representations,
##  in terms of calls to `AGRGRP' (see~"AGRGRP") and `AGRTOC' (see~"AGRTOC").
##
##  This function is used for automatically creating updates of the file
##  `atlasprm.g' in the `gap' directory of the AtlasRep package.
##
DeclareGlobalFunction( "StringOfAtlasTableOfContents" );


#############################################################################
#3
##  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.)
##


#############################################################################
##
#F  AtlasOfGroupRepresentationsNotifyPrivateDirectory( <dirname>[, <dirid>] )
##
##  Let <dirname> be a string denoting the name of a directory,
##  such that `Directory( <dirname> )' is the {\GAP} object describing this
##  directory (see~"ref:Directory" in the {\GAP} Reference Manual).
##  This means that <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~"Accessing Data of the AtlasRep Package") for data contained in the
##  directory with name <dirname>.
##  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 with name <dirname> to the AtlasRep package.
##  First the pair `[ <dirname>, <dirid> ]' is added to the global variable
##  `AtlasOfGroupRepresentationsInfo.private'.
##  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"),
##  for adding field information for characteristic zero representations
##  (see~"AGRFLD"),
##  or for adding new data types (see~"Data Types").
##  Next the table of contents of the private directory is built from the
##  list of files contained in (subdirectories of) the private directory.
##
##  Only those files are considered whose names match an admissible format
##  (see~"Filenames Used in the Atlas of Group Representations"
##  and~"Data Types").
##  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' (see~"InfoAtlasRep") 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' is at least $1$
##  then a message about these names is printed.
##
##  The function returns `true' if none of the filenames with admissible
##  format in the directory is contained in other data directories
##  and if the data belongs to groups whose names have been declared.
##  Otherwise `false' is returned.
##
DeclareGlobalFunction( "AtlasOfGroupRepresentationsNotifyPrivateDirectory" );


#############################################################################
##
#F  AtlasOfGroupRepresentationsForgetPrivateDirectory( <dirid> )
##
##  If <dirid> is the identifier of a private data directory that has been
##  notified with `AtlasOfGroupRepresentationsNotifyPrivateDirectory'
##  (see~"AtlasOfGroupRepresentationsNotifyPrivateDirectory")
##  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.
##
DeclareGlobalFunction( "AtlasOfGroupRepresentationsForgetPrivateDirectory" );


#############################################################################
##
#E

