GAP (ref) - Chapter 6: Main Loop and Break Loop

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]

6 Main Loop and Break Loop
6.1 Main Loop
6.2 Special Rules for Input Lines
6.3 View and Print
6.3-1 Default delegations in the library
6.3-2 Recommendations for the implementation
6.3-3 View
6.3-4 Print
6.3-5 ViewObj
6.3-6 Display
6.3-7 SetNameObject
6.4 Break Loops
6.4-1 quit from a break loop
6.4-2 return from a break loop
6.4-3 OnBreak
6.4-4 OnBreakMessage
6.4-5 Where
6.5 Variable Access in a Break Loop
6.5-1 DownEnv and UpEnv
6.6 Error and ErrorCount
6.6-1 Error
6.6-2 ErrorNoReturn
6.6-3 ErrorCount
6.7 Leaving GAP
6.7-1 QUIT
6.7-2 GapExitCode
6.7-3 QuitGap
6.7-4 ForceQuitGap
6.7-5 InstallAtExit
6.7-6 SaveOnExitFile
6.8 Line Editing
6.9 Editing using the `readline` library
6.9-1 Readline customization
6.9-2 The command line history
6.9-3 SaveCommandLineHistory
6.9-4 Writing your own command line editing functions
6.10 Editing Files
6.10-1 Edit
6.11 Editor Support
6.12 Changing the Screen Size
6.12-1 SizeScreen
6.13 Teaching Mode
6.13-1 TeachingMode

### 6 Main Loop and Break Loop

This chapter is a first of a series of chapters that describe the interactive environment in which you use GAP.

#### 6.1 Main Loop

The normal interaction with GAP happens in the so-called read-eval-print loop. This means that you type an input, GAP first reads it, evaluates it, and then shows the result. Note that the term print may be confusing since there is a GAP function called `Print` (6.3-4) (see 6.3) which is in fact not used in the read-eval-print loop, but traditions are hard to break. In the following, whenever we want to express that GAP places some characters on the standard output, we will say that GAP shows something.

The exact sequence in the read-eval-print loop is as follows.

To signal that it is ready to accept your input, GAP shows the prompt `gap>`. When you see this, you know that GAP is waiting for your input.

Note that every statement must be terminated by a semicolon. You must also enter Return (i.e., strike the Return key) before GAP starts to read and evaluate your input. (The Return key may actually be marked with the word Enter and a returning arrow on your terminal.) Because GAP does not do anything until you enter Return, you can edit your input to fix typos and only when everything is correct enter Return and have GAP take a look at it (see 6.8). It is also possible to enter several statements as input on a single line. Of course each statement must be terminated by a semicolon.

It is absolutely acceptable to enter a single statement on several lines. When you have entered the beginning of a statement, but the statement is not yet complete, and you enter Return, GAP will show the partial prompt `>`. When you see this, you know that GAP is waiting for the rest of the statement. This happens also when you forget the semicolon `;` that terminates every GAP statement. Note that when Return has been entered and the current statement is not yet complete, GAP will already evaluate those parts of the input that are complete, for example function calls that appear as arguments in another function call which needs several input lines. So it may happen that one has to wait some time for the partial prompt.

When you enter Return, GAP first checks your input to see if it is syntactically correct (see Chapter 4 for the definition of syntactically correct). If it is not, GAP prints an error message of the following form

    gap> 1 * ;
    Syntax error: Expression expected
    1 * ;
        ^

The first line tells you what is wrong about the input, in this case the `*` operator takes two expressions as operands, so obviously the right one is missing. If the input came from a file (see `Read` (9.7-1)), this line will also contain the filename and the line number. The second line is a copy of the input. And the third line contains a caret pointing to the place in the previous line where GAP realized that something is wrong. This need not be the exact place where the error is, but it is usually quite close.

Sometimes, you will also see a partial prompt after you have entered an input that is syntactically incorrect. This is because GAP is so confused by your input, that it thinks that there is still something to follow. In this case you should enter `;`Return repeatedly, ignoring further error messages, until you see the full prompt again. When you see the full prompt, you know that GAP forgave you and is now ready to accept your next –hopefully correct– input.

If your input is syntactically correct, GAP evaluates or executes it, i.e., performs the required computations (see Chapter 4 for the definition of the evaluation).

If you do not see a prompt, you know that GAP is still working on your last input. Of course, you can type ahead, i.e., already start entering new input, but it will not be accepted by GAP until GAP has completed the ongoing computation.

When GAP is ready it will usually show the result of the computation, i.e., the value computed. Note that not all statements produce a value, for example, if you enter a `for` loop, nothing will be printed, because the `for` loop does not produce a value that could be shown.

Also sometimes you do not want to see the result. For example if you have computed a value and now want to assign the result to a variable, you probably do not want to see the value again. You can terminate statements by two semicolons to suppress showing the result.

If you have entered several statements on a single line GAP will first read, evaluate, and show the first one, then read, evaluate, and show the second one, and so on. This means that the second statement will not even be checked for syntactical correctness until GAP has completed the first computation.

After the result has been shown GAP will display another prompt, and wait for your next input. And the whole process starts all over again. Note that if you have entered several statements on a single line, a new prompt will only be printed after GAP has read, evaluated, and shown the last statement.

In each statement that you enter, the result of the previous statement that produced a value is available in the variable `last`. The next to previous result is available in `last2` and the result produced before that is available in `last3`.

    gap> 1;2;3;
    1
    2
    3
    gap> last3 + last2 * last;
    7

Also in each statement the time spent by the last statement, whether it produced a value or not, is available in the variable `time` (7.6-4). This is an integer that holds the number of milliseconds. Similarly the amount of memory allocated during that statement (in bytes) is stored in the variable `memory_allocated` (7.7-2). The variables `last`, `last2`, `last3`, `time` (7.6-4) and `memory_allocated` (7.7-2) are all write-protected.

#### 6.2 Special Rules for Input Lines

