Quelle access.gi Sprache: unbekannt

Spracherkennung für: .gi vermutete Sprache: Unknown {[0] [0] [0]} [Methode: Schwerpunktbildung, einfache Gewichte, sechs Dimensionen]

#############################################################################
##
#W access.gi GAP 4 package AtlasRep Thomas Breuer
##
## This file contains functions for accessing data from the ATLAS of Group
## Representations.
##

#############################################################################
##
#F AGR.InfoRead( <str1>, <str2>, ... )
##
AGR.InfoRead:= function( arg )
 local str;

 if UserPreference( "AtlasRep", "DebugFileLoading" ) = true then
 for str in arg do
 Print( str );
 od;
 fi;
 end;

#############################################################################
##
#F AGR.StringFile( <filename> )
##
## In unfortunate cases, files may contain line breaks of the form "\r\n"
## instead of "\n".
## 'Read' would recognize this situation, and would silently replace these
## line breaks, but 'StringFile' keeps the file contents.
## Therefore we remove the '\r' characters.
##
AGR.StringFile:= function( filename )
 local str;

 AGR.InfoRead( "#I reading `", filename, "' started\n" );
 str:= StringFile( filename );
 AGR.InfoRead( "#I reading `", filename, "' done\n" );
 if IsString( str ) then
 str:= ReplacedString( str, "\r", "" );
 fi;

 return str;
 end;

#############################################################################
##
#F AGR.ExtensionInfoCharacterTable
#F AGR.HasExtensionInfoCharacterTable
#F AGR.LibInfoCharacterTable
##
## If the CTblLib package is not available then we cannot use these
## functions.
##
if IsBound( ExtensionInfoCharacterTable ) then
 AGR.ExtensionInfoCharacterTable:= ExtensionInfoCharacterTable;
 AGR.HasExtensionInfoCharacterTable:= HasExtensionInfoCharacterTable;
 AGR.LibInfoCharacterTable:= LibInfoCharacterTable;
fi;

#############################################################################
##
#F AGR.IsLowerAlphaOrDigitChar( <char> )
##
AGR.IsLowerAlphaOrDigitChar:=
 char -> IsLowerAlphaChar( char ) or IsDigitChar( char );

#############################################################################
##
#F AGR_ChecksumFits( <string>, <checksum> )
##
BindGlobal( "AGR_ChecksumFits", function( string, checksum )
 if checksum = fail then
 # We cannot check anything.
 return true;
 elif IsString( checksum ) then
 # This is a 'SHA256' format string.
 return checksum = ValueGlobal( "HexSHA256" )( string );
 elif IsInt( checksum ) then
 # This is a 'CrcString' value.
 return checksum = CrcString( string );
 else
 Error( "<chcksum> must be a string or an integer" );
 fi;
end );

#############################################################################
##
## If the IO package is not available then the following assignments have
## the effect that no warnings about unbound variables are printed when this
## file gets read.
##
if not IsBound( IO_mkdir ) then
 IO_mkdir:= "dummy";
fi;
if not IsBound( IO_stat ) then
 IO_stat:= "dummy";
fi;
if not IsBound( IO_chmod ) then
 IO_chmod:= "dummy";
fi;

#############################################################################
##
#F AtlasOfGroupRepresentationsTransferFile( <url>, <localpath>, <crc> )
##
## This function encapsulates the access to the remote file at the address
## <url>.
## 
## If the access failed then <K>false</K> is returned, otherwise
## either the data are written to the local file with filename
## <A>localpath</A> (if this is a string and the user preference
## <C>AtlasRepDataDirectory</C> is nonempty),
## or a string with the contents of the file is returned.
##
BindGlobal( "AtlasOfGroupRepresentationsTransferFile",
 function( url, localpath, crc )
 local savetofile, pref, result, str, out;

 # Save the contents of the target file to a local file?
 # (The first two conditions mean that we *want* to avoid saving,
 # the third deals with the situation that the intended path does not
 # exist, probably due to missing write permissions.)
 savetofile:= not ( localpath = fail or
 IsEmpty( UserPreference( "AtlasRep",
 "AtlasRepDataDirectory" ) ) or
 not IsWritableFile( localpath{ [ 1 .. Last( Positions(
 localpath, '/' ) ) - 1 ] } ) );

 Info( InfoAtlasRep, 2,
 "calling 'Download' with url '", url, "'" );
 if savetofile then
 result:= Download( url, rec( target:= localpath ) );
 elif EndsWith( url, ".gz" ) then
 # We can only download the compressed file and then load it.
 if not IsBound( AGR.TmpDir ) then
 AGR.TmpDir:= DirectoryTemporary();
 fi;
 if AGR.TmpDir = fail then
 return false;
 fi;
 localpath:= Filename( AGR.TmpDir, "currentfile" );
 result:= Download( url, rec( target:= localpath ) );
 if result.success <> true then
 Info( InfoAtlasRep, 2,
 "Download failed" );
 RemoveFile( localpath );
 return false;
 fi;
 # Uncompress and load the contents.
 str:= StringFile( localpath );
 RemoveFile( localpath );
 if not AGR_ChecksumFits( str, crc ) then
 Info( InfoWarning, 1,
 "download of file '", url,
 "' does not yield a string with the expected crc value '",
 crc, "'" );
 return false;
 fi;
 return str;
 else
 # Transfer the file into the GAP session.
 result:= Download( url, rec() );
 fi;

 if result.success <> true then
 Info( InfoAtlasRep, 2,
 "Download failed with message\n#I ", result.error );
 if savetofile and IsExistingFile( localpath ) then
 # This should not happen, 'Download' should have removed the file.
 if RemoveFile( localpath ) <> true then
 Error( "cannot remove corruped file '", localpath, "'" );
 fi;
 fi;
 elif savetofile and not AGR_ChecksumFits( StringFile( localpath ), crc ) then
 Info( InfoWarning, 1,
 "download of file '", url, "' to '", localpath,
 "' does not yield a file with the expected crc value '",
 crc, "'" );
 if RemoveFile( localpath ) <> true then
 Error( "cannot remove corruped file '", localpath, "'" );
 fi;
 elif not savetofile and not AGR_ChecksumFits( result.result, crc ) then
 Info( InfoWarning, 1,
 "download of file '", url,
 "' does not yield a string with the expected crc value '",
 crc, "'" );
 elif savetofile then
 # The file has been downloaded and stored and seems to be o.k.
 return true;
 else
 # The contents has been downloaded and seems to be o.k.
 return result.result;
 fi;

 return false;
end );

#############################################################################
##
#F AGR.AccessFilesLocation( <files>, <type>, <replace>, <compressed> )
##
AGR.AccessFilesLocation:= function( files, type, replace, compressed )
#T type is not used at all!
 local names, pref, pair, dirname, filename, datadirs, info, entry,
 prefjson, name, namegz;

 names:= [];
 pref:= UserPreference( "AtlasRep", "AtlasRepDataDirectory" );
 if pref <> "" and not EndsWith( pref, "/" ) then
 pref:= Concatenation( pref, "/" );
 fi;
 for pair in files do
 dirname:= pair[1];
 filename:= pair[2];
 if dirname in [ "datagens", "dataword" ] then
 datadirs:= [ Directory( Concatenation( pref, dirname ) ) ];
 else
 datadirs:= fail;
 for info in AtlasOfGroupRepresentationsInfo.notified do
 if dirname = info.ID then
 if StartsWith( info.DataURL, "http" ) then
 # local directory of a remote data extension
 datadirs:= [ Directory(
 Concatenation( pref, "dataext/", info.ID ) ) ];
 else
 # local data extension
 datadirs:= [ Directory( info.DataURL ) ];
 entry:= First( AtlasOfGroupRepresentationsInfo.filenames,
 x -> x[1] = filename );
 if entry = fail then
 Error( "do not know about <filename>" );
 fi;
 filename:= entry[2];
 fi;
 break;
 fi;
 od;
 if datadirs = fail then
 Error( "no data extension with identifier '", dirname, "'" );
 fi;
 fi;

 if replace <> fail then
 filename:= ReplacedString( filename, replace[1], replace[2] );
 fi;

 # Hack/experimental:
 # If wanted then switch to a JSON format alternative of
 # characteristic zero matrices (supported only for "datagens").
 if dirname = "datagens" and
 ( PositionSublist( filename, "-Ar" ) <> fail or
 PositionSublist( filename, "-Zr" ) <> fail ) then
 prefjson:= UserPreference( "AtlasRep", "AtlasRepJsonFilesAddresses" );
 if prefjson <> fail then
 # Use Json format files of characteristic zero
 # matrix representations instead of the GAP format files.
 datadirs:= [ Directory( prefjson[2] ) ];
 filename:= ReplacedString( filename, ".g", ".json" );
 fi;
 fi;

 # There may be an uncompressed or a compressed version.
 # If both are available then prefer the uncompressed version.
 # Take the compressed version only if the program 'gunzip'
 # is available.
 name:= Filename( datadirs, filename );
 if name = fail or not IsReadableFile( name ) then
 if compressed and
 Filename( DirectoriesSystemPrograms(), "gunzip" ) <> fail then
 namegz:= Filename( datadirs, Concatenation( filename, ".gz" ) );
 if namegz = fail then
 # No version is available yet.
 Add( names, Filename( datadirs[1], filename ) );
 else
 Add( names, namegz );
 fi;
 else
 # No version is available yet.
 Add( names, Filename( datadirs[1], filename ) );
 fi;
 else
 Add( names, name );
 fi;
 od;

 return names;
 end;

#############################################################################
##
#F AGR.AccessFilesFetch( <filepath>, <filename>, <dirname>
#F <type>, <compressed>, <crc> )
##
## We assume that the local file <filepath> is not yet available,
## and that we have to download the file.
##
## <filepath> is the local path where the file shall be stored if local
## directories are writable (otherwise the content just gets downloaded),
## <filename> is the name part of the file in question.
## <dirname> is one of "datagens", "dataword", or a private id.
## <type> is a type record.
## <compressed> is 'true' or 'false'.
## <crc> is either the expected crc value of the file or 'fail'.
##
## The function returns 'false' if the access failed,
## 'true' if the remote file was copied to a local file,
## and a string containing the contents of the file otherwise.
##
AGR.AccessFilesFetch:= function( filepath, filename, dirname,
 type, compressed, crc )
 local result, iscompressed, info, datadirs, pref, url, pos,
 gzip, gunzip;

 # Try to fetch the remote file.
 result:= fail;
 iscompressed:= false;
 if dirname in [ "datagens", "dataword" ] then
 # This is an 'official' file.
 dirname:= "core";
 fi;

 # The domain is described by the 'notified' list.
 # We are in the case of a remote extension.
 datadirs:= fail;
 for info in AtlasOfGroupRepresentationsInfo.notified do
 if dirname = info.ID then
 if not IsBound( info.data ) then
 # This should happen only for pure local extension,
 Error( "non-available file <filepath> of a local extension?" );
 fi;

 # Fetch the file if possible.
 if EndsWith( filepath, ".json" ) and EndsWith( filename, ".g" ) then
 # Fetch the file from the address given by the user preference
 # 'AtlasRepJsonFilesAddresses'.
 filename:= filepath{ [ Last( Positions( filepath, '/' ) )+1
 .. Length( filepath ) ] };
 crc:= fail;
 pref:= UserPreference( "AtlasRep", "AtlasRepJsonFilesAddresses" );
 url:= pref[1];
 else
 # Use the standard addresses.
 url:= info.DataURL;
 fi;
 if not EndsWith( url, "/" ) then
 url:= Concatenation( url, "/" );
 fi;
 url:= Concatenation( url, filename );

 # First look for an uncompressed file.
 result:= AtlasOfGroupRepresentationsTransferFile( url,
 filepath, crc );

 # In case of private MeatAxe text files
 # and if 'gunzip' is available,
 # look for a compressed version of the file.
 # (This is not supported for "core".)
 if result = false and compressed and dirname <> "core" then
 gunzip:= Filename( DirectoriesSystemPrograms(), "gunzip" );
 if gunzip <> fail and not IsExecutableFile( gunzip ) then
 gunzip:= fail;
 fi;
 if gunzip <> fail then
 result:= AtlasOfGroupRepresentationsTransferFile(
 Concatenation( url, ".gz" ),
 Concatenation( filepath, ".gz" ), fail );
 # If the file has been stored locally then it is compressed.
 # If the contents is stored in 'result' then it is *uncompressed*.
 if result = true then
 iscompressed:= true;
 fi;
 fi;
 fi;

 if result = false then
 Info( InfoAtlasRep, 1,
 "failed to transfer file '", url, "'" );
 return false;
 fi;

 break;
 fi;
 od;
 if dirname <> info.ID then
 Error( "no data extension with identifier '", dirname, "'" );
 fi;

 if result = true then
 # The contents has just been stored in a local file.
 # For MeatAxe text files, perform postprocessing:
 # If wanted and if the file is not yet compressed then compress it.
 if compressed and
 ( iscompressed = false ) and
 type[1] in [ "perm", "matff" ] and
 UserPreference( "AtlasRep", "CompressDownloadedMeatAxeFiles" ) = true
 then
 gzip:= Filename( DirectoriesSystemPrograms(), "gzip" );
 if gzip = fail or not IsExecutableFile( gzip ) then
 Info( InfoAtlasRep, 1, "no 'gzip' executable found" );
 else
 if not IsBound( gunzip ) then
 gunzip:= Filename( DirectoriesSystemPrograms(), "gunzip" );
 if gunzip <> fail and not IsExecutableFile( gunzip ) then
 gunzip:= fail;
 fi;
 fi;
 if gunzip <> fail then
 result:= Process( DirectoryCurrent(), gzip,
 InputTextNone(), OutputTextNone(), [ filepath ] );
 if result = fail then
 Info( InfoAtlasRep, 2,
 "impossible to compress file '", filepath, "'" );
 fi;
 fi;
 fi;
 fi;
 fi;

 return result;
 end;

#############################################################################
##
#F AGR.AtlasDataGAPFormatFile2( <filename>[, "string"] )
##
## This function is used for reading a GAP format file containing
## a permutation or a matrix over a finite field.
## The assignment to a global variable is avoided by reading a modified
## version of the file.
##
AGR.AtlasDataGAPFormatFile2:= function( filename, string... )
 local str, pos, i;

 if Length( string ) = 0 then
 str:= AGR.StringFile( filename );
 else
 str:= filename;
 fi;
 pos:= PositionSublist( str, ":=" );
 if pos <> fail then
 str:= str{ [ pos + 2 .. Length( str ) ] };
 fi;
 i := InputTextString( Concatenation( "return ", str ) );
 i:= ReadAsFunction( i );
 if i <> fail then
 i:= i();
 fi;
 return i;
 end;

