GAP (ref) - Chapter 3: Running GAP

Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax on]

3 Running GAP
3.1 Command Line Options
3.2 The gap.ini and gaprc files
3.2-1 The gap.ini file
3.2-2 The gaprc file
3.2-3 Configuring User preferences
3.2-4 DeclareUserPreference
3.2-5 User Preferences Defined by GAP
3.3 Saving and Loading a Workspace
3.3-1 SaveWorkspace
3.4 Testing for the System Architecture
3.4-1 ARCH_IS_UNIX
3.4-2 ARCH_IS_MAC_OS_X
3.4-3 ARCH_IS_WINDOWS
3.4-4 ARCH_IS_WSL
3.5 Global Values that Control the GAP Session
3.5-1 GAPInfo
3.6 Coloring the Prompt and Input
3.6-1 ColorPrompt

### 3 Running GAP

This chapter contains information about the command line options for GAP (see 3.1), about some files in user specific GAP root directory (see 3.2) and about saving and loading a GAP workspace (see 3.3).

#### 3.1 Command Line Options

When you start GAP from a command line or from a script you may specify a number of options on the command-line to change the default behaviour of GAP. All these options start with a hyphen `-`, followed by a single letter. Options must not be grouped, e.g., `gap -gq` is invalid, use `gap -g -q` instead. Some options require an argument, this must follow the option and must be separated by whitespace, e.g., `gap -m 256m`, it is not correct to say `gap -m256m` instead. Certain boolean options (`-b`, `-q`, `-e`, `-r`, `-A`, `-D`, `-M`, `-T`, `-X`, `-Y`) toggle the current value so that `gap -b -b` is equivalent to `gap` and to `gap -b -q -b -q` etc.

GAP for UNIX will distinguish between upper and lower case options.

As described in the GAP installation instructions (see the `INSTALL.md` file in the GAP root directory), usually you will not execute GAP directly. Instead you will call a (shell) script, with the name `gap`, which in turn executes GAP. This script sets some options which are necessary to make GAP work on your system. This means that the default settings mentioned below may not be what you experience when you execute GAP on your system.

During a GAP session, one can find the current values of command line options in the record `GAPInfo.CommandLineOptions` (see `GAPInfo` (3.5-1)), whose component names are the command line options (without the leading `-`).

`-A`

  By default, some needed and suggested GAP packages (see 76) are loaded, if present, into the GAP session when it starts. This option disables (actually toggles) the loading of suggested packages, which can be useful for debugging or testing. The needed packages (and their needed packages, and so on) are loaded in any case.

`-b`

  tells GAP to suppress the banner. That means that GAP immediately prints the prompt. This is useful when, after a while, you get tired of the banner. This option can be repeated to enable the banner; each `-b` toggles the state of banner display.

`-c` gapcode

  tells GAP to execute the given GAP code as if it was entered into a temporary file which then is processed together with the other files given to GAP (see the explanation at the end of this list for further details on how filenames are processed).

`-D`

  The `-D` option tells GAP to print short messages when it is reading files or loading modules. This option may be repeated to toggle this behavior on and off. The message,

      #I  READ_GAP_ROOT: loading 'lib/kernel.g' as GAP file

  tells you that GAP has started to read the library file `lib/kernel.g`.

      #I  READ_GAP_ROOT: loading 'lib/kernel.g' statically

  tells you that GAP has used the compiled version of the library file `lib/kernel.g`. This compiled module was statically linked to the GAP kernel at the time the kernel was created.

      #I  READ_GAP_ROOT: loading 'lib/kernel.g' dynamically

  tells you that GAP has loaded the compiled version of the library file `lib/kernel.g`. This compiled module was dynamically loaded to the GAP kernel at runtime from a corresponding `.so` file.

  Obviously, this is a debugging option and most users will not need it.

`-E`

  If your GAP installation uses the `readline` library for command line editing (see 6.9), this may be disabled by using `-E` option. This option may be repeated to toggle this behavior on and off. If your GAP installation does not use the `readline` library (you can check by `IsBound(GAPInfo.UseReadline);` if this is the case), this option will have no effect at all.