The input for some GAP objects may not fit on one line, in particular big integers, long strings or long identifiers. In these cases you can still type or paste them in long single lines. For nicer display you can also specify the input on several lines. This is achieved by ending a line by a backslash or by a backslash and a carriage return character, then continue the input on the beginning of the next line. When reading this GAP will ignore such continuation backslashes, carriage return characters and newline characters. GAP also prints long strings and integers this way.

    gap> n := 1234\
    > 567890;
    1234567890
    gap> "This is a very long string that does not fit on a line \
    > and is therefore continued on the next line.";
    "This is a very long string that does not fit on a line and is therefo\
    re continued on the next line."
    gap> bla\
    > bla := 5;; blabla;
    5

There is a special rule about GAP prompts in input lines: In line editing mode (usual user input and GAP started without `-n`) in lines starting with whitespace following `gap>` , `>` or `brk>` this beginning part is removed. This rule is very convenient because it allows to cut and paste input from other GAP sessions or manual examples easily into your current session.

#### 6.3 View and Print

GAP has three different operations to display or print objects: `Display` (6.3-6), `ViewObj` (6.3-5) and `PrintObj` (6.3-5), and these three have different purposes as follows. The first, `Display` (6.3-6), should print the object to the standard output in a human-readable relatively complete and verbose form. The second, `ViewObj` (6.3-5), should print the object to the standard output in a short and concise form, it is used in the main read-eval-print loop to display the resulting object of a computation. The third, `PrintObj` (6.3-5), should print the object to the standard output in a complete form which is GAP-readable if at all possible, such that reading the output into GAP produces an object which is equal to the original one.

All three operations have corresponding operations which do not print anything to standard output but return the output as a string. These are `DisplayString` (27.7-1), `ViewString` (27.7-3) and `PrintString` (27.7-5) (corresponding to `PrintObj` (6.3-5)). Additionally, there is `String` (27.7-6) which is very similar to `PrintString` (27.7-5) but does not insert control characters for line breaks.

For implementation convenience it is allowed that some of these operations have methods which delegate to some other of these operations. However, the rules for this are that a method may only delegate to another operation which appears further down in the following table:

`Display` (6.3-6)
`ViewObj` (6.3-5)
`PrintObj` (6.3-5)
`DisplayString` (27.7-1)
`ViewString` (27.7-3)
`PrintString` (27.7-5)
`String` (27.7-6)

This is to avoid circular delegations.

Note in particular that none of the methods of the string producing operations may delegate to the corresponding printing operations. Note also that the above mentioned purposes of the different operations suggest that delegations between different operations will be sub-optimal in most scenarios.

##### 6.3-1 Default delegations in the library

The library contains the following low ranked default methods:

- A method for `DisplayString` (27.7-1) which returns the constant value of the global variable `DEFAULTDISPLAYSTRING` (27.7-2).

- A method for `ViewString` (27.7-3) which returns the constant value of the global variable `DEFAULTVIEWSTRING` (27.7-4).

- A method for `Display` (6.3-6) which first calls `DisplayString` (27.7-1) and prints the result, if it is a different object than `DEFAULTDISPLAYSTRING` (27.7-2). Otherwise the method delegates to `PrintObj` (6.3-5).

- A method for `ViewObj` (6.3-5) which first calls `ViewString` (27.7-3) and prints the result, if it is a different object than `DEFAULTVIEWSTRING` (27.7-4). Otherwise the method delegates to `PrintObj` (6.3-5).

- A method for `PrintObj` (6.3-5) which prints the result of `PrintString` (27.7-5).

- A method for `PrintString` (27.7-5) which returns the result of `String` (27.7-6)

##### 6.3-2 Recommendations for the implementation

This subsection describes what methods for printing and viewing one should implement for new GAP objects.

One should at the very least install a `String` (27.7-6) method to allow printing. Using the standard delegations this enables a limited form of viewing, displaying and printing.

If, for larger objects, nicer line breaks are needed, one should install a separate `PrintString` (27.7-5) method which puts in positions for good line breaks using the control characters `\<` (ASCII 1) and `\>` (ASCII 2).

If, for even larger objects, output performance and memory usage matters, one should install a separate `PrintObj` (6.3-5) method.

One should usually install a `ViewString` (27.7-3) method, unless the above `String` (27.7-6) method is good enough for `ViewObj` (6.3-5) purposes. Performance and memory should never matter here, so it is usually unnecessary to install a separate `ViewObj` (6.3-5) method.

If the type of object calls for it one should install a `DisplayString` (27.7-1) method. This is the case if a human readable verbose form is required.

If the performance and memory usage for `Display` (6.3-6) matters, one should install a separate `Display` (6.3-6) method.

Note that if only a `String` (27.7-6) method is installed, then `ViewObj` (6.3-5) works and `ViewString` (27.7-3) returns `DEFAULTVIEWSTRING` (27.7-4). Likewise, `Display` (6.3-6) works and `DisplayString` (27.7-1) returns `DEFAULTDISPLAYSTRING` (27.7-2). If you want to avoid this then install methods for these operations as well.

##### 6.3-3 View

`‣ View`( obj1, obj2... ) | ( function )

`View` shows the objects obj1, obj2... etc. in a short form on the standard output by calling the `ViewObj` (6.3-5) operation on each of them. `View` is called in the read-eval-print loop, thus the output looks exactly like the representation of the objects shown by the main loop. Note that no space or newline is printed between the objects.

##### 6.3-4 Print

`‣ Print`( obj1, obj2, ... ) | ( function )

Also `Print` shows the objects obj1, obj2... etc. on the standard output. The difference compared to `View` (6.3-3) is in general that the shown form is not required to be short, and that in many cases the form shown by `Print` is GAP readable.

    gap> z:= Z(2);
    Z(2)^0
    gap> v:= [ z, z, z, z, z, z, z ];
    [ Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0 ]
    gap> ConvertToVectorRep(v);; v;
    <a GF2 vector of length 7>
    gap> Print( v, "\n" );
    [ Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0 ]

