#############################################################################
##
#W  types.gd             GAP 4 package `atlasrep'               Thomas Breuer
##
#H  @(#)$Id: types.gd,v 1.15 2003/11/05 11:13:52 gap Exp $
##
#Y  Copyright (C)  2001,  Lehrstuhl D fuer Mathematik,  RWTH Aachen,  Germany
##
##  This file contains declarations of the functions for administrating
##  the data types used in the {\ATLAS} of Group Representations.
##
Revision.( "atlasrep/gap/types_gd" ) :=
    "@(#)$Id: types.gd,v 1.15 2003/11/05 11:13:52 gap Exp $";


#############################################################################
##
#F  AGRDeclareDataType( <kind>, <name>, <record> )
##
##  Let <kind> be one of the strings `\"rep\"' or `\"slp\"',
##  and <record> be a record.
##  `AGRDeclareDataType' declares a new data type of representations
##  (if <kind> is `\"rep\"') or of straight line programs (if <kind> is
##  `\"slp\"').
##  For each group used in the AtlasRep package, the record that contains the
##  information about the data will have a component <name> whose value is a
##  list with the data about the new type.
##  Examples of <name> are `\"perm\"', `\"matff\"', and `\"classes\"'.
##
##  *Compulsory components* of <record> are
##  \beginitems
##  `FilenameFormat' &
##      This defines the format of the filenames containing data of the type
##      in question.
##      The value must be a list that can be used as the second argument of
##      `AGRParseFilenameFormat' (see~"AGRParseFilenameFormat"), such that
##      only filenames of the type in question match.
##
##  `AddFileInfo' &
##      This defines the information stored in the table of contents for the
##      data of the type.
##      The value must be a function that takes three arguments (the current
##      list of data for the type and the given group, a list returned
##      by `AGRParseFilenameFormat' for the given type,
##      see~"AGRParseFilenameFormat", and a filename).
##      This function adds the necessary parts of the data entry to the list,
##      and returns `true' if the data belongs to the type,
##      otherwise `false' is returned;
##      note that the latter case occurs if the filename matches the format
##      description but additional conditions on the parts of the name are
##      not satisfied (for example integer parts may be required to be
##      positive or prime powers).
##
##  `DisplayGroup' (for `rep' only) &
##      This defines the format of the lines printed by `DisplayAtlasInfo'
##      (see~"DisplayAtlasInfo") for a given group.
##      The value must be a function that takes a list as returned by the
##      function given in the component `AddFileInfo', and returns the string
##      to be printed for the representation in question.
##  \enditems
##
##  *Optional components* of <record> are
##  \beginitems
##  `DisplayOverviewInfo' &
##      This is used to introduce a new column in the output of
##      `DisplayAtlasInfo' (see~"DisplayAtlasInfo") when this is called
##      without arguments or with a list of group names as its only argument.
##      The value must be a list of length three, containing at its first
##      position a string used as the header of the column, at its second
##      position one of the strings `\"r\"' or `\"l\"', denoting right or
##      left aligned column entries, and at its third position a function
##      that takes two arguments (a list of tables of contents of the
##      AtlasRep package and a group name), and returns a list of length two,
##      containing the string to be printed as the column value and `true' or
##      `false', depending on whether private data is involved or not.
##      (The default is to print no column for the data type.)
##
##  `DisplaySLP' (for `slp' only) &
##      This is used in `DisplayAtlasInfo' for straight line programs.
##      The value must be a function that takes four arguments (a list of
##      tables of contents to examine, the name of the given group,
##      a list of integers or `true' for the required standardization,
##      and a list of all available standardizations), and returns the list
##      of lines (strings) to be printed as the information about the
##      available straight line programs of the current type
##      and for the given group.
##      (The default is to return an empty list.)
##
##  `AccessGroupCondition' (for `rep' only) &
##      This is used in `DisplayAtlasInfo' and `OneAtlasGeneratingSet'.
##      The value must be a function that takes two arguments (a list as
##      returned by `AGRParseFilenameFormat', see~"AGRParseFilenameFormat",
##      and a list of conditions --see below),
##      and returns `true' or `false', depending on whether the first
##      argument satisfies the conditions.
##      (The default value is `ReturnFalse'.)
##
##  `AccessSLP' (for `slp' only) &
##      This is used in `AtlasStraightLineProgram'
##      (see~"AtlasStraightLineProgram").
##      The value must be a function that takes three arguments (the record
##      with the information about the given group in the current table of
##      contents, an integer or a list of integers or `true' for the
##      required standardization, and a list of conditions --see below),
##      and returns either `fail' or a list that together with the group name
##      forms the identifier of a straight line program that matches the
##      conditions.
##      (The default value is `ReturnFail'.)
##
##  `TOCEntryString' &
##      This is used in `StringOfAtlasTableOfContents', so it is needed only
##      for those data types for which data is stored in the official part.
##      The value must be a function that takes two arguments
##      (the name <name> of the type and a list as returned by
##      `AGRParseFilenameFormat', see~"AGRParseFilenameFormat")
##      and returns a string that describes the appropriate function call.
##      (The default value is `TOCEntryStringDefault'.)
##
##  `PostprocessFileInfo' &
##      This is used in the construction of a table of contents via
##      `ReloadAtlasTableOfContents', for testing or rearranging the data of
##      the current table of contents.
##      The value must be a function that takes two arguments,
##      the table of contents record and the record in it that belongs to
##      one fixed group.
##      (The default value is `Ignore'.)
##
##  `SortTOCEntries' &
##      This is used in the construction of a table of contents via
##      `AtlasTableOfContents', for sorting the entries after they have been
##      added and after `PostprocessFileInfo' has been called.
##      The value must be a function that takes a list as returned by
##      `AGRParseFilenameFormat' (see~"AGRParseFilenameFormat"),
##      and returns the sorting key.
##      (There is no default value, which means that no sorting is needed.)
##
##  `TestFileHeaders' (for `rep' only) &
##      This is used in the function
##      `AtlasOfGroupRepresentationsTestFileHeaders'
##      (see~"AtlasOfGroupRepresentationsTestFileHeaders").
##      The value must be a function that takes the same three arguments as
##      `FilenameAtlas' (see~"FilenameAtlas"), except that the first
##      argument `\"datagens\"' can be replaced by `\"local\"' and that the
##      third argument is a list as returned by `AGRParseFilenameFormat'
##      (see~"AGRParseFilenameFormat").
##      (The default value is `ReturnTrue'.)
##
##  `TestFiles' (for `rep' only) &
##      This is used in the function `AtlasOfGroupRepresentationsTestFiles'.
##      (see~"AtlasOfGroupRepresentationsTestFiles").
##      The format of the value and the default are the same as for
##      `TestFileHeaders'.
##
##  `TestWords' (for `slp' only) &
##      This is used in the function `AtlasOfGroupRepresentationsTestWords'
##      (see~"AtlasOfGroupRepresentationsTestWords").
##      The value must be a function that takes the same three arguments as
##      `FilenameAtlas' (see~"FilenameAtlas"), except that the first
##      argument `\"dataword\"' can be replaced by `\"local\"'.
##      (The default is to call `AGRTestWordsDefault' with fourth argument
##      `false'.)
##  \enditems
##
##  The lists of conditions used as arguments of `AccessGroupCondition' and
##  `AccessSLP' usually contain functions such as `IsPermGroup', which are
##  just checked for presence, and functions such as `NrMovedPoints' followed
##  by a prescribed value or a list of prescribed values.
##  Examples of such conditions are `[ IsPermGroup ]' and
##  `[ NrMovedPoints, [ 5, 6 ] ]'.
##  
##  Note that it is not checked whether the ``detection function'' in the
##  component `FilenameFormat' matches exactly one type,
##  so one must be very careful when declaring a new type.
##
DeclareGlobalFunction( "AGRDeclareDataType" );