#############################################################################
##
#V AtlasOfGroupRepresentationsAccessFunctionsDefault
##
## several functions may be provided; return value 'fail' means that
## the next function is tried, otherwise the result counts
##
InstallValue( AtlasOfGroupRepresentationsAccessFunctionsDefault, [
 rec(
 description:= "download/read MeatAxe text files (default)",

 location:= function( files, type )
 return AGR.AccessFilesLocation( files, type, fail, true );
 end,

 fetch:= function( filepath, filename, dirname, type, crc )
 return AGR.AccessFilesFetch( filepath, filename, dirname, type, true, crc );
 end,

 contents:= function( files, type, filepaths )
 local i;

 if not ( IsExistingFile( filepaths[1] ) or
 IsExistingFile( Concatenation( filepaths[1], ".gz" ) ) ) then
 # We have the file contents.
 return type[2].InterpretDefault( filepaths );
 else
 # We have the local filenames.
 filepaths:= ShallowCopy( filepaths );
 for i in [ 1 .. Length( filepaths ) ] do
 if EndsWith( filepaths[i], ".gz" ) then
 filepaths[i]:= filepaths[i]{ [ 1 .. Length( filepaths[i] )-3 ] };
 fi;
 od;
 return type[2].ReadAndInterpretDefault( filepaths );
 fi;
 end,
 ),

 rec(
 description:= "prefer downloading/reading MeatAxe binary files",

 location:= function( files, type )
 if ( not type[1] in [ "perm", "matff" ] ) or
 IsEmpty( UserPreference( "AtlasRep", "AtlasRepDataDirectory" ) ) then
 return fail;
 fi;

 # A list of file names is given, and the files are not compressed.
 # Replace the text format names by binary format names.
 return AGR.AccessFilesLocation( files, type, [ ".m", ".b" ], false );
 end,

 fetch:= function( filepath, filename, dirname, type, crc )
 # Replace the filename by that of the binary file.
 filename:= ReplacedString( filename, ".m", ".b" );
 filename:= ReplacedString( filename, "/mtx/", "/bin/" );
 return AGR.AccessFilesFetch( filepath, filename, dirname,
 type, false, fail );
 end,

 contents:= function( files, type, filepaths )
 # This function is called only for the types "perm" and "matff",
 # binary format files are *not* compressed,
 # and we are sure that we have the filenames not file contents.
 return List( filepaths, FFMatOrPermCMtxBinary );
 end,
 ),

 # GAP format files means:
 # one generator per file,
 # the first line containing an assignment to a global variable,
 # the last character being a semicolon
 rec(
 description:= "prefer downloading/reading GAP format files",

 location:= function( files, type )
 if not type[1] in [ "perm", "matff" ] then
 return fail;
 fi;

 # A list of file names is given, and the files are not compressed.
 # Replace the text format names by GAP format names.
 return AGR.AccessFilesLocation( files, type, [ ".m", ".g" ], false );
 end,

 fetch:= function( filepath, filename, dirname, type, crc )
 # Replace the filename by that of the GAP format file.
 filename:= ReplacedString( filename, ".m", ".g" );
 filename:= ReplacedString( filename, "/mtx/", "/gap/" );
 return AGR.AccessFilesFetch( filepath, filename, dirname,
 type, false, fail );
 end,

 contents:= function( files, type, filepaths )
 # This function is called only for the types "perm" and "matff",
 # and GAP format files are *not* compressed.
 if not ( IsExistingFile( filepaths[1] ) or
 IsExistingFile( Concatenation( filepaths[1], ".gz" ) ) ) then
 # We have the file contents.
 return List( filepaths,
 str -> AGR.AtlasDataGAPFormatFile2( str, "string" ) );
 else
 # We have the local filenames.
 return List( filepaths, AGR.AtlasDataGAPFormatFile2 );
 fi;
 end,
 ),

 rec(
 # This applies only to the "core" data, not to extensions.
 description:= "prefer reading files available from a local server",

 location:= function( files, type )
 local localserverpath, names, pair, filename, info, name;

 # This is meaningful only for official data
 # and if there is a local server.
 localserverpath:= UserPreference( "AtlasRep",
 "AtlasRepLocalServerPath" );
 if localserverpath = "" then
 return fail;
 fi;

 names:= [];
 for pair in files do

 # Compose the remote filename.
 if not pair[1] in [ "datagens", "dataword" ] then
 return fail;
 fi;
 filename:= pair[2];
 info:= First( AtlasOfGroupRepresentationsInfo.filenames,
 x -> x[1] = filename );
 if info = fail then
 Error( "do not know about <filename>" );
 fi;
 filename:= info[2];

 # Check whether the file(s) exist(s).
 name:= Concatenation( localserverpath, filename );
 if IsReadableFile( name ) then
 Add( names, name );
 else
 return fail;
 fi;
 od;

 return names;
 end,

 fetch:= function( filepath, filename, dirname, type, crc )
 # The 'location' function has checked that the file exists.
 return true;
 end,

 contents:= function( files, type, filepaths )
 # We need not care about compressed files,
 # and we know that we get filenames not file contents.
 return type[2].ReadAndInterpretDefault( filepaths );
 end,
 ),
 ] );

#############################################################################
##
#F AtlasOfGroupRepresentationsLocalFilename( <files>, <type> )
##
InstallGlobalFunction( AtlasOfGroupRepresentationsLocalFilename,
 function( files, type )
 local pref, cand, r, paths;

 pref:= UserPreference( "AtlasRep", "FileAccessFunctions" );
 cand:= [];
 for r in Reversed( AtlasOfGroupRepresentationsInfo.accessFunctions ) do
 if r.description in pref then
 paths:= r.location( files, type );
 if paths <> fail then
 if ForAll( paths, IsReadableFile ) then
 # This has priority, do not consider other sources.
 cand:= [ [ r, List( paths, x -> [ x, true ] ) ] ];
 break;
 else
 Add( cand, [ r, List( paths, x -> [ x, IsReadableFile( x ) ] ) ] );
 fi;
 fi;
 fi;
 od;

 return cand;
end );

#############################################################################
##
#F AtlasOfGroupRepresentationsLocalFilenameTransfer( <files>, <type> )
##
InstallGlobalFunction( AtlasOfGroupRepresentationsLocalFilenameTransfer,
 function( files, type )
 local cand, list, ok, result, fetchfun, i, filepath, filename, info,
 dirname, crc, res;

 # 1. Determine the local directory where to look for the file,
 # and the functions that claim to be applicable.
 cand:= AtlasOfGroupRepresentationsLocalFilename( files, type );

 # 2. Check whether the files are already stored.
 # (If yes then 'cand' has length 1.)
 if Length( cand ) = 1 and ForAll( cand[1][2], x -> x[2] ) then
 # 3. We have the local files. Return paths and access functions.
 return [ List( cand[1][2], x -> x[1] ), cand[1][1] ];
 elif UserPreference( "AtlasRep", "AtlasRepAccessRemoteFiles" ) = true then
 # Try to fetch the remote files,
 # using the applicable methods.
 for list in cand do
 if Length( list[2] ) = Length( files ) then
 ok:= true;
 result:= [];
 fetchfun:= list[1].fetch;
 for i in [ 1 .. Length( files ) ] do
 if not list[2][i][2] then
 filepath:= list[2][i][1];
 filename:= files[i][2];
 info:= First( AtlasOfGroupRepresentationsInfo.filenames,
#T the list is ssorted; cheaper way!
 x -> x[1] = filename );
 if info = fail then
 Error( "do not know about <filename>" );
 fi;
 filename:= info[2];
 dirname:= files[i][1];
 if IsBound( info[4] ) then
 crc:= info[4];
 else
 crc:= fail;
 fi;
 res:= fetchfun( filepath, filename, dirname, type, crc );
 if res = false then
 ok:= false;
 fi;
 Add( result, res );
 fi;
 od;
 if ok then
 # 3. We have either the local files or their contents.
 if result[1] = true then
 # Return paths and the relevant record of access functions.
 return [ List( list[2], x -> x[1] ), list[1] ];
 else
 # Return contents and the relevant record of access functions.
 return [ result, list[1] ];
 fi;
 fi;
 fi;
 od;
 fi;

 # The file cannot be made available.
 Info( InfoAtlasRep, 1,
 "no files '", files, "' found in the local directories" );
 return fail;
end );

#############################################################################
##
#F AtlasOfGroupRepresentationsTestTableOfContentsRemoteUpdates()
##
InstallGlobalFunction(
 AtlasOfGroupRepresentationsTestTableOfContentsRemoteUpdates, function()
 local pref, version, inforec, home, result, lines,
 datadirs, line, pos, pos2, filename, localfile, servdate,
 stat;

 if not IsPackageMarkedForLoading( "io", "" ) then
 Info( InfoAtlasRep, 1, "the package IO is not available" );
 return fail;
 fi;

 # If the data directories do not yet exist then nothing is to do.
 pref:= UserPreference( "AtlasRep", "AtlasRepDataDirectory" );
 if not IsDirectoryPath( pref ) then
 return [];
 fi;

 # Download the file that lists the changes.
 version:= InstalledPackageVersion( "atlasrep" );
 inforec:= First( PackageInfo( "atlasrep" ), r -> r.Version = version );
 home:= inforec.PackageWWWHome;
 result:= AtlasOfGroupRepresentationsTransferFile(
 Concatenation( home, "/htm/data/changes.htm" ), fail, fail );
 if result <> false then
 lines:= SplitString( result, "\n" );
 result:= [];
 lines:= Filtered( lines,
 x -> 20 < Length( x ) and x{ [ 1 .. 4 ] } = "<tr>"
 and x{ [ -3 .. 0 ] + Length( x ) } = " -->" );
 if pref <> "" and not EndsWith( pref, "/" ) then
 pref:= Concatenation( pref, "/" );
 fi;
 datadirs:= [ Directory( Concatenation( pref, "datagens" ) ),
 Directory( Concatenation( pref, "dataword" ) ) ];
 for line in lines do
 pos:= PositionSublist( line, "</td><td>" );
 if pos <> fail then
 pos2:= PositionSublist( line, "</td><td>", pos );
 filename:= line{ [ pos+9 .. pos2-1 ] };
 localfile:= Filename( datadirs, filename );
 if localfile <> fail then
 if not IsReadableFile( localfile ) then
 localfile:= Concatenation( localfile, ".gz" );
 fi;
 if IsReadableFile( localfile ) then
 # There is something to compare.
 pos:= PositionSublist( line, "<!-- " );
 if pos <> fail then
 servdate:= Int( line{ [ pos+5 .. Length( line )-4 ] } );
 stat:= IO_stat( localfile );
 if stat <> fail then
 if stat.mtime < servdate then
 Add( result, localfile );
 fi;
 fi;
 fi;
 fi;
 fi;
 fi;
 od;
 return result;
 fi;

 return [];
 end );

#############################################################################
##
#F AGR.FileContents( <files>, <type> )
##
## <files> must be a list of [ <dirname>, <filename> ] pairs,
## where <dirname> is one of "dataword" or "datagens" or the ID of a
## data extension.
##
AGR.FileContents:= function( files, type )
 local result;

 if not ( IsList( files ) and
 ForAll( files, l -> IsList( l ) and Length( l ) = 2
 and ForAll( l, IsString ) ) ) then
 Error( "<files> must be a list of [ <dirname>, <filename> ] pairs" );
 fi;

 # Perhaps the method in question rearranges the distribution into
 # one or several files.
 result:= AtlasOfGroupRepresentationsLocalFilenameTransfer( files, type );
 if result = fail then
 return fail;
 else
 # We have the local files or the contents of the files.
 # Extract and process the contents.
 return result[2].contents( files, type, result[1] );
 fi;
 end;

#############################################################################
##
#F AGR.InfoForName( <gapname> )
##
AGR.InfoForName:= function( gapname )
 local pos;

 gapname:= AGR.GAPName( gapname );
 pos:= PositionSorted( AtlasOfGroupRepresentationsInfo.GAPnames,
 [ gapname ] );
 if pos <= Length( AtlasOfGroupRepresentationsInfo.GAPnames ) and
 AtlasOfGroupRepresentationsInfo.GAPnames[ pos ][1] = gapname then
 return AtlasOfGroupRepresentationsInfo.GAPnames[ pos ];
 else
 return fail;
 fi;
 end;

#############################################################################
##
## auxiliary function
##
AGR.TST:= function( gapname, value, compname, testfun, msg )
 if not IsBound( AGR.GAPnamesRec.( gapname ) ) then
 Error( "AGR.GAPnamesRec.( \"", gapname, "\" ) is not bound" );
 elif not IsBound( AGR.GAPnamesRec.( gapname )[3] ) then
 Error( "AGR.GAPnamesRec.( \"", gapname, "\" )[3] is not bound" );
 elif IsBound( AGR.GAPnamesRec.( gapname )[3].( compname ) ) then
 Error( "AGR.GAPnamesRec.( \"", gapname, "\" )[3].", compname,
 " is bound" );
 elif not testfun( value ) then
 Error( "<", compname, "> must be a ", msg );
 fi;
 end;

#############################################################################
##
#F AGR.IsRepNameAvailable( <repname> )
##
## If 'AtlasOfGroupRepresentationsInfo.checkData' is bound then this
## function is called when additional data are added that refer to the
## representation <repname>.
##
## The data files themselves are *not* read by the function,
## only the format of the filenames and the access with
## 'AllAtlasGeneratingSetInfos' are checked.
##
AGR.IsRepNameAvailable:= function( repname )
 local filenames, type, parsed, groupname, gapname;

 filenames:= [ Concatenation( repname, ".m1" ),
 Concatenation( repname, ".g" ) ];
 for type in AGR.DataTypes( "rep" ) do
 parsed:= List( filenames,
 x -> AGR.ParseFilenameFormat( x, type[2].FilenameFormat ) );
 if ForAny( parsed, IsList ) then
 break;
 fi;
 od;
 if ForAll( parsed, IsBool ) then
 Print( "#E wrong format of '", repname, "'\n" );
 return false;
 fi;
 groupname:= First( parsed, IsList )[1];
 gapname:= First( AtlasOfGroupRepresentationsInfo.GAPnames,
 pair -> pair[2] = groupname );
 if gapname = fail then
 Print( "#E no group name '", groupname, "' for '", repname, "'\n" );
 return false;
 elif ForAll( AllAtlasGeneratingSetInfos( gapname[1] ),
 x -> x.repname <> repname ) then
 Print( "#E no representation '", repname, "' available\n" );
 return false;
 fi;

 return true;
 end;