Another difference is that `Print` shows strings without the enclosing quotes, so `Print` can be used to produce formatted text on the standard output (see also chapter 27). Some characters preceded by a backslash, such as `\n`, are processed specially (see chapter 27.2). `PrintTo` (9.7-3) can be used to print to a file.

    gap> for i in [1..5] do
    >      Print( i, " ", i^2, " ", i^3, "\n" );
    >    od;
    1 1 1
    2 4 8
    3 9 27
    4 16 64
    5 25 125
    gap> g:= SmallGroup(12,5);
    <pc group of size 12 with 3 generators>
    gap> Print( g, "\n" );
    Group( [ f1, f2, f3 ] )
    gap> View( g );  Print( "\n" );
    <pc group of size 12 with 3 generators>

##### 6.3-5 ViewObj

`‣ ViewObj`( obj ) | ( operation )

`‣ PrintObj`( obj ) | ( operation )

The functions `View` (6.3-3) and `Print` (6.3-4) actually call the operations `ViewObj` and `PrintObj`, respectively, for each argument. By installing special methods for these operations, it is possible to achieve special printing behavior for certain objects (see chapter 78). The only exceptions are strings (see Chapter 27), for which the default `PrintObj` and `ViewObj` methods as well as the function `View` (6.3-3) print also the enclosing doublequotes, whereas `Print` (6.3-4) strips the doublequotes.

The default method for `ViewObj` is to call `PrintObj`. So it is sufficient to have a `PrintObj` method for an object in order to `View` (6.3-3) it. If one wants to supply a short form for `View` (6.3-3), one can install additionally a method for `ViewObj`.

##### 6.3-6 Display

`‣ Display`( obj ) | ( operation )

Displays the object obj in a nice, formatted way which is easy to read (but might be difficult for machines to understand). The actual format used for this depends on the type of obj. Each method should print a newline character as last character.

    gap> Display( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ] * Z(5) );
     2 4 1
     3 . 2

One can assign a string to an object that `Print` (6.3-4) will use instead of the default used by `Print` (6.3-4), via `SetName` (12.8-1). Also, `Name` (12.8-2) returns the string previously assigned to the object for printing, via `SetName` (12.8-1). The following is an example in the context of domains.

    gap> g:= Group( (1,2,3,4) );
    Group([ (1,2,3,4) ])
    gap> SetName( g, "C4" ); g;
    C4
    gap> Name( g );
    "C4"

When setting up examples, in particular if for beginning users, it sometimes can be convenient to hide the structure behind a printing name. For many objects, such as groups, this can be done using `SetName` (12.8-1). If the objects however is represented internally, for example permutations representing group elements, this function is not applicable. Instead the function `SetNameObject` (6.3-7) can be used to interface with the display routines on a lower level.

##### 6.3-7 SetNameObject

`‣ SetNameObject`( o, s ) | ( function )

`SetNameObject` sets the string s as display name for object o in an interactive session. When applying `View` (6.3-3) to object o, for example in the system's main loop, GAP will print the string s. Calling `SetNameObject` for the same object o with s set to `fail` (20.2-1) deletes the special viewing setup. Since use of this features potentially slows down the whole print process, this function should be used sparingly.

    gap> SetNameObject(3,"three");
    gap> Filtered([1..10],IsPrimeInt);
    [ 2, three, 5, 7 ]
    gap> SetNameObject(3,fail);
    gap> Filtered([1..10],IsPrimeInt);
    [ 2, 3, 5, 7 ]

#### 6.4 Break Loops

When an error has occurred or when you interrupt GAP (usually by hitting Ctrl-C) GAP enters a break loop, that is in most respects like the main read eval print loop (see 6.1). That is, you can enter statements, GAP reads them, evaluates them, and shows the result if any. However those evaluations happen within the context in which the error occurred. So you can look at the arguments and local variables of the functions that were active when the error happened and even change them. The prompt is changed from `gap>` to `brk>` to indicate that you are in a break loop.

    gap> 1/0;
    Rational operations: <divisor> must not be zero
    not in any function
    Entering break read-eval-print loop ...
    you can 'quit;' to quit to outer loop, or
    you can replace <divisor> via 'return <divisor>;' to continue

If errors occur within a break loop GAP enters another break loop at a deeper level. This is indicated by a number appended to `brk`:

    brk> 1/0;
    Rational operations: <divisor> must not be zero
    not in any function
    Entering break read-eval-print loop ...
    you can 'quit;' to quit to outer loop, or
    you can replace <divisor> via 'return <divisor>;' to continue
    brk_02>

There are two ways to leave a break loop, see 6.4-1 and 6.4-2.

##### 6.4-1 quit from a break loop

The first way to leave a break loop is to quit the break loop. To do this you enter `quit;` or type the eof (end of file) character, which is usually Ctrl-D except when using the `-e` option (see Section 3.1). Note that GAP code between `quit;` and the end of the input line is ignored.

    brk_02> quit;
    brk>

In this case control returns to the break loop one level above or to the main loop, respectively. So iterated break loops must be left iteratively. Note also that if you type `quit;` from a `gap>` prompt, GAP will exit (see 6.7).

Note: If you leave a break loop with `quit` without completing a command it is possible (though not very likely) that data structures will be corrupted or incomplete data have been stored in objects. Therefore no guarantee can be given that calculations afterwards will return correct results! If you have been using options `quit`ting a break loop generally leaves the options stack with options you no longer want. The function `ResetOptionsStack` (8.1-3) removes all options on the options stack, and this is the sole intended purpose of this function.

##### 6.4-2 return from a break loop

The other way to leave a break loop is to return from a break loop. To do this you type `return;` or `return obj;`. If the break loop was entered because you interrupted GAP, then you can continue by typing `return;`. If the break loop was entered due to an error, you may have to modify the value of a variable before typing `return;` (see the example for `IsDenseList` (21.1-2)) or you may have to return an object obj (by typing: `return obj;`) to continue the computation; in any case, the message printed on entering the break loop will tell you which of these alternatives is possible. For example, if the break loop was entered because a variable had no assigned value, the value to be returned is often a value that this variable should have to continue the computation.

    brk> return 9;  # we had tried to enter the divisor 9 but typed 0 ...
    1/9
    gap>

