[MathJax off]

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

tells GAP to print a summary of all available options (-h is mnemonic for help). GAP exits after printing the summary, all other options are ignored.

-K 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

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.

-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

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

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.

-x 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

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.7-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.7-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

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

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", "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 Viewing some large objects.

Default: 3.

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

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

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

3.4-2 ARCH_IS_MAC_OS_X

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

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

3.4-4 ARCH_IS_WSL

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

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 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)    );

generated by GAPDoc2HTML