#############################################################################
##
#F AGR.IsPrgNameAvailable( <prgname> )
##
## If 'AtlasOfGroupRepresentationsInfo.checkData' is bound then this
## function is called when additional data are added that refer to the
## program <prgname>.
##
AGR.IsPrgNameAvailable:= function( prgname )
 local type, parsed, groupname;

 for type in AGR.DataTypes( "prg" ) do
 parsed:= AGR.ParseFilenameFormat( prgname, type[2].FilenameFormat );
 if IsList( parsed ) then
 break;
 fi;
 od;
 if parsed = fail then
 Print( "#E wrong format of '", prgname, "'\n" );
 return false;
 fi;
 groupname:= parsed[1];
 if ForAny( AGR.TablesOfContents( "all" ),
 toc -> IsBound( toc.( groupname ) ) and
 ForAny( RecNames( toc.( groupname ) ),
 nam -> ForAny( toc.( groupname ).( nam ),
 l -> l[ Length( l ) ] = prgname ) ) ) then
 return true;
 else
 Print( "#E no program '", prgname, "' available\n" );
 return false;
 fi;
 end;

#############################################################################
##
#V AGR.MapNameToGAPName
#F AGR.GAPName( <name> )
##
## Let <name> be a string.
## If 'LowercaseString( <name> )' is the lower case version of the GAP name
## of an ATLAS group then 'AGR.GAPName' returns this GAP name.
## If <name> is an admissible name of a GAP character table with identifier
## <id> (this condition is already case insensitive) then 'AGR.GAPName'
## returns 'AGR.GAPName( <id> )'.
##
## These two conditions are forced to be consistent, as follows.
## Whenever a GAP name <nam>, say, of an ATLAS group is notified with
## 'AGR.GNAN', we compute 'LibInfoCharacterTable( <nam> )'.
## If this is 'fail' then there is no danger of an inconsistency,
## and if the result is a record <r> then we have the condition
## 'AGR.GAPName( <r>.firstName ) = <nam>'.
##
## So a case insensitive partial mapping from character table identifiers
## to GAP names of ATLAS groups is built in 'AGR.GNAN',
## and is used in 'AGR.GAPName'
##
## Examples of different names for a group are '"F3+"' vs. '"Fi24'"'
## and '"S6"' vs. '"A6.2_1"'.
##
AGR.MapNameToGAPName:= [ [], [] ];

AGR.GAPName:= function( name )
 local r, nname, pos;

 # Make sure that the file 'gap/types.g' is already loaded.
 IsRecord( AtlasOfGroupRepresentationsInfo );

 if IsBound( AGR.LibInfoCharacterTable ) then
 r:= AGR.LibInfoCharacterTable( name );
 else
 r:= fail;
 fi;
 if r = fail then
 nname:= LowercaseString( name );
 else
 nname:= r.firstName;
 fi;
 pos:= Position( AGR.MapNameToGAPName[1], nname );
 if pos = fail then
 return name;
 fi;
 return AGR.MapNameToGAPName[2][ pos ];
 end;

#############################################################################
##
#F AGR.GAPNameAtlasName( <atlasname> )
##
## Map the Atlas name <atlasname> to the corresponding GAP name.
##
AGR.GAPNameAtlasName:= function( atlasname )
 local entry;

 entry:= First( AtlasOfGroupRepresentationsInfo.GAPnames,
 x -> x[2] = atlasname );
 if entry = fail then
 return fail;
 fi;
 return entry[1];
 end;

#############################################################################
##
#F AGR.GNAN( <gapname>, <atlasname>[, <dirid>] )
##
## <#GAPDoc Label="AGR.GNAN">
## <C>AGR.GNAN( </C><M>gapname, atlasname[, dirid]</M><C> )</C>
## <Item>
## Called with two strings <M>gapname</M> (the &GAP; name of the group)
## and <M>atlasname</M> (the &ATLAS; name of the group),
## <C>AGR.GNAN</C> stores the information in the list
## <C>AtlasOfGroupRepresentationsInfo.GAPnames</C>,
## which defines the name mapping between the &ATLAS;
## names and &GAP; names of the groups.
## 
## An example of a valid call is
## <C>AGR.GNAN("A5.2","S5")</C>.
## </Item>
## <#/GAPDoc>
##
AGR.GNAN:= function( gapname, atlasname, dirid... )
 local value, r, pos;

 # Get the arguments.
 if Length( dirid ) = 1 and IsString( dirid[1] ) then
 dirid:= dirid[1];
 elif IsBound( AGR.DIRID ) then
 dirid:= AGR.DIRID;
 else
 Info( InfoAtlasRep, 1, "'AGR.DIRID' is not bound" );
 return;
 fi;

 if IsBound( AtlasOfGroupRepresentationsInfo.checkData ) then
 if ForAny( AtlasOfGroupRepresentationsInfo.GAPnames,
 pair -> gapname = pair[1] ) then
 Error( "cannot notify '", gapname, "' more than once" );
 elif ForAny( AtlasOfGroupRepresentationsInfo.GAPnames,
 pair -> atlasname = pair[2] ) then
 Error( "ambiguous GAP names for ATLAS name '", atlasname, "'" );
 fi;
 fi;

 # Make the character table names admissible.
 if IsBound( AGR.LibInfoCharacterTable ) then
 r:= AGR.LibInfoCharacterTable( gapname );
 else
 r:= fail;
 fi;
 if r = fail then
 # Store the lowercase name.
 Add( AGR.MapNameToGAPName[1], LowercaseString( gapname ) );
 Add( AGR.MapNameToGAPName[2], gapname );
 elif not r.firstName in AGR.MapNameToGAPName[1] then
 Add( AGR.MapNameToGAPName[1], r.firstName );
 Add( AGR.MapNameToGAPName[2], gapname );
 else
 Error( "<gapname> is not compatible with CTblLib" );
 fi;

 value:= [ gapname, atlasname,
 rec(),
 rec( GNAN:= dirid ) ];
 AddSet( AtlasOfGroupRepresentationsInfo.GAPnames, value );
 AGR.GAPnamesRec.( gapname ):= value;
 end;

#############################################################################
##
#F AGR.TOC( <typename>, <filename>, <crc>[, <dirid>] )
##
## <#GAPDoc Label="AGR.TOC">
## <C>AGR.TOC( </C><M>typename, filename, crc[, dirid]</M><C> )</C>
## <Item>
## <C>AGR.TOC</C> notifies an entry to the
## <C>TableOfContents.( </C><M>dirid</M><C> )</C>
## component of <Ref Var="AtlasOfGroupRepresentationsInfo"/>.
## The string <M>typename</M> must be the name of the data type
## to which the entry belongs,
## the string <M>filename</M> must be the prefix of the data file(s), and
## <M>crc</M> must be a list that contains the checksums of the data files,
## which are either integers (see <Ref BookName="ref" Func="CrcFile"/>)
## or strings (see <C>HexSHA256</C>).
## In particular, the number of files that are described by the entry
## equals the length of <M>crc</M>.
## 
## The optional argument <M>dirid</M> is equal to the argument with the
## same name in the corresponding call of
## <Ref Func="AtlasOfGroupRepresentationsNotifyData"
## Label="for a local file describing private data"/>.
## If no <M>dirid</M> argument is given then the current value of
## <C>AGR.DIRID</C> is taken as the default;
## this value is set automatically before a <F>toc.json</F> file
## gets evaluated by
## <Ref Func="AtlasOfGroupRepresentationsNotifyData"
## Label="for a local file describing private data"/>,
## and is reset afterwards.
## If <C>AGR.DIRID</C> is not bound and <M>dirid</M> is not given then
## this function has no effect.
## 
## An example of a valid call is
## <C>AGR.TOC("perm","alt/A5/mtx/S5G1-p5B0.m", [-3581724,115937465])</C>.
## </Item>
## <#/GAPDoc>
##
AGR.TOC:= function( arg )
 local type, crc, n, string, dirid, t, record, filename, pos, entry,
 groupname, added, j, filenamex, stringx;

 # Get the arguments.
 type:= arg[1];
 crc:= arg[3];
 n:= Length( crc );
 string:= arg[2];
 if Length( arg ) = 4 and IsString( arg[4] ) then
 dirid:= arg[4];
 elif IsBound( AGR.DIRID ) then
 dirid:= AGR.DIRID;
 else
 Info( InfoAtlasRep, 1, "'AGR.DIRID' is not bound" );
 return;
 fi;

 # Parse the filename with the given format info.
 type:= First( AGR.DataTypes( "rep", "prg" ), x -> x[1] = type );
 record:= AtlasTableOfContents( dirid, "all" );

 # Split the name into path and filename.
 filename:= string;
 pos:= Position( filename, '/' );
 while pos <> fail do
 filename:= filename{ [ pos+1 .. Length( filename ) ] };
 pos:= Position( filename, '/' );
 od;

 filenamex:= filename;
 stringx:= string;
 if 1 < n then
 filenamex:= Concatenation( filename, "1" );
 stringx:= Concatenation( string, "1" );
 fi;
 entry:= AGR.ParseFilenameFormat( filenamex, type[2].FilenameFormat );
 if entry = fail then
 Info( InfoAtlasRep, 1, "'", arg, "' is not a valid t.o.c. entry" );
 return;
 fi;
 Add( AtlasOfGroupRepresentationsInfo.newfilenames,
 Immutable( [ filenamex, stringx, dirid, crc[1] ] ) );

 # Get the list for the data in the record for the group name.
 groupname:= entry[1];
 if IsBound( AtlasOfGroupRepresentationsInfo.checkData ) and
 ForAll( AtlasOfGroupRepresentationsInfo.GAPnames,
 x -> x[2] <> groupname ) then
 Error( "'", groupname, "' is not a valid group name" );
 fi;
 if not IsBound( record.( groupname ) ) then
 record.( groupname ):= rec();
 fi;
 record:= record.( groupname );
 if not IsBound( record.( type[1] ) ) then
 record.( type[1] ):= [];
 fi;

 # Add the first filename.
 added:= type[2].AddFileInfo( record.( type[1] ), entry, filenamex );

 # Add the other filenames if necessary.
 if added then
 for j in [ 2 .. n ] do
 entry[ Length( entry ) ]:= j;
 filenamex:= Concatenation( filename, String( j ) );
 stringx:= Concatenation( string, String( j ) );
 added:= type[2].AddFileInfo( record.( type[1] ), entry, filenamex )
 and added;
 Add( AtlasOfGroupRepresentationsInfo.newfilenames,
 Immutable( [ filenamex, stringx, dirid, crc[j] ] ) );
 od;
 fi;

 if not added then
 Info( InfoAtlasRep, 1, "'", arg, "' is not a valid t.o.c. entry" );
 fi;
 end;

#############################################################################
##
#F AGR.GRS( <gapname>, <size>[, <dirid>] )
##
## <#GAPDoc Label="AGR.GRS">
## <C>AGR.GRS( </C><M>gapname, size[, dirid]</M><C> )</C>
## <Item>
## The integer <M>size</M> is stored as the order of the group with
## &GAP; name <M>gapname</M>,
## in <C>AtlasOfGroupRepresentationsInfo.GAPnames</C>.
## 
## An example of a valid call is
## <C>AGR.GRS("A5.2",120)</C>.
## </Item>
## <#/GAPDoc>
##
AGR.GRS:= function( gapname, size, dirid... )

 # Get the arguments.
 if Length( dirid ) = 1 and IsString( dirid[1] ) then
 dirid:= dirid[1];
 elif IsBound( AGR.DIRID ) then
 dirid:= AGR.DIRID;
 else
 Info( InfoAtlasRep, 1, "'AGR.DIRID' is not bound" );
 return;
 fi;

 if IsBound( AtlasOfGroupRepresentationsInfo.checkData ) then
 AGR.TST( gapname, size, "size", IsPosInt, "positive integer" );
 fi;
 AGR.GAPnamesRec.( gapname )[3].size:= size;
 AGR.GAPnamesRec.( gapname )[4].GRS:= dirid;
 end;

#############################################################################
##
#F AGR.MXN( <gapname>, <nrMaxes>[, <dirid>] )
##
## <#GAPDoc Label="AGR.MXN">
## <C>AGR.MXN( </C><M>gapname, nrMaxes[, dirid]</M><C> )</C>
## <Item>
## The integer <M>nrMaxes</M> is stored as the number of classes of
## maximal subgroups of the group with &GAP; name <M>gapname</M>,
## in <C>AtlasOfGroupRepresentationsInfo.GAPnames</C>.
## 
## An example of a valid call is
## <C>AGR.MXN("A5.2",4)</C>.
## </Item>
## <#/GAPDoc>
##
AGR.MXN:= function( gapname, nrMaxes, dirid... )

 # Get the arguments.
 if Length( dirid ) = 1 and IsString( dirid[1] ) then
 dirid:= dirid[1];
 elif IsBound( AGR.DIRID ) then
 dirid:= AGR.DIRID;
 else
 Info( InfoAtlasRep, 1, "'AGR.DIRID' is not bound" );
 return;
 fi;

 if IsBound( AtlasOfGroupRepresentationsInfo.checkData ) then
 AGR.TST( gapname, nrMaxes, "nrMaxes", IsPosInt, "positive integer" );
 fi;
 AGR.GAPnamesRec.( gapname )[3].nrMaxes:= nrMaxes;
 AGR.GAPnamesRec.( gapname )[4].MXN:= dirid;
 end;