`-e`

  tells GAP not to quit when receiving a Ctrl-D on an empty input line (see 6.4-1). This option should not be used when the input is a file or pipe. This option may be repeated to toggle this behavior on and off.

`-f`

  tells GAP to enable the line editing and history (see 6.8).

  In general line editing will be enabled if the input is connected to a terminal. There are rare circumstances, for example when using a remote session with a corrupted telnet implementation, when this detection fails. Try using `-f` in this case to enable line editing. This option does not toggle; you must use `-n` to disable line editing.

`-g`

  tells GAP to print a message every time a full garbage collection is performed. (This is available only if the `GASMAN` garbage collector is used, see 7.12-1.)

      #G  FULL 44580/2479kb live   57304/4392kb dead   734/4096kb free

  For example, this tells you that there are 44580 live objects that survived a full garbage collection, that 57304 unused objects were reclaimed by it, and that 734 kilobytes from a total allocated memory of 4096 kilobytes are available afterwards.

`-g -g`

  If you give the option `-g` twice, GAP prints a information message every time a partial or full garbage collection is performed. (This is available only if the `GASMAN` garbage collector is used, see 7.12-1.) The message,

      #G  PART 9405/961kb+live   7525/1324kb+dead   2541/4096kb free

  for example, tells you that 9405 objects survived the partial garbage collection and 7525 objects were reclaimed, and that 2541 kilobytes from a total allocated memory of 4096 kilobytes are available afterwards.

`-h`
`--help`

  tells GAP to print a summary of all available options. GAP exits after printing the summary, all options coming after are ignored.

`-K` memory
`--limitworkspace` memory

  is like the `-o` option. But while the latter actually allocates more memory if the system allows it and then prints a warning inside a break loop the `-K` options tells GAP not even to try to allocate more memory. Instead GAP just exits with an appropriate message. The default is that this feature is switched off. You have to set it explicitly when you want to enable it.

`-L` filename

  The option `-L` tells GAP to load a saved workspace. See section 3.3. (This is available only if the `GASMAN` garbage collector is used, see 7.12-1.)

`-l` path_list
`--roots` path_list

  can be used to set or modify GAP's list of root directories (see 9.2). The default if no `-l` option is given is the current directory `./`. This option can be used several times. Depending on the `-r` option a further user specific path is prepended to the list of root directories (the path in `GAPInfo.UserGapRoot`).

  path_list should be a list of directories separated by semicolons. No whitespace is permitted before or after a semicolon. If path_list does not start or end with a semicolon, then path_list replaces the existing list of root directories. If path_list starts with a semicolon, then path_list is appended to the existing list of root directories. If path_list ends with a semicolon and does not start with one, then the new list of root directories is the concatenation of path_list and the existing list of root directories. After GAP has completed its startup procedure and displays the prompt, the list of root directories can be seen in the variable `GAPInfo.RootPaths`, see `GAPInfo` (3.5-1).

  Usually this option is used inside a startup script to specify where GAP is installed on the system. The `-l` option can also be used by individual users to tell GAP about privately installed modifications of the library, additional GAP packages and so on. Section 9.2 explains how several root paths can be used to do this.

  GAP will attempt to read the file root_dir`/lib/init.g` during startup where root_dir is one of the directories in its list of root directories. If GAP cannot find its `init.g` file it will print the following warning.

      gap: hmm, I cannot find 'lib/init.g' maybe use option '-l <gaproot>'?

  It is not possible to use GAP without the library files, so you must not ignore this warning. You should leave GAP and start it again, specifying the correct root path using the `-l` option.

`--packagedirs` path_list

  can be used to add paths to GAP's list of package directories (see 9.3). The list always contains all subdirectories `pkg` in a GAP root directory.

  path_list should be a list of directories separated by semicolons. No whitespace is permitted before or after a semicolon, and the first and last character of path_list may not be a semicolon. After GAP has completed its startup procedure and displays the prompt, the list of package directories can be seen in the variable `GAPInfo.PackageDirectories`, see `GAPInfo` (3.5-1).

  Usually this option is used inside a startup script to specify where additional GAP packages are located on the system. The `--packagedirs` option can also be used by individual users to tell GAP about additional GAP packages, without the need to set up a complete root directory structure.

