This chapter describes the interactive environment in which you use GAP3.
The first sections describe the main read eval print loop and the break loop (see Main Loop, Break Loops, and Error).
The next section describes the commands you can use to edit the current input line (see Line Editing).
The next sections describe the GAP3 help system (see Help, Reading Sections, Format of Sections, Browsing through the Sections, Redisplaying a Section, Abbreviating Section Names, Help Index).
The next sections describe the input and output functions (see Read, ReadLib, Print, PrintTo, AppendTo, LogTo, LogInputTo, and SizeScreen).
The next sections describe the functions that allow you to collect statistics about a computation (see Runtime, Profile).
The last sections describe the functions that allow you to execute other programs as subprocesses from within GAP3 (see Exec and Edit).
The normal interaction with GAP3 happens in the so--called read eval print loop. This means that you type an input, GAP3 first reads it, evaluates it, and prints the result. The exact sequence is as follows.
To show you that it is ready to accept your input, GAP3 displays the
prompt gap> . When you see this, you know that GAP3 is waiting for
your input.
Note that every statement must be terminated by a semicolon. You must also enter return before GAP3 starts to read and evaluate your input. Because GAP3 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 GAP3 take a look at it (see Line Editing). 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, GAP3 will display the
partial prompt > . When you see this, you know that GAP3 is
waiting for the rest of the statement. This happens also when you forget
the semicolon ; that terminates every GAP3 statement.
When you enter return, GAP3 first checks your input to see if it is syntactically correct (see chapter The Programming Language for the definition of syntactically correct). If it is not, GAP3 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), 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 GAP3 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 GAP3 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 GAP3 forgave you and is now ready to
accept your next -- hopefully correct -- input.
If your input is syntactically correct, GAP3 evaluates or executes it, i.e., performs the required computations (see chapter The Programming Language for the definition of the evaluation).
If you do not see a prompt, you know that GAP3 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 GAP3 until GAP3 has completed the ongoing computation.
When GAP3 is ready it will usually print 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 printed.
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 the printing of the result.
If you have entered several statements on a single line GAP3 will first read, evaluate, and print the first one, then read evaluate, and print the second one, and so on. This means that the second statement will not even be checked for syntactical correctness until GAP3 has completed the first computation.
After the result has been printed GAP3 will display another prompt, and wait for your next input. And the whole process starts all over again. Note that a new prompt will only be printed after GAP3 has read, evaluated, and printed the last statement if you have entered several statements on a single line.
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. This is an
integer that holds the number of milliseconds.
When an error has occurred or when you interrupt GAP3, usually by
hitting ctr-C, GAP3 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, GAP3 reads them, evaluates them, and prints 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.
There are two ways to leave a break loop.
The first is to quit the break loop and continue in the main loop. To do
this you enter quit; or hit the eof (end of file) character,
which is usually ctr-D. In this case control returns to the main
loop, and you can enter new statements.
The other way is to return from a break loop. To do this you enter
return; or return expr;. If the break loop was entered because you
interrupted GAP3, then you can continue by entering return;. If the
break loop was entered due to an error, you usually have to return a
value to continue the computation. For example, if the break loop was
entered because a variable had no assigned value, you must return the
value that this variable should have to continue the computation.
Error( messages... )
Error signals an error. First the messages messages are printed,
this is done exactly as if Print (see 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.
GAP3 allows 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 ctr key, and,
while still holding the ctr 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 ctr-key and escape keys by
esc-key. The case of key does not matter, i.e., ctr-A and
ctr-a are equivalent.
Characters not mentioned below always insert themselves at the current cursor position.
The first few commands allow you to move the cursor on the current line.
ctr-A move the cursor to the beginning of the line.
esc-B move the cursor to the beginning of the previous word.
ctr-B move the cursor backward one character.
ctr-F move the cursor forward one character.
esc-F move the cursor to the end of the next word.
ctr-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.
ctr-H or del delete the character left of the cursor.
ctr-D delete the character under the cursor.
ctr-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.
ctr-X kill entire input line, and discard all pending input.
ctr-Y insert (yank) a just killed text.
The next commands allow you to change the input.
ctr-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 ctr-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.
ctr-L insert last input line before current character.
ctr-P redisplay the last input line, another ctr-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.
ctr-N Like ctr-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.
ctr-O accepts this line and perform a ctr-N.
Finally there are a few miscellaneous commands.
ctr-V enter next character literally, i.e., enter it even if it
is one of the control keys.
ctr-U execute the next command 4 times.
esc-num execute the next command num times.
esc-ctr-L repaint input line.
This section describes together with the following sections the GAP3 help system. The help system lets you read the manual interactively.
?section
The help command ? displays the section with the name section on the
screen. For example ?Help will display this section on the screen.
You should not type in the single quotes, they are only used in help
sections to delimit text that you should enter into GAP3 or that GAP3
prints in response. When the whole section has been displayed the normal
GAP3 prompt gap> is shown and normal GAP3 interaction resumes.
The section Reading Sections tells you what actions you can perform
while you are reading a section. You command GAP3 to display this
section by entering ?Reading Sections, without quotes. The section
Format of Sections describes the format of sections and the conventions
used, Browsing through the Sections lists the commands you use to flip
through sections, Redisplaying a Section describes how to read a
section again, Abbreviating Section Names tells you how to avoid typing
the long section names, and Help Index describes the index command.
If the section is longer than 24 lines GAP3 stops after 24 lines and displays
-- <space> for more --
If you press space GAP3 displays the next 24 lines of the section and
then stops again. This goes on until the whole section has been
displayed, at which point GAP3 will return immediately to the main
GAP3 loop. Pressing f has the same effect as space.
You can also press b or the key labeled del which will scroll back to
the previous 24 lines of the section. If you press b or del when
GAP3 is displaying the top of a section GAP3 will ring the bell.
You can also press q to quit and return immediately back to the main
GAP3 loop without reading the rest of the section.
Actually the 24 is only a default, if you have a larger screen that can
display more lines of text you may want to tell this to GAP3 with the
-y rows option when you start GAP3.
This section describes the format of sections when they are displayed on the screen and the special conventions used.
As you can see GAP3 indents sections 4 spaces and prints a header line containing the name of the section on the left and the name of the chapter on the right.
<text>
Text enclosed in angle brackets is used for arguments in the descriptions
of functions and for other placeholders. It means that you should not
actually enter this text into GAP3 but replace it by an appropriate
text depending on what you want to do. For example when we write that
you should enter ?section to see the section with the name section,
section servers as a placeholder, indicating that you can enter the
name of the section that you want to see at this place. In the printed
manual such text is printed in italics.
'text'
Text enclosed in single quotes is used for names of variables and
functions and other text that you may actually enter into your computer
and see on your screen. The text enclosed in single quotes may contain
placeholders enclosed in angle brackets as described above. For example
when the help text for IsPrime says that the form of the call is
'IsPrime( <n> )' this means that you should actually enter the IsPrime(
and ), without the quotes, but replace the n with the number (or
expression) that you want to test. In the printed manual this text is
printed in a monospaced (all characters have the same width) typewriter
font.
"text"
Text enclosed in double quotes is used for cross references to other parts of the manual. So the text inside the double quotes is the name of another section of the manual. This is used to direct you to other sections that describe a topic or a function used in this section. So for example Abbreviating Section Names is a cross reference to the next section. In the printed manual the text is replaced by the number of the section.
_ and ^
In mathematical formulas the underscore and the caret are used to denote
subscription and superscription. Ordinarily they apply only to the very
next character following, unless a whole expression enclosed in
parentheses follows. So for example x_1^(i+1) denotes the variable x
with subscript 1 raised to the i+1 power. In the printed manual
mathematical formulas are typeset in italics (actually mathitalics) and
subscripts and superscripts are actually lowered and raised.
Longer examples are usually paragraphs of their own that are indented 8
spaces from the left margin, i.e. 4 spaces further than the surrounding
text. Everything on the lines with the prompts gap> and >, except
the prompts themselves of course, is the input you have to type,
everything else is GAP3's response. In the printed manual examples
are also indented 4 spaces and are printed in a monospaced typewriter
font.
gap> ?Format of Sections
Format of Sections ______________________________________ Environment
This section describes the format of sections when they are displayed
on the screen and the special conventions used.
...
3.8 Browsing through the Sections
The help sections are organized like a book into chapters. This should not surprise you, since the same source is used both for the printed manual and the online help. Just as you can flip through the pages of a book there are special commands to browse through the help sections.
?>
?<
The two help commands ?< and ?> correspond to the flipping of pages.
?< takes you to the section preceding the current section and displays
it, and ?> takes you to the section following the current section.
?<<
?>>
?<< is like ?<, only more so. It takes you back to the first
section of the current chapter, which gives an overview of the sections
described in this chapter. If you are already in this section ?<<
takes you to the first section of the previous chapter. ?>> takes you
to the first section of the next chapter.
?-
?+
GAP3 remembers the sections that you have read. ?- takes you to the
one that you have read before the current one, and displays it again.
Further ?- takes you further back in this history. ?+ reverses this
process, i.e., it takes you back to the section that you have read
after the current one. It is important to note, that ?- and ?+ do
not alter the history like the other help commands.
?
The help command ? followed by no section name redisplays the last help
section again. So if you reach the bottom of a long help section and
already forgot what was mentioned at the beginning, or, for example, the
examples do not seem to agree with your interpretation of the
explanations, use ? to read the whole section again from the beginning.
When ? is used before any section has been read GAP3 displays the
section Welcome to GAP.
3.10 Abbreviating Section Names
Upper and lower case in section are not distinguished, so typing either
?Abbreviating Section Names or ?abbreviating section names will show
this very section.
Each word in section may be abbreviated. So instead of typing
?abbreviating section names you may also type ?abb sec nam, or even
?a s n. You must not omit the spaces separating the words. For each
word in the section name you must give at least the first character. As
another example you may type ?oper for int instead of ?operations for
integers, which is especially handy when you can not remember whether it
was operations or operators.
If an abbreviation matches multiple section names a list of all these section names is displayed.
??topic
?? looks up topic in GAP3's index and prints all the index entries
that contain the substring topic. Then you can decide which section is
the one you are actually interested in and request this one.
gap> ??help
help ______________________________________________________ Index
Help
Reading Sections (help!scrolling)
Format of the Sections (help!format)
Browsing through the Sections (help!browsing)
Redisplaying a Section (help!redisplaying)
Abbreviating Section Names (help!abbreviating)
Help Index
gap>
The first thing on each line is the name of the section. If the name of the section matches topic nothing more is printed. Otherwise the index entry that matched topic is printed in parentheses following the section name. For each section only the first matching index entry is printed. The order of the sections corresponds to their order in the GAP3 manual, so that related sections should be adjacent.
Read( filename )
Read reads the input from the file with the filename filename, which
must be a string.
Read first opens the file filename. If the file does not exist, or
if GAP3 can not open it, e.g., because of access restrictions, an error
is signalled.
Then the contents of the file are read and evaluated, but the results are not printed. The reading and printing happens exactly as described for the main loop (see Main Loop).
If an input in the file contains a syntactical error, a message is printed, and the rest of this statement is ignored, but the rest of the file is read.
If a statement in the file causes an error a break loop is entered (see
Break Loops). The input for this break loop is not taken from the
file, but from the input connected to the stderr output of GAP3. If
stderr is not connected to a terminal, no break loop is entered. If
this break loop is left with quit (or ctr-D) the file is closed and
GAP3 does not continue to read from it.
Note that a statement may not begin in one file and end in another, i.e., eof (end of file) is not treated as whitespace, but as a special symbol that must not appear inside any statement.
Note that one file may very well contain a read statement causing another file to be read, before input is again taken from the first file. There is an operating system dependent maximum on the number of files that may be open at once, usually it is 15.
The special file name "*stdin*" denotes the standard input, i.e.,
the stream through which the user enters commands to GAP3. The exact
behaviour of Read( "*stdin*" ) is operating system dependent, but
usually the following happens. If GAP3 was started with no input
redirection, statements are read from the terminal stream until the user
enters the end of file character, which is usually ctr-D. Note that
terminal streams are special, in that they may yield ordinary input
after an end of file. Thus when control returns to the main read eval
print loop the user can continue with GAP3. If GAP3 was started with
an input redirection, statements are read from the current position in
the input file up to the end of the file. When control returns to the
main read eval print loop the input stream will still return end of file,
and GAP3 will terminate. The special file name "*errin*" denotes
the stream connected with the stderr output. This stream is usually
connected to the terminal, even if the standard input was redirected,
unless the standard error stream was also redirected, in which case
opening of "*errin*" fails, and Read will signal an error.
Read is implemented in terms of the function READ, which behaves
exactly like Read, except that READ does not signal an error when it
can not open the file. Instead it returns true or false to indicate
whether opening the file was successful or not.
ReadLib( name )
ReadLib reads input from the library file with the name name.
ReadLib prefixes name with the value of the variable LIBNAME and
appends the string ".g" and calls Read (see Read) with this file
name.
Print( obj1, obj2... )
Print prints the objects obj1, obj2... etc. to the standard output.
The output looks exactly like the printed representation of the objects
printed by the main loop. The exception are strings, which are printed
without the enclosing quotes and a few other transformations (see
Strings and Characters). Note that no space or newline is printed
between the objects. 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
PrintTo( filename, obj1, obj2... )
PrintTo works like Print, except that the output is printed to the
file with the name filename instead of the standard output. This file
must of course be writable by GAP3, otherwise an error is signalled.
Note that PrintTo will overwrite the previous contents of this file if
it already existed. AppendTo can be used to append to a file (see
AppendTo).
The special file name "*stdout*" can be used to print to the
standard output. This is equivalent to a plain Print, except that a
plain Print that is executed while evaluating an argument to a
PrintTo call will also print to the output file opened by the last
PrintTo call, while PrintTo( "*stdout*", obj1, obj2... )
always prints to the standard output. The special file name
"*errout*" can be used to print to the standard error output file,
which is usually connected with the terminal, even if the standard output
was redirected.
There is an operating system dependent maximum to the number of output files that may be open at once, usually this is 14.
AppendTo( filename, obj1, obj2... )
AppendTo works like PrintTo (see PrintTo), except that the output
does not overwrite the previous contents of the file, but is appended to
the file.
LogTo( filename )
LogTo causes the subsequent interaction to be logged to the file with
the name filename, i.e., everything you see on your terminal will also
appear in this file. This file must of course be writable by GAP3,
otherwise an error is signalled. Note that LogTo will overwrite the
previous contents of this file if it already existed.
LogTo()
In this form LogTo stops logging again.
LogInputTo( filename )
LogInputTo causes the subsequent input lines to be logged to the file
with the name filename, i.e., every line you type will also appear in
this file. This file must of course be writable by GAP3, otherwise an
error is signalled. Note that LogInputTo will overwrite the previous
contents of this file if it already existed.
LogInputTo()
In this form LogInputTo stops logging again.
SizeScreen()
In this form 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.
SizeScreen( [ x, y ] )
In this form SizeScreen sets the size of the screen. x is the length
of each line, y is the number of lines. Either value may be missing,
to leave this value unaffected. Note that those parameters can also be
set with the command line options -x x and -y y (see Getting and
Installing GAP).
Runtime()
Runtime returns the time spent by GAP3 in milliseconds as an integer.
This is usually the cpu time, i.e., not the wall clock time. Also time
spent by subprocesses of GAP3 (see Exec) is not counted.
Profile( true )
In this form Profile turns the profiling on. Subsequent computations
will record the time spent by each function and the number of times each
function was called. Old profiling information is cleared.
Profile( false )
In this form Profile turns the profiling off again. Recorded
information is still kept, so you can display it even after turning the
profiling off.
Profile()
In this form Profile displays the collected information in the
following format.
gap> Factors( 10^21+1 );; # make sure that the library is loaded
gap> Profile( true );
gap> Factors( 10^42+1 );
[ 29, 101, 281, 9901, 226549, 121499449, 4458192223320340849 ]
gap> Profile( false );
gap> Profile();
count time percent time/call child function
4 1811 76 452 2324 FactorsRho
18 171 7 9 237 PowerModInt
127 94 3 0 94 GcdInt
41 83 3 2 415 IsPrimeInt
91 59 2 0 59 TraceModQF
511 47 1 0 39 QuoInt
22 23 0 1 23 Jacobi
116 20 0 0 31 log
3 20 0 6 70 SmallestRootInt
1 19 0 19 2370 FactorsInt
26 15 0 0 39 LogInt
4 4 0 1 4 Concatenation
5 4 0 0 20 RootInt
7 0 0 0 0 Add
26 0 0 0 0 Length
13 0 0 0 0 NextPrimeInt
4 0 0 0 0 AddSet
4 0 0 0 0 IsList
4 0 0 0 0 Sort
8 0 0 0 0 Append
2369 100 TOTAL
The last column contains the name of the function. The first column contains the number of times each function was called. The second column contains the time spent in this function. The third column contains the percentage of the total time spent in this function. The fourth column contains the time per call, i.e., the quotient of the second by the first number. The fifth column contains the time spent in this function and all other functions called, directly or indirectly, by this function.
Exec( command )
Exec executes the command given by the string command in the
operating system. How this happens is operating system dependent. Under
UNIX, for example, a new shell is started and command is passed as a
command to this shell.
gap> Exec( "date" );
Fri Dec 13 17:00:29 MET 1991
Edit (see Edit) should be used to call an editor from within GAP3.
Edit( filename )
Edit starts an editor with the file whose filename is given by the
string filename, and reads the file back into GAP3 when you exit the
editor again. You should set the GAP3 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 Getting and Installing GAP).
gap3-jm