#############################################################################
##
#F AGR.MXO( <gapname>, <sizesMaxes>[, <dirid>] )
##
## <#GAPDoc Label="AGR.MXO">
## <C>AGR.MXO( </C><M>gapname, sizesMaxes[, dirid]</M><C> )</C>
## <Item>
## The list <M>sizesMaxes</M> of subgroup orders of the classes of
## maximal subgroups of the group with &GAP; name <M>gapname</M>
## (not necessarily dense, in non-increasing order) is stored
## in <C>AtlasOfGroupRepresentationsInfo.GAPnames</C>.
## 
## An example of a valid call is
## <C>AGR.MXO("A5.2",[60,24,20,12])</C>.
## </Item>
## <#/GAPDoc>
##
AGR.MXO:= function( gapname, sizesMaxes, dirid... )
 local i;

 # Get the arguments.
 if Length( dirid ) = 1 and IsString( dirid[1] ) then
 dirid:= dirid[1];
 elif IsBound( AGR.DIRID ) then
 dirid:= AGR.DIRID;
 else
 Info( InfoAtlasRep, 1, "'AGR.DIRID' is not bound" );
 return;
 fi;

 # Entries of the form '0' mean unknown values.
 for i in [ 1 .. Length( sizesMaxes ) ] do
 if IsBound( sizesMaxes[i] ) and sizesMaxes[i] = 0 then
 Unbind( sizesMaxes[i] );
 fi;
 od;

 if IsBound( AtlasOfGroupRepresentationsInfo.checkData ) then
 AGR.TST( gapname, sizesMaxes, "sizesMaxes",
 x -> IsList( x ) and ForAll( x, IsPosInt )
 and IsSortedList( Reversed( Compacted( x ) ) ),
 "list of non-increasing pos. integers" );
 fi;
 AGR.GAPnamesRec.( gapname )[3].sizesMaxes:= sizesMaxes;
 AGR.GAPnamesRec.( gapname )[4].MXO:= dirid;
 end;

#############################################################################
##
#F AGR.MXS( <gapname>, <structureMaxes>[, <dirid>] )
##
## <#GAPDoc Label="AGR.MXS">
## <C>AGR.MXS( </C><M>gapname, structureMaxes[, dirid]</M><C> )</C>
## <Item>
## The list <M>structureMaxes</M> of strings describing the
## structures of the maximal subgroups of the group with &GAP; name
## <M>gapname</M> (not necessarily dense), is stored
## in <C>AtlasOfGroupRepresentationsInfo.GAPnames</C>.
## 
## An example of a valid call is
## <C>AGR.MXS("A5.2",["A5","S4","5:4","S3x2"])</C>.
## </Item>
## <#/GAPDoc>
##
AGR.MXS:= function( gapname, structureMaxes, dirid... )
 local i;

 # Get the arguments.
 if Length( dirid ) = 1 and IsString( dirid[1] ) then
 dirid:= dirid[1];
 elif IsBound( AGR.DIRID ) then
 dirid:= AGR.DIRID;
 else
 Info( InfoAtlasRep, 1, "'AGR.DIRID' is not bound" );
 return;
 fi;

 # Entries of the form '""' mean unknown values.
 for i in [ 1 .. Length( structureMaxes ) ] do
 if IsBound( structureMaxes[i] ) and structureMaxes[i] = "" then
 Unbind( structureMaxes[i] );
 fi;
 od;

 if IsBound( AtlasOfGroupRepresentationsInfo.checkData ) then
 AGR.TST( gapname, structureMaxes, "structureMaxes",
 x -> IsList( x ) and ForAll( x, IsString ),
 "list of strings" );
 fi;
 AGR.GAPnamesRec.( gapname )[3].structureMaxes:= structureMaxes;
 AGR.GAPnamesRec.( gapname )[4].MXS:= dirid;
 end;

#############################################################################
##
#F AGR.STDCOMP( <gapname>, <factorCompatibility>[, <dirid>] )
##
## <#GAPDoc Label="AGR.STDCOMP">
## <C>AGR.STDCOMP( </C><M>gapname, factorCompatibility[, dirid]</M><C> )</C>
## <Item>
## The list <M>factorCompatibility</M> (with entries
## the standardization of the group with &GAP; name <M>gapname</M> ,
## the &GAP; name of a factor group,
## the standardization of this factor group, and
## <K>true</K> or <K>false</K>, indicating whether mapping the standard
## generators for <M>gapname</M> to those of <M>factgapname</M> defines an
## epimorphism) is stored
## in <C>AtlasOfGroupRepresentationsInfo.GAPnames</C>.
## 
## An example of a valid call is
## <C>AGR.STDCOMP("2.A5.2",[1,"A5.2",1,true])</C>.
## </Item>
## <#/GAPDoc>
##
AGR.STDCOMP:= function( gapname, factorCompatibility, dirid... )

 # Get the arguments.
 if Length( dirid ) = 1 and IsString( dirid[1] ) then
 dirid:= dirid[1];
 elif IsBound( AGR.DIRID ) then
 dirid:= AGR.DIRID;
 else
 Info( InfoAtlasRep, 1, "'AGR.DIRID' is not bound" );
 return;
 fi;

 if IsBound( AtlasOfGroupRepresentationsInfo.checkData ) and
 not ( IsList( factorCompatibility ) and
 Length( factorCompatibility ) = 4 and
 IsPosInt( factorCompatibility[1] ) and
 IsString( factorCompatibility[2] ) and
 IsPosInt( factorCompatibility[3] ) and
 IsBool( factorCompatibility[4] ) ) then
 Error( "<factorCompatibility> must be a suitable list" );
 fi;
 if not IsBound( AGR.GAPnamesRec.( gapname )[3].factorCompatibility ) then
 AGR.GAPnamesRec.( gapname )[3].factorCompatibility:= [];
 fi;
 Add( AGR.GAPnamesRec.( gapname )[3].factorCompatibility,
 Concatenation( factorCompatibility, [ dirid ] ) );
 end;

#############################################################################
##
#F AGR.RNG( <repname>, <descr>[, <dirid>] )
##
## <#GAPDoc Label="AGR.RNG">
## <C>AGR.RNG( </C><M>repname, descr[, dirid]</M><C> )</C>
## <Item>
## Called with two strings <M>repname</M> (denoting the name
## of a file containing the generators of a matrix representation over a
## ring that is not determined by the filename)
## and <M>descr</M> (describing this ring <M>R</M>, say),
## <C>AGR.RNG</C> adds the triple
## <M>[ repname, descr, R ]</M>
## to the list stored in the <C>ringinfo</C> component of
## <Ref Var="AtlasOfGroupRepresentationsInfo"/>.
## 
## An example of a valid call is
## <C>AGR.RNG("A5G1-Ar3aB0","Field([Sqrt(5)])")</C>.
## </Item>
## <#/GAPDoc>
##
AGR.RNG:= function( repname, descr, args... )
 local len, dirid, data;

 # Get the arguments.
 len:= Length( args );
 if len in [ 1, 3 ] and IsString( args[ len ] ) then
 dirid:= args[ len ];
 args:= args{ [ 1 .. len-1 ] };
 elif IsBound( AGR.DIRID ) then
 dirid:= AGR.DIRID;
 else
 Info( InfoAtlasRep, 1, "'AGR.DIRID' is not bound" );
 return;
 fi;

 if IsBound( AtlasOfGroupRepresentationsInfo.checkData ) then
 # Check that this representation really exists.
 if not AGR.IsRepNameAvailable( repname ) then
 return;
 fi;
 fi;

 data:= [ repname, descr, EvalString( descr ) ];
 Append( data, args );
 Add( data, dirid );

 if ForAny( AtlasOfGroupRepresentationsInfo.ringinfo,
 entry -> repname = entry[1] ) then
 Info( InfoAtlasRep, 1,
 "data '", data, "' cannot be notified more than once" );
 else
 Add( AtlasOfGroupRepresentationsInfo.ringinfo, data );
 fi;
 end;

#############################################################################
##
#F AGR.TOCEXT( <atlasname>, <std>, <maxnr>, <files>[, <dirid>] )
##
## <#GAPDoc Label="AGR.TOCEXT">
## <C>AGR.TOCEXT( </C><M>atlasname, std, maxnr, files[, dirid]</M><C> )</C>
## <Item>
## Called with <M>atlasname</M>,
## the positive integers <M>std</M> (the standardization) and
## <M>maxnr</M> (the number of the class of maximal subgroups), and
## the list <M>files</M> (of filenames of straight line programs for
## computing generators of the <M>maxnr</M>-th maximal subgroup, using
## a straight line program for a factor group plus perhaps some straight
## line program for computing kernel generators),
## <C>AGR.TOCEXT</C> stores the information in
## <C>AtlasOfGroupRepresentationsInfo.GAPnames</C>.
## 
## An example of a valid call is
## <C>AGR.TOCEXT("2A5",1,3,["A5G1-max3W1"])</C>.
## </Item>
## <#/GAPDoc>
##
AGR.TOCEXT:= function( groupname, std, maxnr, files, dirid... )
 local info;

 # Get the arguments.
 if Length( dirid ) = 1 and IsString( dirid[1] ) then
 dirid:= dirid[1];
 elif IsBound( AGR.DIRID ) then
 dirid:= AGR.DIRID;
 else
 Info( InfoAtlasRep, 1, "'AGR.DIRID' is not bound" );
 return;
 fi;

 if IsBound( AtlasOfGroupRepresentationsInfo.checkData ) then
 if not ( IsString( groupname ) and IsPosInt( std )
 and IsPosInt( maxnr )
 and IsList( files )
 and ForAll( files, IsString ) ) then
 Error( "not a valid t.o.c.ext entry" );
 elif ForAll( AtlasOfGroupRepresentationsInfo.GAPnames,
 x -> x[2] <> groupname ) then
 Error( "'", groupname, "' is not a valid group name" );
 fi;

 # Check that the required programs really exist.
 # (We cannot check the availability of the required program for
 # computing kernel generators, since these programs will be notified
 # *after* the current call, in another directory.)
 if not AGR.IsPrgNameAvailable( files[1] ) then
 # The program for the max. subgroup of the factor is not available.
 Print( "#E factor program required by '", groupname, "' and '",
 files, "' not available\n" );
 return;
 fi;
 fi;

 info:= First( AtlasOfGroupRepresentationsInfo.GAPnames,
 x -> x[2] = groupname );
 if not IsBound( info[3].maxext ) then
 info[3].maxext:= [];
 fi;
 Add( info[3].maxext, [ std, maxnr, files, dirid ] );
 end;

#############################################################################
##
#F AGR.API( <repname>, <info>[, <dirid>] )
##
## <#GAPDoc Label="AGR.API">
## <C>AGR.API( </C><M>repname, info[, dirid]</M><C> )</C>
## <Item>
## Called with the string <M>repname</M> (denoting the name of a
## permutation representation)
## and the list <M>info</M> (describing the point stabilizer of this
## representation),
## <C>AGR.API</C> binds the component <M>repname</M> of the record
## <C>AtlasOfGroupRepresentationsInfo.permrepinfo</C> to a record that
## describes the contents of <M>info</M>.
## 
## <M>info</M> has the following entries.
## <List>
## <Item>
## At position <M>1</M>, the transitivity is stored.
## </Item>
## <Item>
## If the transitivity is zero then <M>info</M> has length two,
## and the second entry is the list of orbit lengths.
## </Item>
## <Item>
## If the transitivity is positive then <M>info</M> has length
## four or five, and the second entry is the rank of the action.
## </Item>
## <Item>
## If the transitivity is positive then the third entry is one of the
## strings <C>"prim"</C>, <C>"imprim"</C>, denoting primitivity or not.
## </Item>
## <Item>
## If the transitivity is positive then the fourth entry is either
## the string <C>"???"</C> or a string that describes the structure of
## the point stabilizer.
## If the third entry is <C>"imprim"</C> then this description consists
## of a subgroup part and a maximal subgroup part, separated by
## <C>" < "</C>.
## </Item>
## <Item>
## If the third entry is <C>"prim"</C> then the fifth entry is either
## the string <C>"???"</C>
## or the number of the class of maximal subgroups
## that are the point stabilizers.
## </Item>
## </List>
## 
## An example of a valid call is
## <C>AGR.API("A5G1-p5B0",[3,2,"prim","A4",1])</C>.
## </Item>
## <#/GAPDoc>
##
AGR.API:= function( repname, info, dirid... )
 local r;

 # Get the arguments.
 if Length( dirid ) = 1 and IsString( dirid[1] ) then
 dirid:= dirid[1];
 elif IsBound( AGR.DIRID ) then
 dirid:= AGR.DIRID;
 else
 Info( InfoAtlasRep, 1, "'AGR.DIRID' is not bound" );
 return;
 fi;

 if IsBound( AtlasOfGroupRepresentationsInfo.checkData ) then
 if IsBound( AtlasOfGroupRepresentationsInfo.permrepinfo.( repname ) ) then
 Error( "cannot notify '", repname, "' more than once" );
 fi;

 # Check that this representation really exists.
 if not AGR.IsRepNameAvailable( repname ) then
 return;
 fi;
 fi;

 # The component 'dirid' is used in 'StringOfAtlasTableOfContents'.
 r:= rec( transitivity:= info[1], dirid:= dirid );
 if info[1] = 0 then
 r.orbits:= info[2];
 r.isPrimitive:= false;
 else
 r.rankAction:= info[2];
 r.isPrimitive:= ( info[3] = "prim" );
 r.stabilizer:= info[4];
 if r.isPrimitive then
 r.maxnr:= info[5];
 fi;
 fi;

 AtlasOfGroupRepresentationsInfo.permrepinfo.( repname ):= r;
 end;

