6 Main Loop and Break Loop

View shows the objects obj1, obj2... etc. in a short form on the standard output. 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.

Also Print shows the objects obj1, obj2... etc. on the standard output. The difference compared to View 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 );
[ Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0 ]gap> 

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 Strings and Characters). Some characters preceded by a backslash, such as \n, are processed specially (see chapter Special Characters). PrintTo can be used to print to a file (see PrintTo).

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 );
<pc group of size 12 with 3 generators>gap> 

The functions View and Print 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 Method Selection in the Programmer's Manual). The only exceptions are strings (see Chapter Strings and Characters), for which the default PrintObj and ViewObj methods as well as the function View print also the enclosing doublequotes, whereas Print 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 it. If one wants to supply a ``short form'' for View, one can install additionally a method for ViewObj.

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 will use instead of the default used by Print, via SetName (see SetName). Also, Name (see Name) returns the string previously assigned to the object for printing, via SetName. 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"

6.3 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 Main Loop). 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.

The first 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 Command Line Options). 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 Leaving GAP).

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 quitting a break loop generally leaves the options stack with options you no longer want. The function ResetOptionsStack (see ResetOptionsStack) removes all options on the options stack, and this is the sole intended purpose of this function.

The other way is to return from a break loop. To do this you type return; or return expr;. 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) or you may have to return a value (by typing: return value;) 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> 

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 (see Where).

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 Options Stack), a quit; will also cause the options stack to be reset and an Info-ed warning stating this is emitted at InfoWarning level 1 (see Chapter Info functions).

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

Also, note that one can achieve the effect of changing OnBreak locally. As mentioned above, the default value of OnBreak is Where. Thus, a call to Error (see Error) generally gives a trace back up to five levels of calling functions. Conceivably, we might like to have a function like Error 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 a special variable that GAP   
>                                      # knows to treat as a list of arg'ts
>      local SavedOnBreak, ENTBOnBreak;
>      SavedOnBreak := OnBreak;        # save the 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 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;;

When a break loop is entered by a call to Error (see Error) the message after the ``Entering break read-eval-print loop ...'' line is produced by the function OnBreakMessage, which just like OnBreak (see OnBreak) 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

With OnBreak still set away from its default value, calling Error 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) can be adapted to achieve this. The function CosetTableFromGensAndRels (see CosetTableFromGensAndRels) is an example in the GAP code where the idea is actually used.

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 (see OnBreak) has been set back to its default value.)

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 (see DownEnv) 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 Advanced Features of GAP) to avoid loading compiled code.

(Function calls to Info 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.4 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.

DownEnv moves up nr steps in the environment and allows one to inspect variables on this level; if nr is negative it steps down in the environment again; nr defaults to 1 if not given. UpEnv acts similarly to DownEnv but in the reverse direction. (The names of DownEnv and UpEnv are the wrong way 'round; I guess it all depends on which direction defines is ``up'' -- just use DownEnv and get used to that.)

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

Error signals an error from within a function. First the messages messages are printed, this is done exactly as if Print (see View and Print) were called with these arguments. Then a break loop (see Break Loops) 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.

6.6 ErrorCount

ErrorCount returns a count of the number of errors (including user interruptions) which have occurred in the GAP session so far. This count is reduced modulo 2²⁸ on 32 bit systems, 2⁶⁰ on 64 bit systems. 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.

An emergency way to leave GAP is to enter

at any gap> or brk> or brk_nn> prompt.

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.

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

6.8 Line Editing

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 Command Line Options), 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. This history is limited to about 8000 characters.

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 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. Note that Read by default reads from the directory in which GAP was started (respectively under Windows the directory containing the GAP binary), so you might hav eto give an absolute path to the file.

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

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. You should set the GAP variable EDITOR to the name of the editor that you usually use, e.g., /usr/ucb/vi. This can for example be done in your .gaprc file (see the sections on operating system dependent features in Chapter Installing GAP).

6.10 Editor Support

In the etc subdirectory of the GAP installation we provide some setup files for the editors vim and emacs/xemacs.

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 http://www.vim.org.

To get support for GAP syntax in vim, create in your home directory a directory .vim and a subdirectory .vim/indent (If you are not using Unix, refer to the vim documentation on where to place syntax files). Then copy the file etc/gap.vim in this.vim directory and copy the file etc/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 highlightning 
endif

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

" I'm using the external program `par' for formating 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. Adjust details according to your personal taste.

Setup files for (x)emacs are contained in the etc/emacs subdirectory.

6.11 SizeScreen

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.

With one argument that is a list, SizeScreen sets the size of the screen; x is the length of each line, y is the number of lines. Either value x or y may be missing (i.e. left unbound), to leave this value unaffected. It returns the new values. Note that those parameters can also be set with the command line options -x x and -y y (see Section Command line options).

To check/change whether line breaking occurs for files and streams see PrintFormattingStatus and SetPrintFormattingStatus.

The screen width must be between 20 and 256 characters (inclusive) and the depth at least 10 lines. Values outside this range will be adjusted to the nearest endpoint of the range.

[Top] [Up] [Previous] [Next] [Index]

GAP 4 manual
March 2006