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,
  
          Example  
          #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.
  
          Example  
          #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.
  
          Example  
          #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.)
  
          Example  
          #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,
  
          Example  
          #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.
  
          Example  
          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 GAP will print an error message and will abort.
  
  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.
  
    Example  
    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  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  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.
  
    Example  
    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).
  
    Example  
    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.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.
  
    Example  
    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 Mac OS X).
  
  3.4-2 ARCH_IS_MAC_OS_X
  
  ARCH_IS_MAC_OS_X(  )  function
  
  tests  whether  GAP  is  running  on  Mac  OS X. Note that on Mac OS X, 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)    );