#############################################################################
##
#F AGR.CHAR( <gapname>, <repname>, <char>, <pos>[, <charname>][, <dirid>] )
##
## <#GAPDoc Label="AGR.CHAR">
## <C>AGR.CHAR( </C><M>gapname, repname, char, pos[, charname[, dirid]]</M><C> )</C>
## <Item>
## Called with the strings <M>gapname</M>
## and <M>repname</M> (denoting the name of the representation),
## the integer <M>char</M> (the characteristic of the representation),
## and <M>pos</M> (the position or list of positions of the irreducible
## constituent(s)),
## <C>AGR.CHAR</C> stores the information in
## <C>AtlasOfGroupRepresentationsInfo.characterinfo</C>.
## 
## A string describing the character can be entered as <M>charname</M>.
## 
## If <M>dirid</M> is given but no <M>charname</M> is known then one can
## enter <K>fail</K> as the fifth argument.
## 
## An example of a valid call is
## <C>AGR.CHAR("M11","M11G1-p11B0",0,[1,2],"1a+10a")</C>.
## </Item>
## <#/GAPDoc>
##
AGR.CHAR:= function( groupname, repname, char, pos, arg... )
 local charname, dirid, map;

 # Get the arguments.
 if Length( arg ) >= 1 then
 charname:= arg[1];
 else
 charname:= fail;
 fi;
 if Length( arg ) = 2 then
 dirid:= arg[2];
 elif IsBound( AGR.DIRID ) then
 dirid:= AGR.DIRID;
 else
 Info( InfoAtlasRep, 1, "'AGR.DIRID' is not bound" );
 return;
 fi;

 map:= AtlasOfGroupRepresentationsInfo.characterinfo;
 if not IsBound( map.( groupname ) ) then
 map.( groupname ):= [];
 fi;
 map:= map.( groupname );
 if char = 0 then
 char:= 1;
 fi;
 if not IsBound( map[ char ] ) then
 map[ char ]:= [ [], [], [], [] ];
 fi;
 map:= map[ char ];

 if IsBound( AtlasOfGroupRepresentationsInfo.checkData ) then
 # Check whether we have already a character for this representation.
 # (Two different representations with the same character are allowed.)
 if arg[2] in map[2] and map[1][ Position( map[2], repname ) ] <> pos then
 Error( "attempt to enter two different characters for ", arg[2] );
 fi;

 # Check that this representation really exists.
 if not AGR.IsRepNameAvailable( repname ) then
 return;
 fi;
 fi;

 Add( map[1], pos );
 Add( map[2], repname );
 Add( map[3], charname );
 Add( map[4], dirid );

 # The character information forms one global object.
 # It may belong to any t.o.c., and we would not consider the new entry
 # if the cached t.o.c. would be taken.
 AtlasOfGroupRepresentationsInfo.TOC_Cache:= rec();
 AtlasOfGroupRepresentationsInfo.TableOfContents.merged:= rec();
 end;

#############################################################################
##
#F AGR.CompareAsNumbersAndNonnumbers( <nam1>, <nam2> )
##
## This function is available as 'BrowseData.CompareAsNumbersAndNonnumbers'
## if the Browse package is available.
## But we must deal also with the case that this package is not available.
##
AGR.CompareAsNumbersAndNonnumbers:= function( nam1, nam2 )
 local len1, len2, len, digit, comparenumber, i;

 len1:= Length( nam1 );
 len2:= Length( nam2 );
 len:= len1;
 if len2 < len then
 len:= len2;
 fi;
 digit:= false;
 comparenumber:= 0;
 for i in [ 1 .. len ] do
 if nam1[i] in DIGITS then
 if nam2[i] in DIGITS then
 digit:= true;
 if comparenumber = 0 then
 # first digit of a number, or previous digits were equal
 if nam1[i] < nam2[i] then
 comparenumber:= 1;
 elif nam1[i] <> nam2[i] then
 comparenumber:= -1;
 fi;
 fi;
 else
 # if digit then the current number in 'nam2' is shorter,
 # so 'nam2' is smaller;
 # if not digit then a number starts in 'nam1' but not in 'nam2',
 # so 'nam1' is smaller
 return not digit;
 fi;
 elif nam2[i] in DIGITS then
 # if digit then the current number in 'nam1' is shorter,
 # so 'nam1' is smaller;
 # if not digit then a number starts in 'nam2' but not in 'nam1',
 # so 'nam2' is smaller
 return digit;
 else
 # both characters are non-digits
 if digit then
 # first evaluate the current numbers (which have the same length)
 if comparenumber = 1 then
 # nam1 is smaller
 return true;
 elif comparenumber = -1 then
 # nam2 is smaller
 return false;
 fi;
 digit:= false;
 fi;
 # now compare the non-digits
 if nam1[i] <> nam2[i] then
 return nam1[i] < nam2[i];
 fi;
 fi;
 od;

 if digit then
 # The suffix of the shorter string is a number.
 # If the longer string continues with a digit then it is larger,
 # otherwise the first digits of the number decide.
 if len < len1 and nam1[ len+1 ] in DIGITS then
 # nam2 is smaller
 return false;
 elif len < len2 and nam2[ len+1 ] in DIGITS then
 # nam1 is smaller
 return true;
 elif comparenumber = 1 then
 # nam1 is smaller
 return true;
 elif comparenumber = -1 then
 # nam2 is smaller
 return false;
 fi;
 fi;

 # Now the longer string is larger.
 return len1 < len2;
 end;

#############################################################################
##
#F AGR.SetGAPnamesSortDisp()
##
## Bind the component 'AtlasOfGroupRepresentationsInfo.GAPnamesSortDisp'.
##
AGR.SetGAPnamesSortDisp:= function()
 local list;

 list:= ShallowCopy( AtlasOfGroupRepresentationsInfo.GAPnames );
 SortParallel( List( list, x -> x[1] ), list,
 AGR.CompareAsNumbersAndNonnumbers );
 AtlasOfGroupRepresentationsInfo.GAPnamesSortDisp:= list;
 end;

#############################################################################
##
#F AGR.ParseFilenameFormat( <string>, <format> )
##
AGR.ParseFilenameFormat:= function( string, format )
 local result, i, res;

 string:= SplitString( string, "-" );
 if Length( string ) <> Length( format[1] ) then
 return fail;
 fi;
 result:= [];
 for i in [ 1 .. Length( string ) ] do

 # Loop over the '-' separated components.
 res:= format[2][i]( string[i], format[1][i] );
 if res = fail then
 return fail;
 fi;
 Append( result, res );

 od;
 return result;
 end;

#############################################################################
##
#F AtlasDataGAPFormatFile( <filename>[, "string"] )
##
## <ManSection>
## <Func Name="AtlasDataGAPFormatFile" Arg='filename[, "string"]'/>
##
## <Description>
## Let <A>filename</A> be the name of a file containing the generators of a
## representation in characteristic zero such that reading the file via
## <Ref Func="ReadAsFunction" BookName="ref"</C> yields a record
## containing the list of the generators and additional information.
## Then <Ref Func="AtlasDataGAPFormatFile"/> returns this record.
## </Description>
## </ManSection>
##
BindGlobal( "AtlasDataGAPFormatFile", function( filename, string... )
 local fun;

 AGR.InfoRead( "#I reading '", filename, "' started\n" );
 if Length( string ) = 0 then
 fun:= ReadAsFunction( filename );
 else
 fun:= ReadAsFunction( InputTextString( filename ) );
 fi;
 AGR.InfoRead( "#I reading '", filename, "' done\n" );
 if fun = fail then
 Info( InfoAtlasRep, 1,
 "problem reading '", filename, "' as function\n" );
 else
 fun:= fun();
 fi;
 return fun;
end );

#############################################################################
##
#F AtlasDataJsonFormatFile( <filename>[, "string"] )
##
## Evaluate the contents of a Json format file that describes matrices
## in characteristic zero.
##
## Admit a prescribed ring for the matrix entries,
## given by the 'givenRing' component of the info record stored in the
## global option 'inforecord'.
##
BindGlobal( "AtlasDataJsonFormatFile", function( filename, string... )
 local obj, arec, givenF, info, F, pol, facts, gen, roots, ecoeffs, pos,
 found, N, B, nrows, ncols, mats, d, mat, i, j;

 if Length( string ) = 0 then
 obj:= AGR.GapObjectOfJsonText( StringFile( filename ) );
 else
 obj:= AGR.GapObjectOfJsonText( filename );
 fi;
 if obj.status = false then
 if Length( string ) = 0 then
 Info( InfoAtlasRep, 1,
 "file ", filename, " does not contain valid Json" );
 else
 Info( InfoAtlasRep, 1,
 "string <filename> does not contain valid Json" );
 fi;
 return fail;
 fi;
 arec:= obj.value;

 givenF:= ValueOption( "inforecord" );
 if givenF <> fail then
 if IsBound( givenF.givenRing ) then
 givenF:= givenF.givenRing;
 else
 givenF:= fail;
 fi;
 fi;

 info:= arec.ringinfo;

 if givenF = fail or IsCyclotomicCollection( givenF ) then
 # Create the default field extension in GAP.
 if Length( info ) = 1 and info[1] = "IntegerRing" then
 F:= Integers;
 gen:= 1;
 elif Length( info ) = 2 and info[1] = "QuadraticField" then
 F:= Field( Rationals, [ Sqrt( info[2] ) ] );
 pol:= UnivariatePolynomial( F, arec.polynomial );
 gen:= - Value( Factors( PolynomialRing( F ), pol )[1], 0 );
 elif Length( info ) = 2 and info[1] = "CyclotomicField" then
 F:= CyclotomicField( Rationals, info[2] );
 gen:= E( info[2] );
 elif Length( info ) = 2 and info[1] = "AbelianNumberField" then
 # Choose the unique root of the polynomial
 # that involves E(N) with the correct sign.
 # (This is of course a hack, but it makes the generators in GAP
 # backwards compatible with the old Magma and GAP format files.)
 F:= CyclotomicField( Rationals, info[2] );
 pol:= UnivariatePolynomial( F, arec.polynomial );
 roots:= List( Factors( PolynomialRing( F ), pol ),
 x -> - Value( x, 0 ) );
 ecoeffs:= COEFFS_CYC( E( info[2] ) );
 pos:= PositionNonZero( ecoeffs );
 gen:= First( roots, x -> COEFFS_CYC( x )[ pos ] = ecoeffs[ pos ] );
 F:= Field( Rationals, [ gen ] );
 elif Length( info ) = 1 and info[1] = "NumberField" then
 # We have no good idea to guess the conductor.
 found:= false;
 pol:= UnivariatePolynomial( Rationals, arec.polynomial );
 for N in [ 3 .. 100 ] do
 F:= CyclotomicField( Rationals, N );
 facts:= Factors( PolynomialRing( F ), pol );
 if Length( facts ) = Degree( pol ) then
 roots:= List( facts, x -> - Value( x, 0 ) );
 ecoeffs:= COEFFS_CYC( E( info[2] ) );
 pos:= PositionNonZero( ecoeffs );
 gen:= First( roots, x -> COEFFS_CYC( x )[ pos ] = ecoeffs[ pos ] );
 F:= Field( Rationals, [ gen ] );
 found:= true;
 break;
 fi;
 od;
 if not found then
 Error( "did not find conductor" );
 fi;
 else
 Error( "invalid 'ringinfo'" );
 fi;
 else
 # Take a root of the given defining polynomial
 # over the given field extension as the primitive element.
 F:= givenF;
 if Length( arec.polynomial ) = 2 then
 # no proper extension, usually 'Integers'
 gen:= One( F );
 else
 pol:= UnivariatePolynomial( F, arec.polynomial * One( F ) );
 facts:= Filtered( Factors( PolynomialRing( F ), pol ),
 x -> Degree( x ) = 1 );
 if Length( facts ) = 0 then
 Error( "the polynomial <pol> has no root in <F>" );
 fi;
 gen:= - Value( facts[1], 0 );
 fi;
 fi;

 B:= List( [ 0 .. Length( arec.polynomial )-2 ], i -> gen^i );

 nrows:= arec.dimensions[1];
 ncols:= arec.dimensions[2];

 mats:= [];
 d:= arec.denominator;
 for mat in arec.generators do
 pos:= 0;
 for i in [ 1 .. nrows ] do
 for j in [ 1 .. ncols ] do
 pos:= pos + 1;
 if IsList( mat[ pos ] ) then
 mat[ pos ]:= mat[ pos ] * B;
 fi;
 od;
 od;
 if givenF <> fail then
 mat:= mat * One( givenF );
 fi;
 if d <> 1 then
 mat:= mat / d;
 fi;
#T eventually support 'Matrix( F, mat, ncols )'
#T and given ConstructingFilter!
 Add( mats, List( [ 1 .. nrows ],
 i -> mat{ [ (i-1)*ncols+1 .. i*ncols ] } ) );
 od;

 return rec( generators:= mats );
end );

#############################################################################
##
#F AtlasStringOfFieldOfMatrixEntries( <mats> )
#F AtlasStringOfFieldOfMatrixEntries( <filename> )
##
InstallGlobalFunction( AtlasStringOfFieldOfMatrixEntries, function( mats )
 local F, n, str;

 if IsString( mats ) then
 mats:= AtlasDataGAPFormatFile( mats ).generators;
 fi;

 if IsCyclotomicCollCollColl( mats ) then
 F:= Field( Rationals, Flat( mats ) );
 elif ForAll( mats, IsQuaternionCollColl ) then
 F:= Field( Flat( List( Flat( mats ), ExtRepOfObj ) ) );
 else
 Error( "<mats> must be a matrix list of cyclotomics or quaternions" );
 fi;

 n:= Conductor( F );

 if DegreeOverPrimeField( F ) = 2 then

 # The field is quadratic,
 # so it is generated by 'Sqrt(n)' if $'n' \equiv 1 \pmod{4}$,
 # by 'Sqrt(-n)' if $'n' \equiv 3 \pmod{4}$,
 # and by one of 'Sqrt(n/4)', 'Sqrt(-n/4)' otherwise.
 if n mod 4 = 1 then
 str:= Concatenation( "[Sqrt(", String( n ), ")]" );
 elif n mod 4 = 3 then
 str:= Concatenation( "[Sqrt(-", String( n ), ")]" );
 elif Sqrt( -n/4 ) in F then
 str:= Concatenation( "[Sqrt(-", String( n/4 ), ")]" );
 else
 str:= Concatenation( "[Sqrt(", String( n/4 ), ")]" );
 fi;

 elif IsCyclotomicField( F ) then

 # The field is not quadratic but cyclotomic.
 str:= Concatenation( "[E(", String( n ), ")]" );

 else
 str:= "";
 fi;

 if IsCyclotomicCollCollColl( mats ) then
 if str = "" then
 str:= String( F );
 else
 str:= Concatenation( "Field(", str, ")" );
 fi;
 elif F = Rationals then
 str:= "QuaternionAlgebra(Rationals)";
 elif str = "" then
 str:= Concatenation( "QuaternionAlgebra(", String( F ), ")" );
 else
 str:= Concatenation( "QuaternionAlgebra(", str, ")" );
 fi;

 return [ F, str ];
end );