##### 6.4-3 OnBreak

`‣ OnBreak`( ) | ( function )

By default, when a break loop is entered, GAP prints a trace of the innermost 5 commands currently being executed. This behaviour can be configured by changing the value of the global variable `OnBreak`. When a break loop is entered, the value of `OnBreak` is checked. If it is a function, then it is called with no arguments. By default, the value of `OnBreak` is `Where` (6.4-5).

    gap> OnBreak := function() Print("Hello\n"); end;
    function(  ) ... end

    gap> Error("!\n");
    Error, !
    Hello
    Entering break read-eval-print loop ...
    you can 'quit;' to quit to outer loop, or
    you can 'return;' to continue
    brk> quit;

In cases where a break loop is entered during a function that was called with options (see Chapter 8), a `quit;` will also cause the options stack to be reset and an `Info`-ed warning stating this is emitted at `InfoWarning` (7.4-8) level 1 (see Chapter 7.4).

Note that for break loops entered by a call to `Error` (6.6-1), the lines after `Entering break read-eval-print loop ...` and before the `brk>` prompt can also be customised, namely by redefining `OnBreakMessage` (6.4-4).

Also, note that one can achieve the effect of changing `OnBreak` locally. As mentioned above, the default value of `OnBreak` is `Where` (6.4-5). Thus, a call to `Error` (6.6-1) generally gives a trace back up to five levels of calling functions. Conceivably, we might like to have a function like `Error` (6.6-1) that does not trace back without globally changing `OnBreak`. Such a function we might call `ErrorNoTraceBack` and here is how we might define it. (Note `ErrorNoTraceBack` is not a GAP function.)

    gap> ErrorNoTraceBack := function(arg) # arg is special variable that GAP
    >                                      # knows to treat as list of arg's
    >      local SavedOnBreak, ENTBOnBreak;
    >      SavedOnBreak := OnBreak;        # save current value of OnBreak
    >
    >      ENTBOnBreak := function()       # our `local' OnBreak
    >      local s;
    >        for s in arg do
    >          Print(s);
    >        od;
    >        OnBreak := SavedOnBreak;      # restore OnBreak afterwards
    >      end;
    >
    >      OnBreak := ENTBOnBreak;
    >      Error();
    >    end;
    function( arg... ) ... end

Here is a somewhat trivial demonstration of the use of `ErrorNoTraceBack`.

    gap> ErrorNoTraceBack("Gidday!", " How's", " it", " going?\n");
    Error, Gidday! How's it going?
    Entering break read-eval-print loop ...
    you can 'quit;' to quit to outer loop, or
    you can 'return;' to continue
    brk> quit;

Now we call `Error` (6.6-1) with the same arguments to show the difference.

    gap> Error("Gidday!", " How's", " it", " going?\n");
    Error, Gidday! How's it going?
    Hello
    Entering break read-eval-print loop ...
    you can 'quit;' to quit to outer loop, or
    you can 'return;' to continue
    brk> quit;

Observe that the value of `OnBreak` before the `ErrorNoTraceBack` call was restored. However, we had changed `OnBreak` from its default value; to restore `OnBreak` to its default value, we should do the following.

    gap> OnBreak := Where;;

##### 6.4-4 OnBreakMessage

`‣ OnBreakMessage`( ) | ( function )

When a break loop is entered by a call to `Error` (6.6-1) the message after the `Entering break read-eval-print loop ...` line is produced by the function `OnBreakMessage`, which just like `OnBreak` (6.4-3) is a user-configurable global variable that is a function with no arguments.

    gap> OnBreakMessage(); # By default, OnBreakMessage prints the following
    you can 'quit;' to quit to outer loop, or
    you can 'return;' to continue

Perhaps you are familiar with what's possible in a break loop, and so don't need to be reminded. In this case, you might wish to do the following (the first line just makes it easy to restore the default value later).

    gap> NormalOnBreakMessage := OnBreakMessage;; # save the default value
    gap> OnBreakMessage := function() end;        # do-nothing function
    function(  ) ... end
    gap> OnBreakMessage();
    gap> OnBreakMessage := NormalOnBreakMessage;; # reset

With `OnBreak` (6.4-3) still set away from its default value, calling `Error` (6.6-1) as we did above, now produces:

    gap> Error("!\n");
    Error, !
    Hello
    Entering break read-eval-print loop ...
    brk> quit; # to get back to outer loop

However, suppose you are writing a function which detects an error condition and `OnBreakMessage` needs to be changed only locally, i.e., the instructions on how to recover from the break loop need to be specific to that function. The same idea used to define `ErrorNoTraceBack` (see `OnBreak` (6.4-3)) can be adapted to achieve this. The function `CosetTableFromGensAndRels` (47.6-5) is an example in the GAP code where the idea is actually used.

##### 6.4-5 Where

`‣ Where`( nr ) | ( function )

`‣ WhereWithVars`( nr ) | ( function )

shows the last nr commands on the execution stack during whose execution the error occurred. If not given, nr defaults to 5. (Assume, for the following example, that after the last example `OnBreak` (6.4-3) has been set back to its default value.). `WhereWithVars` acts the same as `Where` while also showing the arguments and local variables of each function.

    gap> StabChain(SymmetricGroup(100)); # After this we typed ^C
    user interrupt at
    bpt := S.orbit[1];
     called from
    SiftedPermutation( S, (g * rep) ^ -1 ) called from
    StabChainStrong( S.stabilizer, [ sch ], options ); called from
    StabChainStrong( S.stabilizer, [ sch ], options ); called from
    StabChainStrong( S, GeneratorsOfGroup( G ), options ); called from
    StabChainOp( G, rec(
         ) ) called from
    ...
    Entering break read-eval-print loop ...
    you can 'quit;' to quit to outer loop, or
    you can 'return;' to continue
    brk> Where(2);
     called from
    SiftedPermutation( S, (g * rep) ^ -1 ) called from
    StabChainStrong( S.stabilizer, [ sch ], options ); called from
    ...