#############################################################################
##
#F  AGRDataTypes( <kind1>[, <kind2>] )
##
##  returns the list of pairs `[ <name>, <record> ]' as declared for
##  the kinds in question
##
DeclareGlobalFunction( "AGRDataTypes" );


#############################################################################
##
#V  AtlasOfGroupRepresentationsInfo
##
##  `AtlasOfGroupRepresentationsInfo' is a record that is set in the file
##  `gap/types.g' of the package.
##  It has the following components.
##  \beginitems
##  `remote' &
##      a boolean that controls what files are available;
##      if the value is `true' then {\GAP} is allowed to try remotely
##      accessing any {\ATLAS} file from the servers (see below) and thus all
##      files listed in the global table of contents are available,
##      if the value is `false' then {\GAP} may access
##      only those files that are stored in the database directories of the
##      local {\GAP} installation
##      (see~"Local or Remote Installation of the AtlasRep Package"),
##
##  `compress' &
##      \index{gzip}%
##      a boolean that controls whether {\MeatAxe} format files are stored in
##      compressed form;
##      if the value is `true' then these files are compressed with `gzip'
##      after they have been fetched from a server
##      (see~"User Parameters for the AtlasRep Package"),
##
##  `wget' (optional) &
##      \index{perl}%
##      \index{wget}%
##      if this is bound to `true' then {\GAP} uses `wget' to fetch data
##      files, otherwise `perl' is used
##      (see the manual index for references),
##
##  `servers' &
##      \index{ftp}%
##      a list of quadrupels `[ <server>, <path>, <login>, <password> ]',
##      where <server> is a string denoting the `ftp' address of a server
##      where files can be fetched that are not stored in the local database,
##      <path> is a string describing the path where the data directories
##      on the server reside
##      (relative to the directory entered via `ftp' login),
##      <login> is the login name for the server access,
##      and <password> is the corresponding password;
##      only this list must be adjusted if new servers are added or if the
##      addresses of servers change,
##
##  `dirnames' &
##      a list of the names of the directories on the servers that contain
##      subdirectories corresponding to the individual groups,
##
##  `GAPnames' &
##      a list of pairs, each containing the {\GAP} name and the
##      {\ATLAS}-file name of a group
##      (see~"Group Names Used in the AtlasRep Package"),
##
##  `groupnames' &
##      a list of triples, each containing at the first position the name of
##      the directory on each server that contains data about the group $G$
##      in question, at the second position the name of the (usually simple)
##      group for which a subdirectory exists that contains the data about
##      $G$, and at the third position the {\ATLAS}-file name used for $G$
##      (see~"Filenames used in the Atlas of Group Representations"),
##
##  `fieldinfo' &
##      a list of triples, each containing at the first position the name of
##      the file with the matrices of a characteristic zero representation,
##      at the second position a string describing the field generated by the
##      matrix entries, and at the third position this field itself;
##      `DisplayAtlasInfo' (see~"DisplayAtlasInfo") displays this information
##      for representations over proper extensions of the rational number
##      field only if the representation is mentioned in the `fieldinfo'
##      list,
##
##  `private' &
##      a list of pairs of strings used for administrating private data
##      (see Chapter~"Private Extensions of the AtlasRep Package"),
##
##  `markprivate' &
##      a string used to mark private data
##      (see~"The Effect of Private Extensions on the User Interface"), and
##
##  `TableOfContents' &
##      a record with at most the components `local', `remote', `types',
##      `data', and the names of private data directories;
##      the values of the components `local' and `remote' can be computed
##      automatically by
##      `ReloadAtlasTableOfContents' (see~"ReloadAtlasTableOfContents"),
##      and the values of the components for local data directories are
##      created by `AtlasOfGroupRepresentationsNotifyPrivateDirectory'
##      (see~"AtlasOfGroupRepresentationsNotifyPrivateDirectory").
##  \enditems
##

#DeclareGlobalVariable( "AtlasOfGroupRepresentationsInfo" );


#############################################################################
##
#A  Maxes( <tbl> )
##
##  In some consistency checks, the {\GAP} Character Table Library is used.
##  Since the AtlasRep package does not require the table library,
##  we declare the missing variables in order to avoid error messages.
##
if not IsBound( Maxes ) then
  DeclareAttribute( "Maxes", IsUnknown );
  InstallMethod( Maxes, [ IsUnknown ], Error );
fi;


#############################################################################
##
##  We want to delay reading the table of contents until the data is really
##  accessed.
##
DeclareAutoreadableVariables( "atlasrep", "gap/types.g",
      [ "AtlasOfGroupRepresentationsInfo" ] );


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