#############################################################################
##
#F AtlasOfGroupRepresentationsScanFilename( <name>, <result>, <dirid> )
##
BindGlobal( "AtlasOfGroupRepresentationsScanFilename",
 function( name, result, dirid )
 local filename, pos, type, format, groupname;

 # Replace the name of binary files by the corresponding MeatAxe filename.
 pos:= PositionSublist( name, ".b" );
 if pos <> fail then
 name:= ReplacedString( name, ".b", ".m" );
 fi;

 # Split the name into path and filename.
 filename:= name;
 pos:= Position( filename, '/' );
 while pos <> fail do
 filename:= filename{ [ pos+1 .. Length( filename ) ] };
 pos:= Position( filename, '/' );
 od;

 for type in AGR.DataTypes( "rep", "prg" ) do
 format:= AGR.ParseFilenameFormat( filename, type[2].FilenameFormat );
 if format <> fail then
 groupname:= format[1];
 if not IsBound( result.( groupname ) ) then
 result.( groupname ):= rec();
 fi;
 if not IsBound( result.( groupname ).( type[1] ) ) then
 result.( groupname ).( type[1] ):= [];
 fi;
 if type[2].AddFileInfo( result.( groupname ).( type[1] ),
 format, filename ) then
 Add( AtlasOfGroupRepresentationsInfo.newfilenames,
 Immutable( [ filename, name, dirid ] ) );
 return true;
 else
 return false;
 fi;
 fi;
 od;

 # No type matches.
 return false;
end );

#############################################################################
##
#F AtlasOfGroupRepresentationsComposeTableOfContents( <filelist>,
#F <gapnames>, <dirid> )
##
## This code is used by 'AtlasTableOfContents'.
##
BindGlobal( "AtlasOfGroupRepresentationsComposeTableOfContents",
 function( filelist, gapnames, dirid )
 local result, name, len, groupname, record, type, listtosort;

 # Initialize the result record.
 result:= rec( otherfiles:= [] );

 # Deal with the case of 'gzip'ped files, and omit obvious garbage.
 for name in Set( filelist ) do
 len:= Length( name );
 if 3 <= len and name{ [ len-2 .. len ] } = ".gz" then
 name:= name{ [ 1 .. len-3 ] };
 fi;
 if AtlasOfGroupRepresentationsScanFilename( name, result, dirid )
 = false then
 if not ( name in [ "dummy", ".", "..", ".svn", "toc.g", "toc.json",
 ".svnignore" ] or
 name[ Length( name ) ] = '%' or
 ( 3 <= Length( name )
 and name{ Length( name ) + [ - 2 .. 0 ] } = "BAK" ) ) then
 Info( InfoAtlasRep, 3,
 "t.o.c. construction: ignoring name '", name, "'" );
 AddSet( result.otherfiles, name );
 fi;
 fi;
 od;

 # Postprocessing,
 # and *sort* the representations as given in the type definition.
 for groupname in List( gapnames, x -> x[2] ) do
 if IsBound( result.( groupname ) ) then

 record:= result.( groupname );
 for type in AGR.DataTypes( "rep", "prg" ) do
 if IsBound( record.( type[1] ) ) then

 type[2].PostprocessFileInfo( result, record );

 # Sort the data of the given type as defined.
 if IsBound( type[2].SortTOCEntries ) then
 listtosort:= List( record.( type[1] ), type[2].SortTOCEntries );
 SortParallel( listtosort, record.( type[1] ) );
 fi;

 fi;
 od;

 fi;
 od;

 # Store the current date in Coordinated Universal Time
 # (Greenwich Mean Time).
 result.lastupdated:= CurrentDateTimeString();

 return result;
end );

#############################################################################
##
#F AtlasTableOfContents( <tocid>, <allorlocal>[, <body>] )
##
InstallGlobalFunction( AtlasTableOfContents,
 function( tocid, allorlocal, body... )
 local toc, id, groupnames, prefix, filenames, dirinfo, dstdir, dstfile,
 tocremote, typeinfo, groupname, r, pair, type, entry, fileinfo,
 filename, loc, dirname, privdir, f, comp, dir, result;

 # Take the stored version if it is already available.
 toc:= AtlasOfGroupRepresentationsInfo.TableOfContents;
 id:= Concatenation( tocid, "|", allorlocal );
 if IsBound( toc.( id ) ) then
 return toc.( id );
 fi;

 if not allorlocal in [ "all", "local" ] then
 Error( "<allorlocal> must be \"all\" or \"local\"" );
 fi;

 groupnames:= AtlasOfGroupRepresentationsInfo.GAPnames;
 prefix:= "";
 filenames:= [];

 # Fetch the information that was set during the notification.
 dirinfo:= First( AtlasOfGroupRepresentationsInfo.notified,
 entry -> entry.ID = tocid );
 if dirinfo = fail then
 return fail;
 fi;

 if allorlocal = "all" then

 if IsBound( dirinfo.data ) then
 # This is a remote part of the database.
 # The contents are described by the record stored as the third entry.
 # (We need also the 'AGR.TOC' calls.)
 toc.( id ):= rec();
 AGR.DIRID:= tocid;
 for entry in dirinfo.data.Data do
 CallFuncList( AGR.( entry[1] ), entry[2] );
 od;
 Unbind( AGR.DIRID );
 toc.( id ).TocID:= tocid;
 return toc.( id );
 else
 # This is a local part of the database,
 # there may be a 'toc.json' file (evaluate it if available)
 # or 'body' contains its contents.
 if Length( body ) = 1 then
 body:= body[1];
 elif IsExistingFile( dirinfo.DataURL ) then
 privdir:= Directory( dirinfo.DataURL );
 filename:= Filename( privdir, "toc.json" );
 if not IsReadableFile( filename ) = true then
 return fail;
 fi;
 body:= AGR.StringFile( filename );
 else
 return fail;
 fi;

 # Store the hint for calls of 'AGR.API', 'AGR.CHR', 'AGR.TOC'.
 f:= AGR.GapObjectOfJsonText( body );
 if f.status = false then
 Error( "file <filename> does not contain valid JSON" );
 fi;
 f:= f.value;
 for comp in [ "Version", "SelfURL", "DataURL", "LocalDirectory" ] do
 if IsBound( f.( comp ) ) then
 dirinfo.( comp ):= f.( comp );
 fi;
 od;
 dirname:= dirinfo.DataURL;
 toc.( id ):= rec();
 AGR.DIRID:= tocid;
 if IsBound( f.DataURL ) then
 # Notify all files, not just the locally available ones.
 for entry in f.Data do
 CallFuncList( AGR.( entry[1] ), entry[2] );
 od;
 dirinfo.data:= f;
 Unbind( AGR.DIRID );
 toc.( id ).TocID:= tocid;
 return toc.( id );
 else
 # This is *only* locally available.
 # Rely on the locally available files.
 for entry in f.Data do
 # Omit 'AGR.TOC' lines that may be present.
 # Note that we are going to list the local directory contents.
 if entry[1] <> "TOC" then
 CallFuncList( AGR.( entry[1] ), entry[2] );
 fi;
 od;
 Unbind( AGR.DIRID );
 fi;

 if IsExistingFile( dirname ) then
 # List the information available in the given local directory.
 # (Up to one directory layer above the data files is supported.)
 for dir in Difference( DirectoryContents( dirname ),
 [ ".", "..", ".svn" ] ) do
 dstfile:= Filename( privdir, dir );
 if IsDirectoryPath( dstfile ) then
 Append( filenames,
 List( Difference( DirectoryContents( dstfile ),
 [ ".", "..", ".svn" ] ),
 x -> Concatenation( dir, "/", x ) ) );
 else
 Add( filenames, dir );
 fi;
 od;

 # Compose the result record.
 result:= AtlasOfGroupRepresentationsComposeTableOfContents( filenames,
 groupnames, tocid );
 result.TocID:= tocid;

 # Store the newly computed table of contents.
 toc.( id ):= result;
 return result;

 fi;
 fi;

 else
 # First create the "all" variant, then filter it.
 tocremote:= AtlasTableOfContents( tocid, "all" );
 if tocid = "core" then
 typeinfo:= Concatenation(
 List( AGR.DataTypes( "rep" ), x -> [ "datagens", x ] ),
 List( AGR.DataTypes( "prg" ), x -> [ "dataword", x ] ) );
 else
 typeinfo:= List( AGR.DataTypes( "rep", "prg" ), x -> [ tocid, x ] );
 fi;

 for groupname in RecNames( tocremote ) do
 r:= tocremote.( groupname );
 if IsRecord( r ) then
 for pair in typeinfo do
 type:= pair[2];
 if IsBound( r.( type[1] ) ) then
 for entry in r.( type[1] ) do
 fileinfo:= entry[ Length( entry ) ];
 if IsString( fileinfo ) then
 fileinfo:= [ fileinfo ];
 fi;
 loc:= AtlasOfGroupRepresentationsLocalFilename(
 List( fileinfo, x -> [ pair[1], x ] ), type );
 if not IsEmpty( loc ) and ForAll( loc[1][2], x -> x[2] ) then
 Append( filenames, fileinfo );
 fi;
 od;
 fi;
 od;
 fi;
 od;

 # Compose the result record.
 result:= AtlasOfGroupRepresentationsComposeTableOfContents( filenames,
 groupnames, tocid );

 result.TocID:= tocid;

 # Store the newly computed table of contents.
 toc.( id ):= result;

 # Return the result record.
 return result;
 fi;

 return fail;
end );

#############################################################################
##
#F StringOfAtlasTableOfContents( <inforec> )
##
InstallGlobalFunction( StringOfAtlasTableOfContents, function( inforec )
 local dirid, remote, prefix, open, close, toc, data, entry, name, val,
 entry2, reps, type, nam, r, line, map, i, j, list, comp, str,
 parskip;

 if IsString( inforec ) then
 r:= First( AtlasOfGroupRepresentationsInfo.notified,
 x -> x.ID = inforec );
 if r = fail then
 Error( "if the argument is a string then it must be \"core\" ",
 "or the ID of a data extension" );
 elif IsBound( r.data ) then
 r:= r.data;
 fi;
 inforec:= rec( ID:= inforec );
 if IsBound( r.DataURL ) and StartsWith( r.DataURL, "http" ) then
 inforec.DataURL:= r.DataURL;
 fi;
 for comp in [ "Version", "SelfURL", "LocalDirectory" ] do
 if IsBound( r.( comp ) ) then
 inforec.( comp ):= r.( comp );
 fi;
 od;
 fi;

 if not IsRecord( inforec ) then
 Error( "<inforec> must be an ID string or a record" );
 elif not IsBound( inforec.ID ) then
 Error( "<inforec>.ID must be bound" );
 fi;

 dirid:= inforec.ID;
 if ForAll( AtlasOfGroupRepresentationsInfo.notified,
 x -> x.ID <> dirid ) then
 Error( "<inforec>.ID must be \"core\" ",
 "or the ID of a data extension" );
 fi;

 remote:= IsBound( inforec.DataURL ) and
 StartsWith( inforec.DataURL, "http" );

 prefix:= "[\"";
 open:= "\",[";
 close:= "]]";

 toc:= AGR.TablesOfContents( dirid )[1];

 data:= rec( GNAN:= [],
 GRS:= [],
 MXN:= [],
 MXO:= [],
 MXS:= [],
 TOC:= [],
 STDCOMP:= [],
 RNG:= [],
 TOCEXT:= [],
 API:= [],
 CHAR:= [],
 );

 # Collect the available information for this group.
 for entry in AtlasOfGroupRepresentationsInfo.GAPnames do

 if entry[4].GNAN = dirid then
 Add( data.GNAN, [ entry[1], Concatenation( "\"", entry[2], "\"" ) ] );
 fi;
 if IsBound( entry[4].GRS ) and entry[4].GRS = dirid then
 Add( data.GRS, [ entry[1], String( entry[3].size ) ] );
 fi;
 if IsBound( entry[4].MXN ) and entry[4].MXN = dirid then
 Add( data.MXN, [ entry[1], String( entry[3].nrMaxes ) ] );
 fi;
 if IsBound( entry[4].MXO ) and entry[4].MXO = dirid then
 # For the JSON format, replace each hole in the list by '0'.
 val:= ReplacedString( String( entry[3].sizesMaxes ), " ", "" );
 val:= ReplacedString( val, ",,", ",0," );
 val:= ReplacedString( val, ",,", ",0," );
 val:= ReplacedString( val, "[,", "[0," );
 Add( data.MXO, [ entry[1], val ] );
 fi;
 if IsBound( entry[4].MXS ) and entry[4].MXS = dirid then
 # For the JSON format, replace each hole in the list by '""'.
 val:= ReplacedString( String( entry[3].structureMaxes ), " ", "" );
 val:= ReplacedString( val, ",,", ",\"\"," );
 val:= ReplacedString( val, ",,", ",\"\"," );
 val:= ReplacedString( val, "[,", "[\"\"," );
 Add( data.MXS, [ entry[1], val ] );
 fi;
 if IsBound( entry[3].factorCompatibility ) then
 for entry2 in entry[3].factorCompatibility do
 if entry2[5] = dirid then
 Add( data.STDCOMP, [ entry[1],
 ReplacedString( String( entry2{ [ 1 .. 4 ] } ), " ", "" ) ] );
 fi;
 od;
 fi;
 if IsBound( entry[3].maxext ) then
 for entry2 in entry[3].maxext do
 if entry2[4] = dirid then
 Add( data.TOCEXT, [ entry[2],
 Concatenation(
 String( entry2[1] ), ",", String( entry2[2] ), ",",
 ReplacedString( String( entry2[3] ), " ", "" ) ) ] );
 fi;
 od;
 fi;

 if remote and IsBound( toc.( entry[2] ) ) then
 # Collect the representations and straight line programs.
 reps:= toc.( entry[2] );
 for type in AGR.DataTypes( "rep", "prg" ) do
 if IsBound( reps.( type[1] ) ) then
 for entry in reps.( type[1] ) do
 if IsBound( type[2].TOCEntryString ) then
 val:= type[2].TOCEntryString( type[1], entry );
 if val = fail then
 Info( InfoAtlasRep, 1,
 "'TOCEntryString' for data type '", type[1], "'",
 " returns 'fail'" );
 else
 Add( data.TOC, type[2].TOCEntryString( type[1], entry ) );
 fi;
 else
 Info( InfoAtlasRep, 1,
 "no component 'TOCEntryString' for data type '",
 type[1], "'" );
 fi;
 od;
 fi;
 od;
 fi;

 od;

 for entry in AtlasOfGroupRepresentationsInfo.ringinfo do
 if entry[ Length( entry ) ] = dirid then
 if Length( entry ) = 4 then
 Add( data.RNG, [ entry[1], Concatenation( "\"", entry[2], "\"" ) ] );
 else
 # The length is 6.
 Add( data.RNG, [ entry[1], Concatenation( "\"", entry[2], "\"" ),
 entry[4], entry[5] ] );
 fi;
 fi;
 od;

 for nam in RecNames( AtlasOfGroupRepresentationsInfo.permrepinfo ) do
 r:= AtlasOfGroupRepresentationsInfo.permrepinfo.( nam );
 if r.dirid = dirid then
 line:= "[";
 Append( line, String( r.transitivity ) );
 Append( line, "," );
 if r.transitivity = 0 then
 Append( line, ReplacedString( String( r.orbits ), " ", "" ) );
 else
 Append( line, String( r.rankAction ) );
 Append( line, "," );
 if r.isPrimitive then
 Append( line, "\"prim\"" );
 else
 Append( line, "\"imprim\"" );
 fi;
 Append( line, ",\"" );
 Append( line, r.stabilizer );
 Append( line, "\"" );
 if r.isPrimitive then
 Append( line, "," );
 if IsInt( r.maxnr ) then
 Append( line, String( r.maxnr ) );
 else
 Append( line, "\"" );
 Append( line, String( r.maxnr ) );
 Append( line, "\"" );
 fi;
 fi;
 fi;
 Append( line, "]" );

 Add( data.API, [ nam, line ] );
 fi;
 od;

 for nam in RecNames( AtlasOfGroupRepresentationsInfo.characterinfo ) do
 map:= AtlasOfGroupRepresentationsInfo.characterinfo.( nam );
 for i in [ 1 .. Length( map ) ] do
 if IsBound( map[i] ) then
 for j in [ 1 .. Length( map[i][1] ) ] do
 if map[i][4][j] = dirid then
 # This information belongs to the current t.o.c.
 line:= Concatenation( "\"", map[i][2][j], "\"," );
 if i = 1 then
 Append( line, "0" );
 else
 Append( line, String( i ) );
 fi;
 Append( line, "," );
 Append( line,
 ReplacedString( String( map[i][1][j] ), " ", "" ) );
 if map[i][3][j] <> fail then
 Append( line, ",\"" );
 Append( line, map[i][3][j] );
 Append( line, "\"" );
 fi;
 Add( data.CHAR, [ nam, line ] );
 fi;
 od;
 fi;
 od;
 od;

 list:= [];
 for comp in [ "GNAN", "GRS", "MXN", "MXO", "MXS" ] do
 parskip:= "\n";
 Sort( data.( comp ) );
 for entry in data.( comp ) do
 Add( list, Concatenation( parskip, prefix, comp, open,
 "\"", entry[1], "\",", entry[2], close ) );
 parskip:= "";
 od;
 od;

 # Sort the TOC entries by filename and type.
 SortParallel( List( data.TOC,
 x -> SplitString( x, "\"" ){ [ 4, 2 ] } ), data.TOC );
 parskip:= "\n";
 for entry in data.TOC do
 Add( list, Concatenation( parskip, prefix, "TOC", open, entry, close ) );
 parskip:= "";
 od;

 for comp in [ "STDCOMP", "RNG", "TOCEXT", "API", "CHAR" ] do
 parskip:= "\n";
 Sort( data.( comp ) );
 for entry in data.( comp ) do
 if Length( entry ) = 2 then
 Add( list, Concatenation( parskip, prefix, comp, open,
 "\"", entry[1], "\",", entry[2], close ) );
 else
 Add( list, Concatenation( parskip, prefix, comp, open,
 "\"", entry[1], "\",", entry[2], ",",
 ReplacedString( String( entry[3] ), " ", "" ), ",",
 ReplacedString( String( entry[4] ), " ", "" ),
 close ) );
 fi;
 parskip:= "";
 od;
 od;

 str:= "{\n";
 Append( str, "\"ID\":\"" );
 Append( str, dirid );
 Append( str, "\",\n" );
 for comp in [ "Version", "DataURL", "SelfURL", "LocalDirectory" ] do
 if IsBound( inforec.( comp ) ) then
 Append( str, "\"" );
 Append( str, comp );
 Append( str, "\":\"" );
 Append( str, inforec.( comp ) );
 Append( str, "\",\n" );
 fi;
 od;
 Append( str, "\"Data\":[" );
 Append( str, JoinStringsWithSeparator( list, ",\n" ) );
 Append( str, "\n]\n}\n" );

 return str;
end );