Note that the variables displayed even in the first line of the `Where` list (after the `called from` line) may be already one environment level higher and `DownEnv` (6.5-1) may be necessary to access them.

At the moment this backtrace does not work from within compiled code (this includes the method selection which by default is compiled into the kernel). If this creates problems for debugging, call GAP with the `-M` option (see 3.1) to avoid loading compiled code.

(Function calls to `Info` (7.4-6) and methods installed for binary operations are handled in a special way. In rare circumstances it is possible therefore that they do not show up in a `Where` log but the log refers to the last proper function call that happened before.)

The command line option `-T` to GAP disables the break loop. This is mainly intended for testing purposes and for special applications. If this option is given then errors simply cause GAP to return to the main loop.

#### 6.5 Variable Access in a Break Loop

In a break loop access to variables of the current break level and higher levels is possible, but if the same variable name is used for different objects or if a function calls itself recursively, of course only the variable at the lowest level can be accessed.

##### 6.5-1 DownEnv and UpEnv

`‣ DownEnv`( nr ) | ( function )

`‣ UpEnv`( nr ) | ( function )

`DownEnv` moves down nr steps in the environment and allows one to inspect variables on this level; if nr is negative it steps up in the environment again; nr defaults to 1 if not given. `UpEnv` acts similarly to `DownEnv` but in the reverse direction (the mnemonic rule to remember the difference between `DownEnv` and `UpEnv` is the order in which commands on the execution stack are displayed by `Where` (6.4-5)).

    gap> OnBreak := function() Where(0); end;; # eliminate back-tracing on
    gap>                                       # entry to break loop
    gap> test:= function( n )
    >    if n > 3 then Error( "!\n" ); fi; test( n+1 ); end;;
    gap> test( 1 );
    Error, !
    Entering break read-eval-print loop ...
    you can 'quit;' to quit to outer loop, or
    you can 'return;' to continue
    brk> Where();
     called from
    test( n + 1 ); called from
    test( n + 1 ); called from
    test( n + 1 ); called from
    <function>( <arguments> ) called from read-eval-loop
    brk> n;
    4
    brk> DownEnv();
    brk> n;
    3
    brk> Where();
     called from
    test( n + 1 ); called from
    test( n + 1 ); called from
    <function>( <arguments> ) called from read-eval-loop
    brk> DownEnv( 2 );
    brk> n;
    1
    brk> Where();
     called from
    <function>( <arguments> ) called from read-eval-loop
    brk> DownEnv( -2 );
    brk> n;
    3
    brk> quit;
    gap> OnBreak := Where;; # restore OnBreak to its default value

Note that the change of the environment caused by `DownEnv` only affects variable access in the break loop. If you use `return` to continue a calculation GAP automatically jumps to the right environment level again.

Note also that search for variables looks first in the chain of outer functions which enclosed the definition of a currently executing function, before it looks at the chain of calling functions which led to the current invocation of the function.

    gap> foo := function()
    > local x; x := 1;
    > return function() local y; y := x*x; Error("!!\n"); end;
    > end;
    function(  ) ... end
    gap> bar := foo();
    function(  ) ... end
    gap> fun := function() local x; x := 3; bar(); end;
    function(  ) ... end
    gap> fun();
    Error, !!
     called from
    bar(  ); called from
    <function>( <arguments> ) called from read-eval-loop
    Entering break read-eval-print loop ...
    you can 'quit;' to quit to outer loop, or
    you can 'return;' to continue
    brk> x;
    1
    brk> DownEnv(1);
    brk> x;
    3

Here the `x` of `foo` which contained the definition of `bar` is found before that of `fun` which caused its execution. Using `DownEnv` we can access the `x` from `fun`.

#### 6.6 Error and ErrorCount

##### 6.6-1 Error

`‣ Error`( messages, ... ) | ( function )

`Error` signals an error from within a function. First the messages messages are printed, this is done exactly as if `Print` (6.3-4) (see 6.3) were called with these arguments. Then a break loop (see 6.4) is entered, unless the standard error output is not connected to a terminal. You can leave this break loop with `return;` to continue execution with the statement following the call to `Error`. `ErrorNoReturn` (6.6-2) operates identically to `Error`, except it does not allow using `return;` to continue execution.

##### 6.6-2 ErrorNoReturn

`‣ ErrorNoReturn`( messages, ... ) | ( function )

`ErrorNoReturn` signals an error from within a function. First the messages messages are printed, this is done exactly as if `Print` (6.3-4) (see 6.3) were called with these arguments. Then a break loop (see 6.4) is entered, unless the standard error output is not connected to a terminal. This break loop can only be exited with `quit;`. The function differs from `Error` (6.6-1) by not allowing execution to continue.

##### 6.6-3 ErrorCount

`‣ ErrorCount`( ) | ( function )

`ErrorCount` returns a count of the number of errors (including user interruptions) which have occurred in the GAP session so far. The count is incremented by each error, even if GAP was started with the `-T` option to disable the break loop.

#### 6.7 Leaving GAP

The normal way to terminate a GAP session is to enter either `quit;` (note the semicolon) or an end-of-file character (usually Ctrl-D) at the `gap>` prompt in the main read eval print loop.

##### 6.7-1 QUIT

`‣ QUIT` | ( global variable )

An emergency way to leave GAP is to enter `QUIT` at any `gap>` or `brk>` or `brk_nn>` prompt.

##### 6.7-2 GapExitCode

`‣ GapExitCode`( [ret] ) | ( function )

`GapExitCode` sets the exit value which is returned to the operating system (or parent process) when GAP exits. This may be an integer in the range [-128..127] (other values are reduced modulo 256), or a boolean. `true` corresponds to the return value 0, which by convention is treated as "success". `false` corresponds to the return value 1, which by convention is treated as "failure". The exit value is not changed if no argument is given.

The previous exit code is returned.