`-M`

  tells GAP not to check for, nor to use, compiled versions of library files. This option may be repeated to toggle this behavior on and off.

`-m` memory
`--minworkspace` memory

  tells GAP to allocate memory bytes at startup time. If the last character of memory is `k` or `K` it is taken as kilobytes, if the last character is `m` or `M` memory is taken as megabytes and if it is `g` or `G` it is taken as gigabytes.

  This amount of memory should be large enough so that computations do not require too many garbage collections. On the other hand, if GAP allocates more memory than is physically available, it will spend most of the time paging.

`-n`

  tells GAP to disable the line editing and history (see 6.8).

  You may want to do this if the command line editing is incompatible with another program that is used to run GAP. For example if GAP is run from inside a GNU Emacs shell window, `-n` should be used since otherwise every input line will be echoed twice, once by Emacs and once by GAP. This option does not toggle; you must use `-f` to enable line editing.

`-O`

  disables loading obsolete variables (see Chapter 77). This option is used mainly for testing purposes, for example in order to make sure that a GAP package or one's own GAP code does not rely on the obsolete variables.

`-o` memory
`--maxworkspace` memory

  tells GAP to allocate at most memory bytes without asking. The option argument memory is specified as with the `-m` option.

  If more than this amount is required during the GAP session, GAP prints an error message and enters a break loop. In that case you can enter `return;` which implicitly doubles the amount given with this option.

`-q`

  tells GAP to be quiet. This means that GAP displays neither the banner nor the prompt `gap>`. This is useful if you want to run GAP as a filter with input and output redirection and want to avoid the banner and the prompts appearing in the output file. This option may be repeated to disable quiet mode; each `-q` toggles quiet mode.

`-R`

  The option `-R` tells GAP not to load a saved workspace previously specified via the `-L` option. This option does not toggle.

`-r`

  The option `-r` tells GAP to ignore any user specific configuration files. In particular, the user specific root directory `GAPInfo.UserGapRoot` is not added to the GAP root directories and so `gap.ini` and `gaprc` files that may be contained in that directory are not read, see 3.2. Multiple `-r` options toggle this behaviour.

`-s` memory

  With this option GAP does not use `sbrk` to get memory from the operating system. Instead it uses `mmap`, `malloc` or some other command for the amount given with this option to allocate space for the `GASMAN` memory manager. Usually GAP does not really use all of this memory, the options `-m`, `-o`, `-K` still work as documented. This feature assumes that the operating system only assigns physical memory to the GAP process when it is accessed, so that specifying a large amount of memory with `-s` should not cause any performance problem. The advantage of using this option is that GAP can work together with kernel modules which allocate a lot of memory with `malloc`.

  The option argument memory is specified as with the `-m` option.

`-T`

  suppresses the usual break loop behaviour of GAP. With this option GAP behaves as if the user `quit` immediately from every break loop, and also suppresses displaying any error backtrace. This is intended for automated testing of GAP. This option may be repeated to toggle this behavior on and off.

`--version`

  tells GAP to print its version and then exit immediately, all options coming after are ignored.

`-x` length
`--width` length

  With this option you can tell GAP how long lines are. GAP uses this value to decide when to split long lines. After starting GAP you may use `SizeScreen` (6.12-1) to alter the line length.

  The default value is 80, unless another value can be obtained from the Operating System, which is the right value if you have a standard terminal application. If you have a larger monitor, or use a smaller font, or redirect the output to a printer, you may want to increase this value.

`-y` length
`--line` length

  With this option you can tell GAP how many lines your screen has. GAP uses this value to decide after how many lines of on-line help it should wait. After starting GAP you may use `SizeScreen` (6.12-1) to alter the number of lines.

  The default value is 24, unless another value can be obtained from the Operating System, which is the right value if you have a standard terminal application. If you have a larger monitor, or use a smaller font, or redirect the output to a printer, you may want to increase this value.