#############################################################################
##
#F AGR.TablesOfContents( <descr> )
##
## Admissible arguments are
## 1 the string "all",
## 2 the string "local",
## 3 a string describing a table of contents
## which occurs as the 'ID' component of an entry in
## 'AtlasOfGroupRepresentationsInfo.notified', or
## 4 a list of conditions such as [ <std>, "contents", <...> ]
## 5 a list of strings as 1-3.
##
AGR.TablesOfContents:= function( descr )
 local pos, tocid, allorlocal, label, tocs, entry;

 if descr = [] then
 descr:= [ "all" ];
 elif IsString( descr ) then
 descr:= [ descr ];
 elif not IsList( descr ) then
 Error( "<descr> must be a string or a list of strings/conditions" );
 fi;

 pos:= Position( descr, "contents" );
 if pos <> fail then
 # 'descr' is a list of conditions.
 # Evaluate only its "contents" part,
 # i. e., restrict the tables of contents, and remove this condition.
 # (Do not make a shallow copy!)
 tocid:= descr[ pos+1 ];
 Remove( descr, pos );
 Remove( descr, pos );
 if IsString( tocid ) then
 descr:= [ tocid ];
 else
 descr:= tocid;
 fi;
 elif ForAny( descr,
 x -> x <> "all" and x <> "local"
 and ForAll( AtlasOfGroupRepresentationsInfo.notified,
 entry -> x <> entry.ID ) ) then
 # 'descr' is a list of conditions that do not restrict the
 # table of contents.
 descr:= [ "all" ];
 fi;
 pos:= Position( descr, "local" );
 if pos <> fail then
 allorlocal:= "local";
 Remove( descr, pos );
 if descr = [] then
 descr:= [ "all" ];
 fi;
 else
 allorlocal:= "all";
 fi;

 # Now 'descr' is a list of identifiers of tables of contents.
 label:= JoinStringsWithSeparator(
 SortedList( Concatenation( [ allorlocal ], descr ) ), "|" );
 if not IsBound( AtlasOfGroupRepresentationsInfo.TOC_Cache.( label ) ) then
 tocs:= [];
 for entry in AtlasOfGroupRepresentationsInfo.notified do
 if "all" in descr or entry.ID in descr then
 Add( tocs, AtlasTableOfContents( entry.ID, allorlocal ) );
 fi;
 od;
 AtlasOfGroupRepresentationsInfo.TOC_Cache.( label ):= tocs;
 fi;
 return AtlasOfGroupRepresentationsInfo.TOC_Cache.( label );
end;

#############################################################################
##
#F AGR.CreateLocalJSONFile( <dirid>, <body> )
##
## Return either 'fail' or the path of the newly created file.
##
AGR.CreateLocalJSONFile:= function( dirid, body )
 local pref, datadir, filename;

 pref:= UserPreference( "AtlasRep", "AtlasRepDataDirectory" );
 if pref = "" then
 # We cannot (or do not want to) store local files.
 return fail;
 elif pref <> "" and not EndsWith( pref, "/" ) then
 pref:= Concatenation( pref, "/" );
 fi;
 datadir:= Concatenation( pref, "dataext/", dirid );
 if not IsDirectoryPath( datadir ) then
 # Create the subdirectory 'dirid' and set the mode 1023.
 # (Note that 'mkdir' does not guarantee the required mode,
 # so we call 'chmod' afterwards.)
 if not IsPackageMarkedForLoading( "IO", "" ) or
 IO_mkdir( datadir, 1023 ) <> true then
 Info( InfoAtlasRep, 1,
 "AtlasOfGroupRepresentationsNotifyData:\n",
 "#I 'IO_mkdir' cannot create the local directory\n",
 "#I ", datadir );
 return fail;
 elif IO_chmod( datadir, 1023 ) <> true then
 Info( InfoAtlasRep, 1,
 "AtlasOfGroupRepresentationsNotifyData:\n",
 "#I 'IO_chmod' cannot set the mode of \n",
 "#I ", datadir, " to 1023" );
 return fail;
 fi;
 fi;

 filename:= Filename( Directory( datadir ), "toc.json" );
 if IsReadableFile( filename ) then
 # A perhaps outdated version of the file is stored;
 # we did not know this in advance because 'dirid' was not given.
 # Compare the current version with the available one,
 # and update the local version if necessary.
 if AGR.StringFile( filename ) <> body then
 if FileString( filename, body ) = fail then
 Info( InfoAtlasRep, 1,
 "AtlasOfGroupRepresentationsNotifyData:\n",
 "#I could not replace file\n",
 "#I '", filename, "'" );
 return fail;
 else
 Info( InfoAtlasRep, 1,
 "AtlasOfGroupRepresentationsNotifyData:\n",
 "#I replaced file\n",
 "#I '", filename, "'" );
 fi;
 fi;
 elif FileString( filename, body ) = fail then
 Info( InfoAtlasRep, 1,
 "AtlasOfGroupRepresentationsNotifyData:\n",
 "#I could not write local file\n",
 "#I '", filename, "'" );
 return fail;
 else
 Info( InfoAtlasRep, 1,
 "AtlasOfGroupRepresentationsNotifyData:\n",
 "#I wrote new file\n",
 "#I '", filename, "'" );
 fi;

 return filename;
end;