##### 6.7-3 QuitGap

`‣ QuitGap`( [ret] ) | ( function )

`QuitGap` acts similarly to the keyword `QUIT`, except `QUIT` cannot be called from a function. It exits GAP cleanly, calling any function installed using `InstallAtExit` (6.7-5). The optional argument ret will be passed to `GapExitCode` (6.7-2).

##### 6.7-4 ForceQuitGap

`‣ ForceQuitGap`( [ret] ) | ( function )

`ForceQuitGap` is similar to `QuitGap` (6.7-3), except it ignores any functions installed with `InstallAtExit` (6.7-5), or any other functions normally run at GAP exit, such as flushing any partially outputted lines to both the screen and files, and exits GAP immediately. The optional argument ret will be passed to `GapExitCode` (6.7-2).

##### 6.7-5 InstallAtExit

`‣ InstallAtExit`( func ) | ( function )

`‣ QUITTING` | ( global variable )

Before actually terminating, GAP will call (with no arguments) all of the functions that have been installed using `InstallAtExit`. These typically perform tasks such as cleaning up temporary files created during the session, and closing open files. If an error occurs during the execution of one of these functions, that function is simply abandoned, no break loop is entered.

    gap> InstallAtExit(function() Print("bye\n"); end);
    gap> quit;
    bye

During execution of these functions, the global variable `QUITTING` will be set to `true` if GAP is exiting because the user typed `QUIT` and `false` otherwise. Since `QUIT` is considered as an emergency measure, different action may be appropriate.

##### 6.7-6 SaveOnExitFile

`‣ SaveOnExitFile` | ( global variable )

If, when GAP is exiting due to a `quit` or end-of-file (i.e. not due to a `QUIT`) the variable `SaveOnExitFile` is bound to a string value, then the system will try to save the GAP workspace to that file, see `SaveWorkspace` (3.3-1).

#### 6.8 Line Editing

In most installations GAP will be compiled to use the Gnu readline library (see the line `Libs used:` on GAP startup). In that case skip to the next section 6.9. (The line editing commands described in the rest of this section were available in previous versions of GAP, they will work almost the same in the standard configuration of the Gnu readline library.)

GAP allows one you to edit the current input line with a number of editing commands. Those commands are accessible either as control keys or as escape keys. You enter a control key by pressing the Ctrl key, and, while still holding the Ctrl key down, hitting another key `key`. You enter an escape key by hitting Esc and then hitting another key `key`. Below we denote control keys by Ctrl-`key` and escape keys by Esc-`key`. The case of `key` does not matter, i.e., Ctrl-A and Ctrl-a are equivalent.

Normally, line editing will be enabled if the input is connected to a terminal. Line editing can be enabled or disabled using the command line options `-f` and `-n` respectively (see 3.1), however this is a machine dependent feature of GAP.

Typing Ctrl-key or Esc-key for characters not mentioned below always inserts Ctrl-`key` resp. Esc-`key` at the current cursor position.

The first few commands allow you to move the cursor on the current line.

Ctrl-A

  move the cursor to the beginning of the line.

Esc-B

  move the cursor to the beginning of the previous word.

Ctrl-B

  move the cursor backward one character.

Ctrl-F

  move the cursor forward one character.

Esc-F

  move the cursor to the end of the next word.

Ctrl-E

  move the cursor to the end of the line.

The next commands delete or kill text. The last killed text can be reinserted, possibly at a different position, with the yank command Ctrl-Y.

Ctrl-H or del

  delete the character left of the cursor.

Ctrl-D

  delete the character under the cursor.

Ctrl-K

  kill up to the end of the line.

Esc-D

  kill forward to the end of the next word.

Esc-del

  kill backward to the beginning of the last word.

Ctrl-X

  kill entire input line, and discard all pending input.

Ctrl-Y

  insert (yank) a just killed text.

The next commands allow you to change the input.

Ctrl-T

  exchange (twiddle) current and previous character.

Esc-U

  uppercase next word.

Esc-L

  lowercase next word.

Esc-C

  capitalize next word.

The Tab character, which is in fact the control key Ctrl-I, looks at the characters before the cursor, interprets them as the beginning of an identifier and tries to complete this identifier. If there is more than one possible completion, it completes to the longest common prefix of all those completions. If the characters to the left of the cursor are already the longest common prefix of all completions hitting Tab a second time will display all possible completions.

tab

  complete the identifier before the cursor.

The next commands allow you to fetch previous lines, e.g., to correct typos, etc.

Ctrl-L

  insert last input line before current character.

Ctrl-P

  redisplay the last input line, another Ctrl-P will redisplay the line before that, etc. If the cursor is not in the first column only the lines starting with the string to the left of the cursor are taken.

Ctrl-N

  Like Ctrl-P but goes the other way round through the history.

Esc-<

  goes to the beginning of the history.

Esc->

  goes to the end of the history.

Ctrl-O

  accepts this line and perform a Ctrl-N.

Finally there are a few miscellaneous commands.

Ctrl-V

  enter next character literally, i.e., enter it even if it is one of the control keys.

Ctrl-U

  execute the next line editing command 4 times.

Esc-`num`

  execute the next line editing command `num` times.

Esc-Ctrl-L

  redisplay input line.

The four arrow keys (cursor keys) can be used instead of Ctrl-B, Ctrl-F, Ctrl-P, and Ctrl-N, respectively.

#### 6.9 Editing using the `readline` library

The descriptions in this section are valid only if your GAP installation uses the `readline` library for command line editing. You can check by `IsBound(GAPInfo.UseReadline);` if this is the case.

You can use all the features of `readline`, as for example explained in https://tiswww.case.edu/php/chet/readline/rluserman.html. Therefore the command line editing in GAP is similar to the `bash` shell and many other programs. On a Unix/Linux system you may also have a manpage, try `man readline`.

Compared to the command line editing which was used in GAP up to version 4.4 (or compared to not using the `readline` library) using `readline` has several advantages:

- Most keys still do the same as explained in 6.8 (in the default configuration).