filename ...

  Further arguments are taken as filenames of files that are read by GAP during startup, after the system and private init files are read, but before the first prompt is printed. Filenames ending with `.tst` are processed by `Test` (7.10-2), all other files by `Read` (9.8-1). These files and also commands specified via the `-c` option are processed in the order in which they appear on the command line. If a file cannot be opened or if executing the code in it raises an error, then the usual error handling for `Read` (9.8-1) respectively `Test` (7.10-2) kicks in. If this enters a break loop, then exiting that break loop also exits GAP.

Additional options, such as `-C`, `-P` and`-p` are used internally by the gac script (see 76.3-11) and/or on specific operating systems.

#### 3.2 The gap.ini and gaprc files

When you start GAP, it looks for files with the names `gap.ini` and `gaprc` in its root directories (see 9.2), and reads the first `gap.ini` and the first `gaprc` file it finds. These files are used for certain initializations, as follows.

The file `gap.ini` is read early in the startup process. Therefore, the parameters set in this file can influence the startup process, such as which packages are automatically loaded (see `LoadPackage` (76.2-1)) and whether library files containing obsolete variables are read (see Chapter 77). On the other hand, only calls to a restricted set of GAP functions are allowed in a `gap.ini` file. Usually, it should only contain calls of `SetUserPreference` (3.2-3). This file can be generated (or updated when new releases introduce further user preferences) with the command `WriteGapIniFile` (3.2-3). This file is read whenever GAP is started, with or without a workspace.