#############################################################################
##
#F AtlasOfGroupRepresentationsNotifyData( <dir>, <id>[, <test>] )
#F AtlasOfGroupRepresentationsNotifyData( <filename>[, <id>][, <test>] )
#F AtlasOfGroupRepresentationsNotifyData( <url>[, <id>][, <test>] )
#F AtlasOfGroupRepresentationsNotifyData( <filecontents>[, <id>][, <test>] )
##
InstallGlobalFunction( AtlasOfGroupRepresentationsNotifyData,
 function( arg )
 local usage, test, dir, filename, url, firstarg, dirname, dirid, body, f,
 known, r, comp, localdir, pos, package, path, localdirs, pref,
 datadirs, p, datadir, oldtest, olddata, nam, entry,
 toc, allfilenames, RemovedDirectories, groupname, record, type,
 name, tocs, ok, oldtoc, list, i, names, unknown, value;

 # Get and check the arguments.
 usage:= Concatenation(
 "usage:\n",
 "AtlasOfGroupRepresentationsNotifyData( <dir>, <id>[, <test>] ),\n",
 "AtlasOfGroupRepresentationsNotifyData( <filename>[, <id>][, <test>] ),\n",
 "AtlasOfGroupRepresentationsNotifyData( <url>[, <id>][, <test>] ),\n",
 "AtlasOfGroupRepresentationsNotifyData( <filecontents>[, <id>][, <test>] )" );

 test:= false;
 if Length( arg ) = 0 then
 Error( usage );
 elif IsBool( arg[ Length( arg ) ] ) then
 test:= ( arg[ Length( arg ) ] = true );
 Remove( arg );
 if Length( arg ) = 0 then
 Error( usage );
 fi;
 fi;

 dir:= fail;
 filename:= fail;
 url:= fail;
 body:= fail;
 firstarg:= arg[1];
 if IsDirectory( firstarg ) then
 # first form, with directory
 dir:= firstarg;
 dirname:= ShallowCopy( dir![1] );
 elif IsString( firstarg ) then
 if StartsWith( firstarg, "~" ) then
 firstarg:= UserHomeExpand( firstarg );
 fi;
 if IsDirectoryPath( firstarg ) then
 # first form, with directory path
 dirname:= ShallowCopy( firstarg );
 dir:= Directory( dirname );
 elif IsReadableFile( firstarg ) then
 # second form
 filename:= firstarg;
 elif not StartsWith( firstarg, "{" ) then
 # third form
 url:= firstarg;
 else
 # fourth form
 body:= firstarg;
 fi;
 else
 Error( usage );
 fi;

 if Length( arg ) = 2 and IsString( arg[2] ) then
 dirid:= arg[2];
 if dirid = "local" then
 # "local" is reserved to restrict overviews.
 Error( "<dirid> must not be the string \"local\"" );
 elif ( dir <> fail or filename <> fail ) and
 ForAny( AtlasOfGroupRepresentationsInfo.notified,
 entry -> entry.ID = dirid and
 not StartsWith( entry.DataURL, "http" ) ) then
 # We have already notified this extension,
 # and it is a local one, thus we can ignore this notification.
 # (If we know the extension just as a remote one,
 # we can try to upgrade it to a local one.)
 return true;
 fi;
 elif Length( arg ) <> 1 then
 Error( usage );
 fi;

 if dir <> fail then

 # This is the first form:
 # A local directory contains some data files.

 if IsEmpty( dirname ) then
 Error( "<dirname> must not be empty" );
 elif dirname[ Length( dirname ) ] <> '/' then
 Add( dirname, '/' );
 fi;
 Add( AtlasOfGroupRepresentationsInfo.notified,
 rec( ID:= dirid, DataURL:= dirname ) );

 elif filename <> fail then

 # This is the second form:
 # A local JSON format file describes remote and/or local data.
 body:= AGR.StringFile( filename );
 if body = fail then
 Info( InfoAtlasRep, 1,
 "AtlasOfGroupRepresentationsNotifyData:\n",
 "#I cannot read '", filename, "'" );
 return false;
 fi;
 f:= AGR.GapObjectOfJsonText( body );
 if f.status = false then
 Error( "file <filename> does not contain valid JSON" );
 fi;
 f:= f.value;
 if IsBound( dirid ) and dirid <> f.ID then
 Error( "'", dirid, "' differs from ID in file: '", filename, "'" );
 fi;
 dirid:= f.ID;
 known:= First( AtlasOfGroupRepresentationsInfo.notified,
 entry -> entry.ID = dirid );
 if known <> fail then
 if known.ID = dirid and not StartsWith( known.DataURL, "http" ) then
 # We have already notified this extension as a local one.
 return true;
 elif dirid = "core" then
 return true;
 fi;
 fi;

 # The extension is either new or has been notified as a remote one
 # which may later be upgraded to a local one.
 if dirid = "core" then
 r:= rec( ID:= dirid, data:= f );
 for comp in [ "Version", "DataURL", "SelfURL", "LocalDirectory" ] do
 if IsBound( f.( comp ) ) then
 r.( comp ):= f.( comp );
 fi;
 od;
 Add( AtlasOfGroupRepresentationsInfo.notified, r );
 AtlasTableOfContents( dirid, "all" );
 return true;
 elif IsBound( f.LocalDirectory ) then
 # If the local directory is available then delegate to the first form.
 # The filename is interpreted relative to GAP's 'pkg' directory,
 # so we assume that the relevant package is already loaded.
 localdir:= f.LocalDirectory;
 pos:= Position( f.LocalDirectory, '/' );
 if pos = fail then
 Error( "local directory ", f.LocalDirectory,
 " does not have the form <pkgname>/<path>" );
 fi;
 package:= f.LocalDirectory{ [ 1 .. pos-1 ] };
 if IsPackageMarkedForLoading( package, "" ) then
 path:= f.LocalDirectory{ [ pos+1 .. Length ( f.LocalDirectory ) ] };
 localdirs:= DirectoriesPackageLibrary( package, path );
 if not IsEmpty( localdirs ) and IsDirectory( localdirs[1] ) then
 # Do not delegate to the first form
 # because we need the components of 'f'.
 Info( InfoAtlasRep, 2,
 "AtlasOfGroupRepresentationsNotifyData:\n",
 "#I use the local directory instead of the remote one ",
 "for '", dirid, "'" );
 if known <> fail then
 # Remove the remote notification before we can upgrade to local.
 Info( InfoAtlasRep, 2,
 "AtlasOfGroupRepresentationsNotifyData:\n",
 "#I first remove the remote notification" );
 AtlasOfGroupRepresentationsForgetData( dirid );
 fi;
 r:= rec( ID:= dirid, DataURL:= ShallowCopy( localdirs[1]![1] ) );
 fi;
 fi;
 fi;

 if not IsBound( r ) then
 # If we arrive here then 'LocalDirectory' cannot be used.
 # Create a copy of the JSON file in the local data directory
 # if possible.
 AGR.CreateLocalJSONFile( dirid, body );
 r:= rec( ID:= dirid, DataURL:= f.DataURL );
 fi;
 r.data:= f;
 for comp in [ "Version", "SelfURL", "LocalDirectory" ] do
 if IsBound( f.( comp ) ) then
 r.( comp ):= f.( comp );
 fi;
 od;
 Add( AtlasOfGroupRepresentationsInfo.notified, r );

 elif url <> fail then

 # This is the third form:
 # We know a URL where a JSON format file can be found
 # that describes remote and/or local data.
 # - If 'dirid' is given and we have already a local copy of this file
 # then we delegate to the second form.
 # - Otherwise, if we are in online mode and can download this file
 # then do this and then delegate to the fourth form.
 # - Otherwise we give up.

 pref:= UserPreference( "AtlasRep", "AtlasRepDataDirectory" );
 if pref <> "" and not EndsWith( pref, "/" ) then
 pref:= Concatenation( pref, "/" );
 fi;
 datadirs:= Directory( Concatenation( pref, "dataext" ) );
 if IsBound( dirid ) then
 datadirs:= Filename( datadirs, dirid );
 if IsReadableFile( datadirs ) and IsDirectoryPath( datadirs ) then
 filename:= Filename( Directory( datadirs ), "toc.json" );
 if IsReadableFile( filename ) then
 Info( InfoAtlasRep, 1,
 "AtlasOfGroupRepresentationsNotifyData:\n",
 "#I use the locally available '", dirid, "/toc.json'\n",
 "#I instead of '", url, "'" );
 return AtlasOfGroupRepresentationsNotifyData(
 filename, dirid, test );
 fi;
 fi;
 fi;

 if UserPreference( "AtlasRep", "AtlasRepAccessRemoteFiles" ) = true then
 # Try to fetch the file.
 body:= AtlasOfGroupRepresentationsTransferFile( url, fail, fail );
 if body = false then
 Info( InfoAtlasRep, 1,
 "AtlasOfGroupRepresentationsNotifyData:\n",
 "#I cannot read '", url, "'" );
 return false;
 fi;

 f:= AGR.GapObjectOfJsonText( body );
 if f.status = false then
 Error( "file does not contain valid JSON: ", url );
 fi;
 f:= f.value;
 if not IsBound( f.ID ) then
 Error( "file does not contain ID: ", url );
 elif IsBound( dirid ) and dirid <> f.ID then
 Error( "'", dirid, "' differs from ID in file: ", url );
 elif not IsBound( f.DataURL ) then
 Error( "file does not contain DataURL: ", url );
 fi;
 dirid:= f.ID;
 if ForAny( AtlasOfGroupRepresentationsInfo.notified,
 entry -> entry.ID = dirid and
 not StartsWith( entry.DataURL, "http" ) ) then
 # We have already notified this extension as a local one.
 return true;
 fi;

 # Store a local copy of the file if it is not yet available
 # and if we are allowed/able to write local files;
 # it can then be used next time in offline mode.
 # If necessary then create a subdirectory in 'dataext'.
 filename:= AGR.CreateLocalJSONFile( dirid, body );

 # Delegate to the fourth form.
 return AtlasOfGroupRepresentationsNotifyData( body, dirid, test );

 elif IsBound( dirid ) then
 Info( InfoAtlasRep, 2,
 "AtlasOfGroupRepresentationsNotifyData:\n",
 "#I cannot notify new data extension in offline mode,\n",
 "#I local directory '", dirid, "'\n",
 "#I is not available" );
 else
 Info( InfoAtlasRep, 2,
 "AtlasOfGroupRepresentationsNotifyData:\n",
 "#I cannot notify new data extension via\n",
 "#I '", url, "'\n",
 "#I in offline mode" );
 fi;

 # Give up.
 return false;

 fi;

 # Now we are in the first, second, or fourth form.
 # It remains to evaluate the JSON file.
 # The file may contain calls of 'AGR.GNAN' (which must come *before* the
 # data for the groups in question can be notified) and of 'AGR.API' and
 # 'AGR.CHAR' (which must come *afterwards*).
 # So we must postpone the calls of 'AGR.IsRepNameAvailable'.
 # If the private files are not stored locally then the file must contain
 # also the relevant 'AGR.TOC' calls.
 oldtest:= IsBound( AtlasOfGroupRepresentationsInfo.checkData );
 Unbind( AtlasOfGroupRepresentationsInfo.checkData );
 olddata:= rec(
 permrepinfo:= RecNames( AtlasOfGroupRepresentationsInfo.permrepinfo ),
 charrepinfo:= [],
 );
 for nam in RecNames( AtlasOfGroupRepresentationsInfo.characterinfo ) do
 for entry in AtlasOfGroupRepresentationsInfo.characterinfo.( nam ) do
 Append( olddata.charrepinfo, entry[2] );
 od;
 od;

 # Set up the table of contents for the extension.
 # The following call does the work.
 if body <> fail then
 if ForAll( AtlasOfGroupRepresentationsInfo.notified,
 r -> r.ID <> dirid ) then
 # 'AtlasTableOfContents' sets the necessary components.
 Add( AtlasOfGroupRepresentationsInfo.notified, rec( ID:= dirid ) );
 fi;
 toc:= AtlasTableOfContents( dirid, "all", body );
 else
 toc:= AtlasTableOfContents( dirid, "all" );
 fi;

 # In test mode, make the ignored filenames visible.
 if test and IsBound( toc.otherfiles )
 and not IsEmpty( toc.otherfiles ) then
 Print( "#I AtlasOfGroupRepresentationsNotifyData:\n",
 "#I ignored files in ", dirname, ":\n",
 "#I ", toc.otherfiles, "\n" );
 fi;
 Unbind( toc.otherfiles );

 # Check that no filename of this table of contents exists already in
 # another table of contents.
 Sort( AtlasOfGroupRepresentationsInfo.filenames );
 ok:= true;
 for entry in AtlasOfGroupRepresentationsInfo.newfilenames do
 pos:= PositionSorted( AtlasOfGroupRepresentationsInfo.filenames,
 [ entry[1] ] );
 if pos <= Length( AtlasOfGroupRepresentationsInfo.filenames )
 and AtlasOfGroupRepresentationsInfo.filenames[ pos ][1] = entry[1] then
 Info( InfoAtlasRep, 1,
 "file '", entry[1], "' was already in another t.o.c." );
 ok:= false;
 fi;
 od;

 if not ok then
 AtlasOfGroupRepresentationsForgetData( dirid );
 return false;
 fi;

 Append( AtlasOfGroupRepresentationsInfo.filenames,
 AtlasOfGroupRepresentationsInfo.newfilenames );
 AtlasOfGroupRepresentationsInfo.newfilenames:= [];
 Sort( AtlasOfGroupRepresentationsInfo.filenames );

 # Add group names that were not notified.
 unknown:= Set( Filtered( RecNames( toc ),
 x -> ForAll( AtlasOfGroupRepresentationsInfo.GAPnames,
 pair -> x <> pair[2] ) ) );
 RemoveSet( unknown, "TocID" );
 RemoveSet( unknown, "lastupdated" );
 if not IsEmpty( unknown ) then
 ok:= false;
 Info( InfoAtlasRep, 1,
 "no GAP names defined for ", unknown );
 for name in unknown do
 value:= [ name, name, rec() ];
 AddSet( AtlasOfGroupRepresentationsInfo.GAPnames, value );
 AGR.GAPnamesRec.( name ):= value;
 od;
 fi;

 # Clear the caches.
 AGR.SetGAPnamesSortDisp();
 AtlasOfGroupRepresentationsInfo.TOC_Cache:= rec();
 AtlasOfGroupRepresentationsInfo.TableOfContents.merged:= rec();

 # Run the postponed tests.
 if test then
 AtlasOfGroupRepresentationsInfo.checkData:= true;
 olddata.repinfo:= Difference(
 RecNames( AtlasOfGroupRepresentationsInfo.permrepinfo ),
 olddata.permrepinfo );
 olddata.charrepinfonew:= [];
 for nam in RecNames( AtlasOfGroupRepresentationsInfo.characterinfo ) do
 for entry in AtlasOfGroupRepresentationsInfo.characterinfo.( nam ) do
 Append( olddata.charrepinfonew, entry[2] );
 od;
 od;
 UniteSet( olddata.repinfo, Difference( olddata.charrepinfonew,
 olddata.charrepinfo ) );
 for nam in olddata.repinfo do
 ok:= AGR.IsRepNameAvailable( nam ) and ok;
 od;
 fi;

 # Restore the original flag.
 if not oldtest then
 Unbind( AtlasOfGroupRepresentationsInfo.checkData );
 fi;

 # Return the flag.
 return ok;
 end );

#############################################################################
##
#F AtlasOfGroupRepresentationsForgetData( <dirid> )
##
InstallGlobalFunction( AtlasOfGroupRepresentationsForgetData,
 function( dirid )
 local GAPnames, notified, i, j, entry, gapname, pos, list, info;

 GAPnames:= AtlasOfGroupRepresentationsInfo.GAPnames;
 notified:= AtlasOfGroupRepresentationsInfo.notified;

 for i in [ 1 .. Length( notified ) ] do
 if notified[i].ID = dirid then

 # Remove the group related information that belongs to 'dirid'.
 for j in [ 1 .. Length( GAPnames ) ] do
 entry:= GAPnames[j];
 if entry[4].GNAN = dirid then
 gapname:= entry[1];
 pos:= Position( AGR.MapNameToGAPName[2], gapname );
 if pos <> fail then
 Remove( AGR.MapNameToGAPName[1], pos );
 Remove( AGR.MapNameToGAPName[2], pos );
 fi;
 Unbind( GAPnames[j] );
 # This throws away information which was perhaps added
 # in another extension.
 Unbind( AGR.GAPnamesRec.( gapname ) );
 fi;
 if IsBound( entry[4].GRS ) and entry[4].GRS = dirid then
 Unbind( entry[4].GRS );
 Unbind( entry[3].size );
 fi;
 if IsBound( entry[4].MXN ) and entry[4].MXN = dirid then
 Unbind( entry[4].MXN );
 Unbind( entry[3].nrMaxes );
 fi;
 if IsBound( entry[4].MXO ) and entry[4].MXO = dirid then
 Unbind( entry[4].MXO );
 Unbind( entry[3].sizesMaxes );
 fi;
 if IsBound( entry[4].MXS ) and entry[4].MXS = dirid then
 Unbind( entry[4].MXS );
 Unbind( entry[3].structureMaxes );
 fi;
 od;
 AtlasOfGroupRepresentationsInfo.GAPnames:= Compacted( GAPnames );

 # Remove information about representations.
 AtlasOfGroupRepresentationsInfo.ringinfo:= Filtered(
 AtlasOfGroupRepresentationsInfo.ringinfo,
 x -> x[ Length(x) ] <> dirid );
 for gapname in RecNames(
 AtlasOfGroupRepresentationsInfo.characterinfo ) do
 for list in AtlasOfGroupRepresentationsInfo.characterinfo.(
 gapname ) do
 for pos in Reversed( Positions( list[4], dirid ) ) do
 for j in [ 1 .. 4 ] do
 Remove( list[j], pos );
 od;
 od;
 od;
 od;
 info:= AtlasOfGroupRepresentationsInfo.permrepinfo;
 for entry in RecNames( info ) do
 if info.( entry ).dirid = dirid then
 Unbind( info.( entry ) );
 fi;
 od;

 AtlasOfGroupRepresentationsInfo.filenames:= Filtered(
 AtlasOfGroupRepresentationsInfo.filenames,
 x -> x[3] <> dirid );
 AtlasOfGroupRepresentationsInfo.newfilenames:= [];

 # Remove the information concerning the data extension.
 Remove( notified, i );

 # Discard all caches.
 Unbind( AtlasOfGroupRepresentationsInfo.TableOfContents.(
 Concatenation( dirid, "|all" ) ) );
 Unbind( AtlasOfGroupRepresentationsInfo.TableOfContents.(
 Concatenation( dirid, "|local" ) ) );
 AtlasOfGroupRepresentationsInfo.TableOfContents.merged:= rec();
 AGR.SetGAPnamesSortDisp();
 AtlasOfGroupRepresentationsInfo.TOC_Cache:= rec();

 return;

 fi;
 od;

 Print( "#I AtlasOfGroupRepresentationsForgetData:\n",
 "#I There seems to be no data extension with identifier '",
 dirid, "'\n" );
 end );

if IsString( IO_mkdir ) then
 Unbind( IO_mkdir );
fi;
if IsString( IO_stat ) then
 Unbind( IO_stat );
fi;
if IsString( IO_chmod ) then
 Unbind( IO_chmod );
fi;

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

Quelle access.gi Sprache: unbekannt

[Dauer der Verarbeitung: 0.62 Sekunden, vorverarbeitet 2026-04-28]