- There are many additional commands, e.g. undoing (Ctrl-_, keyboard macros (Ctrl-x(, Ctrl-x) and Ctrl-xe), file name completion (hit Esc two or four times), showing matching parentheses, `vi`-style key bindings, deleting and yanking text, ...

- Lines which are longer than a physical terminal row can be edited more conveniently.

- Arbitrary unicode characters can be typed into string literals.

- The key bindings can be configured, either via your `~/.inputrc` file or by GAP commands, see 6.9-1.

- The command line history can be saved to and read from a file, see 6.9-2.

- Adventurous users can even implement completely new command line editing functions on GAP level, see 6.9-4.

##### 6.9-1 Readline customization

You can use your readline init file (by default `~/.inputrc` on Unix/Linux) to customize key bindings. If you want settings be used only within GAP you can write them between lines containing `$if GAP` and `$endif`. For a detailed documentation of the available settings and functions see here.

    $if GAP
      set blink-matching-paren on
      "\C-x\C-o": dump-functions
      "\ep": kill-region
    $endif

Alternatively, from within GAP the command `ReadlineInitLine(line);` can be used, where line is a string containing a line as in the init file.

Caveat: GAP overwrites the following keys (after reading the `~/.inputrc` file): `\C-g`, `\C-i`, `\C-n`, `\C-o`, `\C-p`, `\C-r`, `\C-\`, `\e<`, `\e>`, `Up`, `Down`, `TAB`, `Space`, `PageUp`, `PageDown`. So, do not redefine these in your `~/.inputrc`.

Note that after pressing Ctrl-v the next special character is input verbatim. This is very useful to bind keys or key sequences. For example, binding the function key F3 to the command `kill-whole-line` by using the sequence Ctrl-v F3 looks on many terminals like this: `ReadlineInitLine("\"^[OR\":kill-whole-line");`. (You can get the line back later with Ctrl-y.)

The Ctrl-g key can be used to type any unicode character by its code point. The number of the character can either be given as a count, or if the count is one the input characters before the cursor are taken (as decimal number or as hex number which starts with `0x`. For example, the double stroke character ℤ can be input by any of the three key sequences Esc 8484 Ctrl-g, 8484 Ctrl-g or 0x2124 Ctrl-g.

Some terminals bind the Ctrl-s and Ctrl-q keys to stop and restart terminal output. Furthermore, sometimes Ctrl-\ quits a program. To disable this behaviour (and maybe use these keys for command line editing) you can use `Exec("stty stop undef; stty start undef; stty quit undef");` in your GAP session or your `gaprc` file (see 3.2).

##### 6.9-2 The command line history

GAP can save your input lines for later reuse. The keys Ctrl-p (or Up), Ctrl-n (or Down), ESC< and ESC> work as documented in 6.8, that is they scroll backward and forward in the history or go to its beginning or end. Also, Ctrl-o works as documented, it is useful for repeating a sequence of previous lines. (But Ctrl-l clears the screen as in other programs.)

The command line history can be used across several instances of GAP via the following two commands.

##### 6.9-3 SaveCommandLineHistory

`‣ SaveCommandLineHistory`( [fname][,] [app] ) | ( function )

Returns: `fail` or number of saved lines

`‣ ReadCommandLineHistory`( [fname][,] [app] ) | ( function )

Returns: `fail` or number of added lines

The first command saves the lines in the command line history to the file given by the string fname. The default for fname is `history` in the user's GAP root path `GAPInfo.UserGapRoot` or `"~/.gap_hist"` if this directory does not exist. If the optional argument app is `true` then the lines are appended to that file otherwise the file is overwritten.

The second command is the converse, it reads the lines from file fname. If the optional argument app is true the lines are appended to the history, else it prepends them.

By default, the command line history stores up to 1000 input lines. command line history. This number may be restricted or enlarged via via `SetUserPreference("HistoryMaxLines", num);` which may be set to a non negative number `num` to store up to `num` input lines or to `infinity` to store arbitrarily many lines. An automatic storing and restoring of the command line history can be configured via `SetUserPreference("SaveAndRestoreHistory", true);`.

Note that these functions are only available if your GAP is configured to use the `readline` library.

##### 6.9-4 Writing your own command line editing functions

It is possible to write new command line editing functions in GAP as follows.

The functions have one argument l which is a list with five entries of the form `[count, key, line, cursorpos, markpos]` where `count` and `key` are the last pressed key and its count (these are not so useful here because users probably do not want to overwrite the binding of a single key), then `line` is a string containing the line typed so far, `cursorpos` is the current position of the cursor (point), and `markpos` the current position of the mark.

The result of such a function must be a list which can have various forms:

`[str]`

  with a string `str`. In this case the text `str` is inserted at the cursor position.

`[kill, begin, end]`

  where `kill` is `true` or `false` and `begin` and `end` are positions on the input line. This removes the text from the lower position to before the higher position. If `kill` is `true` the text is killed, i.e. put in the kill ring for later yanking.

`[begin, end, str]`

  where `begin` and `end` are positions on the input line and `str` is a string. Then the text from position `begin` to before `end` is substituted by `str`.

`[1, lstr]`

  where `lstr` is a list of strings. Then these strings are displayed like a list of possible completions. The input line is not changed.

`[2, chars]`

  where `chars` is a string. The characters from `chars` are used as the next characters from the input. (At most 512 characters are possible.)

`[100]`

  This rings the bell as configured in the terminal.

In the first three cases the result list can contain a position as a further entry, this becomes the new cursor position. Or it can contain two positions as further entries, these become the new cursor position and the new position of the mark.

Such a function can be installed as a macro for `readline` via `InstallReadlineMacro(name, fun);` where `name` is a string used as name of the macro and `fun` is a function as above. This macro can be called by a key sequence which is returned by `InvocationReadlineMacro(name);`.

As an example we define a function which puts double quotes around the word under or before the cursor position. The space character, the characters in `"(,)"`, and the beginning and end of the line are considered as word boundaries. The function is then installed as a macro and bound to the key sequence Esc Q.

    gap> EditAddQuotes := function(l)
    >   local str, pos, i, j, new;
    >   str := l[3];
    >   pos := l[4];
    >   i := pos;
    >   while i > 1 and (not str[i-1] in ",( ") do
    >     i := i-1;
    >   od;
    >   j := pos;
    >   while IsBound(str[j]) and not str[j] in ",) " do
    >     j := j+1;
    >   od;
    >   new := "\"";
    >   Append(new, str{[i..j-1]});
    >   Append(new, "\"");
    >   return [i, j, new];
    > end;;
    gap> InstallReadlineMacro("addquotes", EditAddQuotes);
    gap> invl := InvocationReadlineMacro("addquotes");;
    gap> ReadlineInitLine(Concatenation("\"\\eQ\":\"",invl,"\""));;

#### 6.10 Editing Files

In most cases, it is preferable to create longer input (in particular GAP programs) separately in an editor, and to read in the result via `Read` (9.7-1). Note that `Read` (9.7-1) by default reads from the directory in which GAP was started (respectively under Windows the directory containing the GAP binary), so you might have to give an absolute path to the file.

If you cannot create several windows, the `Edit` (6.10-1) command may be used to leave GAP, start an editor, and read in the edited file automatically.

##### 6.10-1 Edit

`‣ Edit`( filename ) | ( function )

`Edit` starts an editor with the file whose filename is given by the string filename, and reads the file back into GAP when you exit the editor again.

GAP will call your preferred editor if you call `SetUserPreference("Editor", path);` where path is the path to your editor, e.g., `/usr/bin/vim`. On Windows you can use `edit.com`.

Under macOS, you should use `SetUserPreference("Editor", "open");`, this will open the file in the default editor. If you call `SetUserPreference("EditorOptions", ["-t"]);`, the file will open in `TextEdit`, and `SetUserPreference("EditorOptions", ["-a", "<appl>"]);` will open the file using the application `<appl>`.

This can for example be done in your `gap.ini` file, see Section 3.2-1.

#### 6.11 Editor Support

In the `etc` subdirectory of the GAP installation we provide some setup files for the editor `vim`.

`vim` is a powerful editor that understands the basic `vi` commands but provides much more functionality. You can find more information about it (and download it) from https://www.vim.org.

To get support for GAP syntax in vim, create in your home directory a directory `.vim` with subdirectories `.vim/syntax` and `.vim/indent` (If you are not using Unix, refer to the `vim` documentation on where to place syntax files). Then copy the file `etc/vim/gap.vim` to `.vim/syntax/gap.vim` and the file `etc/vim/gap_indent.vim` to `.vim/indent/gap.vim`.

Then edit the `.vimrc` file in your home directory. Add lines as in the following example:

    if has("syntax")
      syntax on             " Default to no syntax highlighting
    endif

    " For GAP files
    augroup gap
      " Remove all gap autocommands
      au!
    autocmd BufRead,BufNewFile *.g,*.gi,*.gd set filetype=gap comments=s:##\ \ ,m:##\ \ ,e:##\ \ b:#

    " I'm using the external program `par' for formatting comment lines starting
    " with `##  '. Include these lines only when you have par installed.
      autocmd BufRead,BufNewFile *.g,*.gi,*.gd set formatprg="par w76p4s0j"
      autocmd BufWritePost,FileWritePost *.g,*.gi,*.gd set formatprg="par w76p0s0j"
    augroup END

See the headers of the two mentioned files for additional comments and adjust details according to your personal taste. Send comments and suggestions to support@gap-system.org.

Users of `emacs`/`xemacs` may wish to take a look at the major-mode for editing GAP files by Ivan Andrus.

#### 6.12 Changing the Screen Size

##### 6.12-1 SizeScreen

`‣ SizeScreen`( [sz] ) | ( function )

Called with no arguments, `SizeScreen` returns the size of the screen as a list with two entries. The first is the length of each line, the second is the number of lines.

Called with one argument that is a list sz, `SizeScreen` sets the size of the screen; The first entry of sz, if bound, is the length of each line, and the second entry of sz, if bound, is the number of lines. The values for unbound entries of sz are left unaffected. The function returns the new values.

Note that those parameters can also be set with the command line options `-x` for the line length and `-y` for the number of lines (see Section 3.1).

To check/change whether line breaking occurs for files and streams see `PrintFormattingStatus` (10.4-8) and `SetPrintFormattingStatus` (10.4-8).

The line length must be between 20 and 4096 characters (inclusive) and the number of lines must be at least 10. Values outside this range will be adjusted to the nearest endpoint of the range.

#### 6.13 Teaching Mode

When using GAP in the context of (undergraduate) teaching it is often desirable to simplify some of the system output and functionality defaults (potentially at the cost of making the printing of objects more expensive). This can be achieved by turning on a teaching mode:

##### 6.13-1 TeachingMode

`‣ TeachingMode`( [switch] ) | ( function )

When called with a boolean argument switch, this function will turn teaching mode respectively on or off.

    gap> a:=Z(11)^3;
    Z(11)^3
    gap> TeachingMode(true);
    #I  Teaching mode is turned ON
    gap> a;
    ZmodnZObj(8,11)
    gap> TeachingMode(false);
    #I  Teaching mode is turned OFF
    gap> a;
    Z(11)^3

At the moment, teaching mode changes the following things

Prime Field Elements

  Elements of fields of prime order are printed as `ZmodnZObj` (14.5-3) instead as power of a primitive root.

Quadratic Irrationalities

  Elements of a quadratic extension of the rationals are printed using the square root `ER` (18.4-2) instead of using roots of unity.

Creation of some small groups

  The group creator functions `CyclicGroup` (50.1-2), `AbelianGroup` (50.1-3), `ElementaryAbelianGroup` (50.1-4), and `DihedralGroup` (50.1-6) create by default (if no other representation is specified) not a pc group, but a finitely presented group, which makes the generators easier to interpret.

[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