The file `gaprc` is read after the startup process, before the first input file given on the command line (see 3.1). So the contents of this file cannot influence the startup process, but all GAP library functions can be called in this file. When GAP is started with a workspace then the file is read only if no `gaprc` file had been read before the workspace was created. (With this setup, it is on the one hand possible that administrators provide a GAP workspace for several users such that the user's `gaprc` file is read when GAP is started with the workspace, and on the other hand one can start GAP, read one's `gaprc` file, save a workspace, and then start from this workspace without reading one's `gaprc` file again.)

Note that by default, the user specific GAP root directory `GAPInfo.UserGapRoot` is the first GAP root directory. So you can put your `gap.ini` and `gaprc` files into this directory.

This mechanism substitutes the much less flexible reading of a users `.gaprc` file in versions of GAP up to 4.4. For compatibility this `.gaprc` file is still read if the directory `GAPInfo.UserGapRoot` does not exist, see 77.5 how to migrate your old setup.

##### 3.2-1 The gap.ini file

The file `gap.ini` is read after the declaration part of the GAP library is read, before the declaration parts of the packages needed and suggested by GAP are read, and before the implementation parts of GAP and of the packages are read.

The file `gap.ini` is expected to consist of calls to the function `SetUserPreference` (3.2-3), see Section `SetUserPreference` (3.2-3).

Since the file `gap.ini` is read before the implementation part of GAP is read, not all GAP functions may be called in the file. Assignments of numbers, lists, and records are admissible as well as calls to basic functions such as `Concatenation` (21.20-1) and `JoinStringsWithSeparator` (27.7-20).

Note that the file `gap.ini` is read also when GAP is started with a workspace.

##### 3.2-2 The gaprc file

If a file `gaprc` is found it is read after GAP's `init.g`, but before any of the files mentioned on the command line are read. You can use this file for your private customizations. (Many users may be happy with using just user preferences in the `gap.ini` file (see above) for private customization.) For example, if you have a file containing functions or data that you always need, you could read this from `gaprc`. Or if you find some of the names in the library too long, you could define abbreviations for those names in `gaprc`. The following sample `gaprc` file does both.

    Read( "/usr/you/dat/mygroups.grp" );
    Ac := Action;
    AcHom := ActionHomomorphism;
    RepAc := RepresentativeAction;

Note that only one `gaprc` file is read when GAP is started. When a workspace is created in a GAP session after a `gaprc` file has been read then no more `gaprc` file will be read when GAP is started with this workspace.

Also note that the file must be called `gaprc`. If you use a Windows text editor, in particular if your default is not to show file suffixes, you might accidentally create a file `gaprc.txt` or `gaprc.doc` which GAP will not recognize.

##### 3.2-3 Configuring User preferences

`‣ SetUserPreference`( [package, ]name, value ) | ( function )

`‣ UserPreference`( [package, ]name ) | ( function )

`‣ ShowUserPreferences`( package1, package2, ... ) | ( function )

`‣ WriteGapIniFile`( [dir][,] [ignorecurrent] ) | ( function )

Some aspects of the behaviour of GAP can be customized by the user via user preferences. Examples include the way help sections are displayed or the use of colors in the terminal.

User preferences are specified via a pair of strings, the first is the (case insensitive) name of a package (or `"GAP"` for the core GAP library) and the second is some arbitrary case sensitive string.

User preferences can be set to some value with `SetUserPreference`. The current value of a user preference can be found with `UserPreference`. In both cases, if no package name is given the default `"GAP"` is used. If a user preference is not known or not set then `UserPreference` returns `fail`.

The stored values of user preferences are always immutable, see Section 12.6.

The function `ShowUserPreferences` with no argument shows in a pager an overview of all known user preferences together with some explanation and the current value. If one or more strings package1, ... are given then only the user preferences for these packages are shown. The Browse package provides the function `BrowseUserPreferences` (Browse: BrowseUserPreferences) which gives an overview of the known user preferenes and also admits editing the values of the preferences.

The easiest way to make use of user preferences is probably to use the function `WriteGapIniFile`, usually without argument. This function creates a file `gap.ini` in your user specific GAP root directory (`GAPInfo.UserGapRoot`). If such a file already exists the function will make a backup of it first. This newly created file contains descriptions of all known user preferences and also calls of `SetUserPreference` for those user preferences which currently do not have their default value. You can then edit that file to customize (further) the user preferences for future GAP sessions.

Should a later version of GAP or some packages introduce new user preferences then you can call `WriteGapIniFile` again since it will set the previously known user preferences to their current values.

Optionally, a different directory for the resulting `gap.ini` file can be specified as argument dir to `WriteGapIniFile`. Another optional argument is the boolean value `true`, if this is given, the settings of all user preferences in the current session are ignored.

Note that your `gap.ini` file is read by GAP very early during its startup process. A consequence is that the value argument in a call of `SetUserPreference` must be some very basic GAP object, usually a boolean, a number, a string or a list of those. A few user preferences support more complicated settings. For example, the user preference `"UseColorPrompt"` admits a record as its value whose components are available only after the GAPDoc package has been loaded, see `ColorPrompt` (3.6-1). If you want to specify such a complicated value, then move the corresponding call of `SetUserPreference` from your `gap.ini` file into your `gaprc` file (also in the directory `GAPInfo.UserGapRoot`). This file is read much later.

    gap> SetUserPreference( "Pager", "less" );
    gap> SetUserPreference("PagerOptions",
    >                      [ "-f", "-r", "-a", "-i", "-M", "-j2" ] );
    gap> UserPreference("Pager");
    "less"

The first two lines of this example will cause GAP to use the programm `less` as a pager. This is highly recommended if `less` is available on your system. The last line displays the current setting.

##### 3.2-4 DeclareUserPreference

`‣ DeclareUserPreference`( record ) | ( function )

This function can be used (also in packages) to introduce new user preferences. It declares a user preference, determines a default value and contains documentation of the user preference. After declaration a user preference will be shown with `ShowUserPreferences` (3.2-3) and `WriteGapIniFile` (3.2-3).

When this declaration is evaluated it is checked, if this user preference is already set in the current session. If not the value of the user preference is set to its default. (Do not use `fail` as default value since this indicated that a user preference is not set.)

The argument record of `DeclareUserPreference` must be a record with the following components.

`name`

  a string or a list of strings, the latter meaning several preferences which belong together,

`description`

  a list of strings describing the preference(s), one string for each paragraph; if several preferences are declared together then the description refers to all of them,

`default`

  the default value that is used, or a function without arguments that computes this default value; if several preferences are declared together then the value of this component must be the list of default values for the individual preferences.

The following components of record are optional.

`check`

  a function that takes a value as its argument and returns either `true` or `false`, depending on whether the given value is admissible for this preference; if several preferences are declared together then the number of arguments of the function must equal the length of the `name` list,

`values`

  the list of admissible values, or a function without arguments that returns this list,

`multi`

  `true` or `false`, depending on whether one may choose several values from the given list or just one; needed (and useful only) if the `values` component is present,

`package`

  the name of the GAP package to which the preference is assigned; if the declaration happens inside a file that belongs to this package then the value of this component is computed, using `GAPInfo.PackageCurrent`; otherwise, the default value for `package` is `"GAP"`,

`omitFromGapIniFile`

  if the value is `true` then this user preference is ignored by `WriteGapIniFile` (3.2-3).

    gap> UserPreference( "MyFavouritePrime" );
    fail
    gap> DeclareUserPreference( rec(
    >        name:= "MyFavouritePrime",
    >        description:= [ "is not used, serves as an example" ],
    >        default:= 2,
    >        omitFromGapIniFile:= true ) );
    gap> UserPreference( "MyFavouritePrime" );
    2
    gap> SetUserPreference( "MyFavouritePrime", 17 );
    gap> UserPreference( "MyFavouritePrime" );
    17

##### 3.2-5 User Preferences Defined by GAP

Here is the list of those user preferences that are currently declared via `DeclareUserPreference` (3.2-4) for GAP itself. The preferences that are declared for GAP packages belong to the documentation of these packages.

`Autocompleter`

  Set how names are filtered during tab-autocomplete, this can be: `"default"`: case-sensitive matching. `"case-insensitive"`: case-insensitive matching, or a record with two components named `filter` and `completer`, which are both functions which take two arguments. `filter` takes a list of names and a partial identifier and returns all the members of `names` which are a valid extension of the partial identifier. `completer` takes a list of names and a partial identifier and returns the partial identifier as extended as possible (it may also change the identifier, for example to correct the case, or spelling mistakes), or returns `fail` to leave the existing partial identifier.

  This preference is ignored if GAP was not compiled with readline support.

  Default: `"default"`.

`Editor`, `EditorOptions`

  Determines the editor and options (used by GAP's `Edit` (6.10-1) command). Under macOS, the value `"open"` for `Editor` will work. For further options, see the GAP help for `Edit` (6.10-1). If you want to use the editor defined in your (shell) environment then leave the `Editor` and `EditorOptions` preferences empty.

  The defaults are computed at runtime.

`ExcludeFromAutoload`

  These packages are not loaded at GAP startup. This doesn't work for packages which are needed by the GAP library, or which are already loaded in a workspace.

  Default: `""`.

`HelpViewers`, `XpdfOptions`, `XdviOptions`

  Here you can choose your preferred help viewers. See the help for `SetHelpViewer` (2.3-1) for further options.

  Try `HelpViewers:= [ "screen", "firefox", "xpdf" ];`.

  (For `"screen"` we also suggest to set the `Pager` entry to `"less"`.)

  Defaults: `[ [ "screen" ], "", "" ]`.

`HistoryBackwardSearchSkipIdenticalEntries`

  When a command is executed multiple times, it is also stored in history multiple times. Setting this option to `true` skips identical entries when searching backwards in history.

  Admissible values: `true`, `false`.

  Default: `false`.

`HistoryMaxLines`, `SaveAndRestoreHistory`

  `HistoryMaxLines` is the maximal amount of input lines held in GAP's command line history.

  If `SaveAndRestoreHistory` is `true` then GAP saves its command line history before terminating a GAP session, and prepends the stored history when GAP is started. If this is enabled it is suggested to set `HistoryMaxLines` to some finite value. It is also possible to set `HistoryMaxLines` to `infinity` (18.2-1) to keep arbitrarily many lines.

  These preferences are ignored if GAP was not compiled with readline support.

  Defaults: `[ 10000, true ]`.

`InfoPackageLoadingLevel`

  Info messages concerning package loading up to this level are printed. The level can be changed in a running session using `SetInfoLevel` (7.4-3).

  Admissible values: `1`, `2`, `3`, `4`.

  Default: `1`.

`MaxBitsIntView`

  Maximal bit length of integers to `View` unabbreviated. Default is about 30 lines of a 80 character wide terminal. Set this to `0` to avoid abbreviated ints.

  Default: `8000`.

`PartialPermDisplayLimit`, `NotationForPartialPerms`

  options for the display of partial perms

  Defaults: `[ 100, "component" ]`.

`TransformationDisplayLimit`, `NotationForTransformations`

  options for the display of transformations

  Defaults: `[ 100, "input" ]`.

`PackagesToIgnore`

  These packages are not regarded as available. This doesn't work for packages which are needed by the GAP library, or which are already loaded in a workspace.

  Default: `""`.

`PackagesToLoad`

  A list of names of packages which should be loaded during startup. For backwards compatibility, the default lists most of packages that were autoloaded in GAP 4.4 (add or remove packages as you like).

  Default: `[ "autpgrp", "alnuth", "crisp", "ctbllib", "factint", "fga", "irredsol", "laguna", "PackageManager", "polenta", "polycyclic", "resclasses", "sophus", "tomlib" ]`.

`Pager`, `PagerOptions`

  For displaying help pages on screen and other things GAP has a rudimentary builtin pager. We recommend using a more sophisticated external program. For example, when you have the program `less` on your computer we recommend:

  `Pager := "less";`

  `PagerOptions := ["-f", "-r", "-a", "-i", "-M", "-j2"];`

  If you want to use `more`, we suggest to use the `-f` option. If you want to use the pager defined in your environment then leave the `Pager` and `PagerOptions` preferences empty.

  The defaults are computed at runtime.

`ReadObsolete`

  May be useful to say `false` here to check if you are using commands which may vanish in a future version of GAP

  Admissible values: `true`, `false`.

  Default: `true`.

`ReproducibleBehaviour`

  This preference disables code in GAP which changes behaviour based on time spent, and therefore can produce different results depending on how much time is taken by other programs running on the same computer. This option may lead to slower or lower-quality results. Note that many algorithms in GAP use the global random number generator, which is NOT affected by this option. This only tries to ensure the same version of GAP, with the same package versions loaded, on the same machine, running the same code, in a fresh GAP session, will produce the same results.

  Admissible values: `true`, `false`.

  Default: `false`.

`ShortBanners`

  If this option is set to `true`, package banners printed during loading will only show the name, version and description of a package.

  Admissible values: `true`, `false`.

  Default: `false`.

`UseColorPrompt`

  In a color capable terminal (almost any terminal application) you can run GAP such that the prompts, the input and output are distinguished by colors. Options are `true`, `false` or some record as explained in the help section for `ColorPrompt` (3.6-1).

  Default: `true`.

`UseColorsInTerminal`

  Almost all current terminal emulations support color display, setting this to `true` implies a default display of most manuals with color markup. It may influence the display of other things in the future.

  Admissible values: `true`, `false`.

  Default: `true`.

`ViewLength`

  A bound for the number of lines printed when `View`ing some large objects.

  Default: `3`.

`WhereDepth`

  The number of stack frames shown by `Where` and `WhereWithVars` when called without an explicit depth argument, e.g. in the default `OnBreak` handler.

  Default: `5`.

#### 3.3 Saving and Loading a Workspace

GAP workspace files are binary files that contain the data of a GAP session. Currently saving and loading workspace files are supported only when the `GASMAN` garbage collector is used, see Section 7.12-1.

One can produce a workspace file with `SaveWorkspace` (3.3-1), and load it into a new GAP session using the `-L` command line option, see Section 3.1.

One purpose of workspace files is of course the possibility to save a snapshot image of the current GAP workspace in a file.

The recommended way to start GAP is to load an existing workspace file, because this reduces the startup time of GAP drastically. So if you have installed GAP yourself then you should think about creating a workspace file immediately after you have started GAP, and then using this workspace file later on, whenever you start GAP. If your GAP installation is shared between several users, the system administrator should think about providing such a workspace file.

##### 3.3-1 SaveWorkspace

`‣ SaveWorkspace`( filename ) | ( function )

will save a snapshot image of the current GAP workspace in the file filename. This image then can be loaded by another copy of GAP which then will behave as at the point when `SaveWorkspace` was called.

    gap> a:=1;
    gap> SaveWorkspace("savefile");
    true
    gap> quit;

`SaveWorkspace` can only be used at the main `gap>` prompt. It cannot be included in the body of a loop or function, or called from a break loop.

#### 3.4 Testing for the System Architecture

##### 3.4-1 ARCH_IS_UNIX

`‣ ARCH_IS_UNIX`( ) | ( function )

tests whether GAP is running on a UNIX system (including macOS).

##### 3.4-2 ARCH_IS_MAC_OS_X

`‣ ARCH_IS_MAC_OS_X`( ) | ( function )

tests whether GAP is running on macOS. Note that on macOS, also `ARCH_IS_UNIX` (3.4-1) will be `true`.

##### 3.4-3 ARCH_IS_WINDOWS

`‣ ARCH_IS_WINDOWS`( ) | ( function )

tests whether GAP is running on a Windows system without standard POSIX tools available (such as a shell).

##### 3.4-4 ARCH_IS_WSL

`‣ ARCH_IS_WSL`( ) | ( function )

tests whether GAP is running on a Windows system inside the 'Windows Subsystem for Linux'. Note that in this case `ARCH_IS_UNIX` (3.4-1) will be `true`, and in most situations WSL can be treated identically to Linux.

#### 3.5 Global Values that Control the GAP Session

##### 3.5-1 GAPInfo

`‣ GAPInfo` | ( global variable )

Several global values control the GAP session, such as the command line, the architecture, or the information about available and loaded packages. Many of these values are accessible as components of the global record `GAPInfo`. Typically, these components are set and read in low level GAP functions, so changing the values of existing components of `GAPInfo` by hand is not recommended.

Important components are documented via index entries, try the input `??GAPInfo` for getting an overview of these components.

#### 3.6 Coloring the Prompt and Input

GAP provides hooks for functions which are called when the prompt is to be printed and when an input line is finished.

An example of using this feature is the following function.

##### 3.6-1 ColorPrompt

`‣ ColorPrompt`( bool[, optrec] ) | ( function )

`ColorPrompt` changes GAP's user interface: After calling `ColorPrompt(true);`, the prompts and the user input are displayed in colors different from the color that is used for the output. This is also the default for a GAP session. Switch off these colorings with `ColorPrompt(false);`.

Note that colors will only work if your terminal emulation in which you run GAP understands the so called ANSI color escape sequences –almost all terminal emulations on current UNIX/Linux (`xterm`, `rxvt`, `konsole`, ...) systems do so.

The colors shown depend on the terminal configuration and cannot be forced from an application. If your terminal follows the ANSI conventions you see the standard prompt in bold blue and the break loop prompt in bold red, as well as your input in red.

If you prefer to switch off colors for prompts and input at the start of your GAP sessions, put a call of `SetUserPreference("UseColorPrompt", false);` in your `gap.ini` file. If you want a more complicated setting as explained below then put your `SetUserPreference("UseColorPrompt", rec( ... ) );` call into your `gaprc` file.

The optional second argument optrec allows one to further customize the behaviour. It must be a record from which the following components are recognized:

`MarkupStdPrompt`

  a string or no argument function returning a string containing the escape sequence used for the main prompt `gap>` .

`MarkupContPrompt`

  a string or no argument function returning a string containing the escape sequence used for the continuation prompt `>` .

`MarkupBrkPrompt`

  a string or no argument function returning a string containing the escape sequence used for the break prompt `brk...>` .

`MarkupInput`

  a string or no argument function returning a string containing the escape sequence used for user input.

`TextPrompt`

  a no argument function returning the string with the text of the prompt, but without any escape sequences. The current standard prompt is returned by `CPROMPT()`. But note that changing the standard prompts makes the automatic removal of prompts from input lines impossible (see 6.2).

`PrePrompt`

  a function called before printing a prompt.

Here is an example.

    LoadPackage("GAPDoc");
    timeSHOWMIN := 100;
    ColorPrompt(true, rec(
       # usually cyan bold, see ?TextAttr
       MarkupStdPrompt := Concatenation(TextAttr.bold, TextAttr.6),
       MarkupContPrompt := Concatenation(TextAttr.bold, TextAttr.6),
       PrePrompt := function()
         # show the 'time' automatically if at least timeSHOWMIN
         if CPROMPT() = "gap> " and time >= timeSHOWMIN then
           Print("Time of last command: ", time, " ms\n");
         fi;
       end)    );

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 Bib Ind

generated by GAPDoc2HTML