%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  introduc.tex              GAP documentation             Thomas Breuer
%W                                                         & Frank Celler
%W                                                     & Martin Schoenert
%W                                                       & Heiko Theissen
%%
%H  @(#)$Id: introduc.tex,v 4.30.2.2 2005/05/05 13:21:18 gap Exp $
%%
%Y  Copyright 1997,  Lehrstuhl D fuer Mathematik,  RWTH Aachen,   Germany
%%
%%  This file contains a tutorial introduction to GAP.
%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{A First Session with GAP}

This tutorial introduces you to  the {\GAP}  system.  It is written  with
users in mind who have just managed to start {\GAP} for the first time on
their computer and want to learn the basic facts  about {\GAP} by playing
around with some instructive  examples. Therefore, this tutorial contains
at many  places several lines of  input  (which you  should type  on your
terminal) followed by the corresponding output  (which {\GAP} produces as
an answer to your input).
\begintt
This ``session protocol'' is indented and printed in typewriter style
(like this paragraph) in this tutorial and should look exactly as it
looks on your text terminal or text window.
\endtt
This is  to encourage you to actually  run through these examples on your
computer. This will support your  feeling for {\GAP}  as a tool, which is
the leading aim of this  tutorial. Do not believe any  statement in it as
long  as you cannot verify  it for your own  version of  {\GAP}. You will
learn to distinguish  between small  deviations of  the behavior of  your
personal {\GAP} from the printed examples and serious nonsense.

Since the printing routines of {\GAP} are in some sense machine dependent
you will for instance encounter a different layout of the printed objects
in different environments.  But the  contents should always be the  same.
In case you encounter serious nonsense  it is highly recommended that you
send a bug report to \Mailto{support@gap-system.org}.

The  examples in this  tutorial should explain  everything you have to
know in order  to be able  to use {\GAP}.   The reference  manual then
gives a more systematic treatment of the various types of objects that
{\GAP} can manipulate.   It   seems desirable neither to    start this
systematic  course  with  the   most   elementary (and  most   boring)
structures, nor to confront you with all the complex data types before
you know how  they are composed from  elementary structures.  For this
reason this tutorial  wants to provide  you with a basic understanding
of {\GAP} objects, on which the reference  manual will then build when
it  explains everything in  detail.   So  after having mastered   this
tutorial, you can immediately plunge into the exciting parts of {\GAP}
and  only read detailed  information about  elementary things (in  the
reference manual) when you really need them.

Each chapter of this tutorial contains an  overview of its sections at
the beginning,  and a section  with references to the reference manual
at the end.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Starting and Leaving GAP}

\atindex{starting GAP}{@starting {\GAP}}
\atindex{leaving GAP}{@leaving {\GAP}}
\indextt{quit}
If the  program is correctly  installed then you usually start {\GAP} by
simply
typing  `gap' at  the  prompt of your   operating system followed by  the
<return> key, sometimes this is also called the <newline> key.
\begintt
$ gap
\endtt
{\GAP} answers your request with its beautiful banner and then it shows
its own prompt `gap>' asking you for further input.
(You can avoid the banner with the command line option `-b';
more command line options are described in
Section~"ref:Command Line Options" in the reference manual.)
\beginexample
gap> 
\endexample
The usual  way to end a  {\GAP} session is  to type `quit;' at the `gap>'
prompt. Do not omit the semicolon!
\begintt
gap> quit;
$ 
\endtt
On some systems you could type  <ctl>-`D' to yield the same effect.
In any situation   {\GAP} is ended by  typing  <ctl>-`C' twice  within  a
second. Here as always, a combination like  <ctl>-`D' means that you have
to press the `D' key while you hold down the <ctl> key.

On some systems (for example the Apple Macintosh) minor changes might be
necessary. This is explained in chapter "ref:Installing GAP" in the reference
manual.

\index{whitespace}
In  most   places *whitespace*  characters   (i.e.  <space>s, <tab>s  and
<return>s) are insignificant for the meaning of {\GAP} input. Identifiers
and keywords must however not contain any whitespace.  On the other hand,
sometimes there  must be  whitespace  around identifiers and keywords  to
separate them from each other and from numbers. We will use whitespace to
format more complicated commands for better readability.

\index{comments}
A *comment* in  {\GAP} starts with the  symbol `\#' and continues to  the
end of the line. Comments are  treated like whitespace  by {\GAP}. We use
comments in   the printed examples  in this  tutorial to  explain certain
lines of input or output.
% These comments will be printed in a normal font for better readability,
% they start with the symbol~\#.

You should be able to reproduce the results of the *examples* of {\GAP}
sessions in this manual, in the following sense.
If you start the {\GAP} session with the two commands
%notest
\beginexample
gap> SizeScreen( [ 80, ] ); LogTo( "logfile1" );
\endexample
(which are used to set the line length to 80 if this isn't already your
default line length and to save a listing of
the session on some file), then choose any chapter and rerun its
examples in one continuous session and in the given order, the {\GAP}
output should look like the output shown in the manual, except for a
few lines of output which we have edited a little bit with respect to
blanks or line breaks in order to improve the readability.  However,
when random processes are involved, you may get different results if
you extract single examples and run them separately.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Loading Source Code from a File}\null

\index{loading source code from a file}
\index{reading source code from a file}
\indextt{Read}
The most convenient way of creating larger pieces of {\GAP} code is to
write them to some text file -- for this purpose you can simply use your
favorite text editor.
You can load such a file into {\GAP} using the `Read' function:
\begintt
gap> Read("../../GAPProgs/Example.g");
\endtt
You can either give the full absolute path name of the source file or
its relative path name from the {\GAP} root directory (the directory
containing `bin/', `doc/', `lib/', etc.).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{The Read Evaluate Print Loop}\null

\atindex{read evaluate print loop}{@read evaluate print loop|indexit}
{\GAP}  is  an   interactive   system.    It  continuously   executes   a
read evaluate print loop.  Each  expression you type  at the  keyboard is
read by {\GAP}, evaluated, and then the result is shown.

The interactive nature of {\GAP} allows you to type  an expression at the
keyboard and see its value immediately.  You can  define a  function  and
apply it to arguments  to  see how  it  works.  You may  even write whole
programs containing lots  of functions and test them without leaving  the
program.

When  your program is large it  will be more  convenient to write it on a
file and then read that file  into {\GAP}. Preparing  your functions in a
file   has  several advantages.  You  can   compose  your functions  more
carefully in a  file (with your favorite  text  editor), you can  correct
errors without retyping  the whole function and you  can keep a  copy for
later use. Moreover you can write lots of comments into the program text,
which are ignored  by {\GAP}, but are   very useful for  human readers of
your program text. {\GAP} treats  input from a  file in the same way that
it treats input from the keyboard. Further details can be found in
section "ref:Read" in the Reference Manual.

A simple calculation with {\GAP} is as easy as one can imagine.  You type
the problem just after the prompt, terminate it with a semicolon and then
pass the problem to the  program with the <return> key.  For  example, to
multiply the difference between 9 and 7 by the sum of 5 and 6, that is to
calculate  $(9 - 7) \* (5 + 6)$, you type exactly this  last sequence  of
symbols followed by `;' and <return>.
\beginexample
gap> (9 - 7) * (5 + 6);
22
gap> 
\endexample
Then {\GAP} echoes   the result 22 on the   next line and shows with  the
prompt  that it is ready  for the  next problem.  Henceforth,  we will no
longer print this additional prompt.

\index{line editing}
If you make a mistake while typing the line,
but *before* typing the final <return>,
you can use the <delete> key (or sometimes <backspace> key)
to delete the last typed character.
You can also move the cursor back and forward in the line with <ctl>-`B'
and <ctl>-`F' and insert or delete characters anywhere in the line.
The line editing commands are fully described
in section~"ref:Line Editing" of the reference manual.

If you did omit the semicolon at the end of  the line but have already
typed  <return>, then {\GAP} has  read  everything you typed, but does
not know  that the command  is  complete.  The program is  waiting for
further  input and indicates  this with  a  partial prompt `>'.   This
problem is solved by simply  typing the missing  semicolon on the next
line  of  input. Then  the result  is printed   and  the normal prompt
returns.
\beginexample
gap> (9 - 7) * (5 + 6)
> ;
22
\endexample
So the input can consist of several lines, and {\GAP} prints a partial
prompt `>' in each input line except the first, until the command is
completed with a semicolon.
({\GAP} may already evaluate part of the input when <return> is typed,
so for long calculations it might take some time until the partial prompt
appears.)
Whenever you see the partial prompt and you cannot decide what {\GAP} is
still  waiting for, then  you have  to type  semicolons  until the normal
prompt returns.
In  every situation the exact meaning of the prompt `gap>' is that the
program is waiting for a new problem.

But even if you  mistyped the command more  seriously, you do not have to
type   it all again. Suppose   you  mistyped or  forgot  the last closing
parenthesis. Then your command is syntactically incorrect and {\GAP} will
notice it, incapable of computing the desired result.
%notest
\beginexample
gap> (9 - 7) * (5 + 6;
Syntax error: ) expected
(9 - 7) * (5 + 6;
                ^
\endexample
\index{line editing}
Instead of the result an error message  occurs indicating the place where
an unexpected  symbol occurred with   an arrow sign  `^'  under it.  As a
computer program  cannot know what your  intentions really were,  this is
only  a hint. But in this  case {\GAP}  is  right by  claiming that there
should be a closing  parenthesis before the  semicolon. Now you  can type
<ctl>-`P' to recover the last line of input. It will be written after the
prompt with the cursor in the first  position. Type <ctl>-`E' to take the
cursor  to the end of   the line, then <ctl>-`B'   to move the cursor one
character back. The cursor is now on the position of the semicolon. Enter
the missing parenthesis by simply typing `)'. Now the line is correct and
may be passed to {\GAP}  by hitting the <return>  key. Note that for this
action it is not necessary to move the cursor  past the last character of
the input line.

Each line  of commands  you  type is sent to    {\GAP} for evaluation  by
pressing <return> regardless of the position of  the cursor in that line.
We will no longer mention the <return> key from now on.

\index{break loops}
Sometimes a syntax error will cause {\GAP} to enter a *break loop*.  This
is indicated by the special prompt `brk>'. If another syntax error occurs
while  {\GAP} is in  a break loop, the prompt  will  change to `brk_02>',
`brk_03>' and so on. You can leave the current break loop and exit to the
next outer one by either typing `quit;' or by hitting <ctl>-`D'.
Eventually {\GAP} will return to its normal state and show its normal
prompt `gap>' again.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Constants and Operators}\null

\index{constants}\index{operators}
In an  expression like `(9  - 7) * (5 +  6)' the constants `5', `6', `7',
and `9' are being composed by the operators `+', `*' and `-' to result in
a new value.

There are  three kinds  of operators in  {\GAP}, arithmetical  operators,
comparison operators, and logical operators.  You  have already seen that
it is possible to form  the sum,  the  difference, and the product of two
integer values.  There are some  more operators applicable to integers in
{\GAP}.   Of  course integers  may  be divided  by  each other,  possibly
resulting in noninteger rational values.
\beginexample
gap> 12345/25;
2469/5
\endexample
Note  that  the numerator and denominator  are divided by their  greatest
common divisor  and that the result is uniquely represented as a division
instruction.

We     haven't met negative numbers      yet.  So consider the  following
self-explanatory examples.
\beginexample
gap> -3; 17 - 23;
-3
-6
\endexample
The exponentiation   operator  is  written  as  `^'. This   operation  in
particular might lead  to  very large numbers.  This  is  no problem  for
{\GAP} as it can handle numbers of (almost) any size.
\beginexample
gap> 3^132;
955004950796825236893190701774414011919935138974343129836853841
\endexample
The `mod' operator allows you to compute one value modulo another.
\beginexample
gap> 17 mod 3;
2
\endexample
Note  that  there must be   whitespace around the  keyword  `mod' in this
example since `17mod3' or `17mod' would be interpreted as identifiers.
The whitespace around operators that do not consist of letters, e.g.,
the operators `*' and `-', is not necessary.

{\GAP}  knows a  precedence  between operators that may be overridden  by
parentheses.
\beginexample
gap> (9 - 7) * 5 = 9 - 7  * 5;
false
\endexample
Besides these arithmetical operators there are comparison operators in
{\GAP}. A comparison results  in a  *boolean  value* which is  another
kind  of constant.  The comparison  operators `=', `\<>', `\<', `\<=',
`>' and `>=',  test for equality, inequality,  less than, less than or
equal, greater than and greater than or equal, respectively.
\beginexample
gap> 10^5 < 10^4;
false
\endexample
The boolean values  `true' and   `false'  can be  manipulated via logical
operators, i.~e., the unary operator `not' and the binary operators `and'
and `or'.  Of course boolean values can be compared, too.
\beginexample
gap> not true; true and false; true or false;
false
false
true
gap> 10 > 0 and 10 < 100;
true
\endexample
Another important  type of constants in   {\GAP} are *permutations*. They
are written in cycle notation and they can be multiplied.
\beginexample
gap> (1,2,3);
(1,2,3)
gap> (1,2,3) * (1,2);
(2,3)
\endexample
The inverse of the   permutation  `(1,2,3)' is denoted   by `(1,2,3)^-1'.
Moreover the caret operator `^' is used to determine the image of a point
under a permutation and to conjugate one permutation by another.
\beginexample
gap> (1,2,3)^-1;
(1,3,2)
gap> 2^(1,2,3);
3
gap> (1,2,3)^(1,2);
(1,3,2)
\endexample
The various other constants that {\GAP} can deal with will be introduced
when they are used, for example there are elements of finite fields
such as `Z(8)', and complex roots of unity such as `E(4)'.

The    last  type  of   constants  we  want  to mention    here are the
*characters*, which are simply objects in {\GAP} that represent arbitrary
characters  from  the character set   of the  operating system. Character
literals can  be  entered   in  {\GAP} by  enclosing  the   character  in
*singlequotes* `{'}'.
\beginexample
gap> 'a';
'a'
gap> '*';
'*'
\endexample
There are no  operators defined for characters except that characters can
be compared.

%%  Summary  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
In this  section you  have  seen that values  may  be preceded  by  unary
operators  and combined by  binary operators placed between the operands.
There are rules for precedence which may be overridden by parentheses.  A
comparison  results in a boolean value.   Boolean values are combined via
logical operators.  Moreover you have seen that {\GAP} handles numbers of
arbitrary size.   Numbers and boolean   values are constants.   There are
other types of  constants in {\GAP} like permutations.   You are now in a
position to use {\GAP} as a simple desktop calculator.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Variables versus Objects}\null

\index{variables}\index{assignment}\index{identifier}\index{objects}
\atindex{objects!vs.\ variables}{@objects!vs.\ variables|indexit}
The  constants described  in the  last  section are  specified by certain
combinations   of digits and  minus  signs (in  the case  of integers) or
digits,  commas  and parentheses  (in   the case  of permutations). These
sequences of characters always  have the same meaning  to {\GAP}.  On the
other hand, there are *variables*, specified by a sequence of letters and
digits (including at least one letter), and their meaning depends on what
has been  assigned to them.  An *assignment* is  done by a {\GAP} command
`<sequence_of_letters_and_digits> := <meaning>',  where the  sequence  on
the left hand side is called the *identifier*  of the variable and it serves
as its name. The meaning on the right hand side can be a constant like an
integer or  a  permutation, but  it can  also be almost  any other {\GAP}
object. From now on,  we will use the  term *object* to denote  something
that can be assigned to a variable.

There must be no whitespace between the `:' and the `=' in the assignment
operator.  Also do not confuse  the  assignment operator with the  single
equality sign `=' which in {\GAP} is only used for the test of equality.
\beginexample
gap> a:= (9 - 7) * (5 + 6);
22
gap> a;
22
gap> a * (a + 1);
506
gap> a = 10;
false
gap> a:= 10;
10
gap> a * (a + 1);
110
\endexample
After an assignment the assigned object is echoed on the  next line.  The
printing of the  object of a statement may  be in every case prevented by
typing a double semicolon.
\beginexample
gap> w:= 2;; 
\endexample
After the assignment the variable evaluates  to that object if evaluated.
Thus it is possible to  refer to that object by  the name of the variable
in any situation.

This is in fact the whole secret of an assignment. An identifier is bound
to an  object and from this moment  points to that object.  Nothing more.
This binding  is changed by the  next  assignment to that  identifier. An
identifier does not denote a block of memory as in some other programming
languages. It simply points to an object, which has  been given its place
in memory by the {\GAP} storage manager.   This place may change during a
{\GAP} session, but that doesn't  bother the identifier.  *The identifier
points to the object, not to a place in the memory.*

For the  same reason it is  not the  identifier that has   a type but the
object.  This means  on the other hand that  the identifier `a' which now
is bound to an integer object may in the  same session point to any other
object regardless of its type.

Identifiers  may be sequences  of letters and digits containing at  least
one letter.   For example  `abc' and `a0bc1'  are valid identifiers.  But
also `123a'  is  a valid identifier as  it cannot be  confused  with  any
number.  Just `1234' indicates the  number 1234 and cannot be at the same
time the name of a variable.

Since  {\GAP} distinguishes  upper and  lower  case, `a1'  and  `A1'  are
different  identifiers.   Keywords  such as `quit'  must not  be used  as
identifiers.  You will see more keywords in the following sections.

In  the remaining  part of  this manual   we  will ignore the  difference
between variables, their names  (identifiers), and the objects they point
to.  It may be useful  to think from time  to  time about what is  really
meant by terms such as ``the integer `w'''.

There are some predefined variables coming with {\GAP}.  Many of them you
will find in the remaining  chapters of  this manual, since functions are
also referred to via identifiers.

You    can get   an  overview   of  *all*  {\GAP}   variables by entering
`NamesGVars()'.  Many of these are predefined.  If  you are interested in
the variables you  have defined yourself  in the current {\GAP}  session,
you can enter `NamesUserGVars()'.
%notest
\beginexample
gap> NamesUserGVars();
[ "a", "w" ]
\endexample
This seems to be the  right place to state the  following rule:
The name of every global variable in the {\GAP} library starts with a
*capital letter*.
Thus if you choose only names starting with a small letter for your own
variables you will not attempt to overwrite any predefined variable.
(Note that most of the predefined variables are read-only,
and trying to change their values will result in an error message.)

There are some further interesting variables one of which will be
introduced now.

\indextt{last}\indextt{last2}\indextt{last3}
Whenever {\GAP} returns an object by printing it  on  the next  line this
object is assigned to the variable `last'.  So if you computed
\beginexample
gap> (9 - 7) * (5 + 6);
22
\endexample
and forgot to assign the object to the  variable `a' for further use, you
can still do it by the following assignment.
\beginexample
gap> a:= last;
22
\endexample
Moreover there are variables `last2' and `last3', you can guess their values.

%%  Summary  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
In this section you  have seen how to  assign objects to variables. These
objects  can  later be accessed  through the  name  of the  variable, its
identifier. You  have also encountered the  useful concept of  the `last'
variables storing the latest returned  objects. And you have learned that
a double semicolon prevents the result of a statement from being printed.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Objects vs.\ Elements}\null

\atindex{objects!vs.\ elements}{@objects!vs.\ elements|indexit}\index{elements}
In the last section  we mentioned that every object   is given a  certain
place  in memory by the  {\GAP} storage manager  (although that place may
change in the course  of  a {\GAP}  session). In  this sense, objects  at
different places in memory are never equal, and if  the object pointed to
by the  variable  `a' (to be more  precise,  the variable with identifier
`a')  is  equal to the   object pointed to by  the  variable `b', then we
should better  say that they  are not only  equal but *identical*. {\GAP}
provides the function `IsIdenticalObj' to test whether this is the case.

\beginexample
gap> a:= (1,2);; IsIdenticalObj( a, a );
true
gap> b:= (1,2);; IsIdenticalObj( a, b );
false
gap> b:= a;; IsIdenticalObj( a, b );
true
\endexample

\indextt{IsIdenticalObj}

%\exercise `IsIdenticalObj' works not   only for variables, but  also  for
%constants.   Try   the   commands      `IsIdenticalObj'(  -1,  -1    )',
%`IsIdenticalObj( 2^28, 2^28   )', `IsIdenticalObj( (1,2),  (1,2) )', and
%explain the outcome.
%
%\answer `IsIdenticalObj(  -1, -1 )' is  `true'.  Small integers like `-1'
%are treated in a special way, equal small integers behave as if they were
%identical  objects. Integers  larger    than $2^{28}-1$ or  smaller  than
%$-2^{28}$ can be nonidentical objects, and calculating such an integer or
%entering it at the  keyboard constructs a new object.  The same holds for
%the two equal but not identical permutations in the third example.

As the above example indicates, {\GAP}
objects  <a>  and  <b> can  be  unequal  although they are   equal from a
mathematical point of view, i.e., although we should have `<a> = <b>'. It
may  be that the objects <a>  and <b> are  stored  in different places in
memory, or it may be that we have  an equivalence relation defined on the
set of  objects under which <a>  and <b> belong   to the same equivalence
class.  For example, if `<a>  = $x^3$' and  `<b> = $x^{-5}$' are words in
the finitely presented group $\langle  x\mid x^2=1\rangle$, we would have
`<a> = <b>' in that group.

{\GAP}   uses  the equality operator  `='  to  denote such a mathematical
equality, *not* the identity of objects. Hence we often  have `<a> = <b>'
although `IsIdenticalObj( <a>, <b> ) =  false'.  The operator `=' defines
an equivalence relation on the set of all {\GAP} objects, and we call the
corresponding  equivalence classes *elements*.   Phrasing it differently,
the same element may be represented by various {\GAP} objects.

Non-trivial examples of   elements   that are represented by    different
objects (objects  that really  look different,  not ones  that are merely
stored in  different  memory places)  will  occur only   when  we will be
considering composite objects such as lists or domains.

%\exercise To prepare yourself for the discussion of equality and identity
%of lists, assume  that a variable has been  assigned the empty list by `a
%:=  [ ];' and   explain how to  assign  (1)~the same (identical)  object,
%(2)~an equal  object to another variable  `b'. How can someone  else test
%which alternative you chose without using `IsIdenticalObj'?
%
%\answer (1)~`b := a;'\quad (2)~`b := [ ];' or `b := ShallowCopy( a );' or
%something similar.\quad  To test whether `b'  is identical to `a', put an
%element  in the list with  `Add(  b, 1  );'  and see  if this change also
%affected `a'.  The lists are then  identical if and only  if  this is the
%case, i.e., if still `a = b'.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{About Functions}

A  program  written  in  the  {\GAP} language  is  called  a  *function*.
Functions  are   special  {\GAP}  objects.   Most  of  them  behave  like
mathematical functions.  They are applied to  objects and  will return  a
new  object  depending  on  the input.   The  function  `Factorial',  for
example,  can be applied to an  integer and will  return the factorial of
this integer.
\beginexample
gap> Factorial(17);
355687428096000
\endexample
Applying  a  function  to arguments  means  to  write  the  arguments  in
parentheses following the function.   Several arguments are  separated by
commas, as for the  function  `Gcd' which  computes  the greatest  common
divisor of two integers.
\beginexample
gap> Gcd(1234, 5678);
2
\endexample
There   are other functions that  do  not return   an  object but only
produce  a side effect, for  example changing one  of their arguments.
These functions are sometimes called procedures.  The function `Print'
is only called for the side effect of printing something on the screen.
\beginexample
gap> Print(1234, "\n");
1234
\endexample
In order to be able to compose arbitrary text with `Print', this function
itself will not produce a line break  after printing. Thus we had another
newline character `\"\\n\"' printed to start a new line.

Some functions will both change an argument  and return an object such as
the function `Sortex'  that sorts a  list and returns the permutation  of
the list  elements that it has  performed.  You will not understand right
now what it means  to change an object.   We will return to this  subject
several times in the next sections.

\index{maps-to operator}
A comfortable way to define a function yourself is the *maps-to* operator
`->' consisting of  a minus sign and a   greater sign with  no whitespace
between them. The function  `cubed' which maps a  number  to its  cube is
defined on the following line.
\beginexample
gap> cubed:= x -> x^3;
function( x ) ... end
\endexample
After the function has been defined, it can now be applied.
\beginexample
gap> cubed(5);
125
\endexample
More complicated  functions,  especially  functions with   more  than one
argument cannot be defined in this way.
You will see how to write your own {\GAP} functions in
Section~"Writing Functions".

%%  Summary  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
In  this section you have seen {\GAP} objects of type function.  You have
learned how to apply a function to  arguments.  This  yields as result  a
new object or a side effect.  A side effect may change an argument of the
function.   Moreover you have seen an easy  way  to define a  function in
{\GAP} with the maps-to operator.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Help}

The  content of  the {\GAP}  manuals is  also available  as on-line  help. A
{\GAP} session loads  a long list of index entries.  This typically contains
all  chapter  and  section  headers,  all  names  of  documented  functions,
operations and so on, as well as  some explicit index entries defined in the
manuals.

The format of a query is as follows.

`?[<book>:][?]<topic>'

A simple example would be to type  `?help' at the {\GAP} prompt. If there is
a single section with index entry <topic> then this is displayed directly.

If  there are  several matches  you get  an overview  like in  the following
example.

\begintt
gap> ?sets
Help: several entries match this topic - type ?2 to get match [2]

[1] Tutorial: Sets
[2] Reference: Sets
[3] Reference: sets
[4] Reference: Sets of Subgroups
[5] Reference: setstabilizer
\endtt

{\GAP}'s manuals consist of several  *books*, which are indicated before the
colon in the list above. A help query can be restricted to one book by using
the optional <book>: part. For example  `?tut : sets' will display the first
of these help sections. More precisely, the parts of the string <book> which
are separated  by white  space are  interpreted as  beginnings of  the first
words in  the name of the  book. Try `?books'  to see the list  of available
books and their names.

The  search for  a  matching <topic>  (and optional  <book>)  is done  *case
insensitively*.  If  there  is  another  `?'  before  the  <topic>,  then  a
*substring search* for <topic> is  performed on all index entries. Otherwise
the parts  of <topic> which are  separated by white space  are considered as
*beginnings of the first words* in an index entry.

White space is normalized in the search string (and the index entries). 

*Examples.* All the  following queries lead to the chapter  of the reference
manual which explains the use of {\GAP}'s help system in more detail.

\begintt
gap> ?Reference: The Help System
gap> ?  REF : t h s
gap> ?ref:?  help   system 
\endtt

The query `??sets' shows all help  sections in all books whose index entries
contain the substring `sets'.

As mentioned in the  example above a complete list of  commands for the help
system  is available  in Section~`?Ref:  The Help  System' of  the reference
manual.  In  particular  there  are  commands to  browse  through  the  help
sections, see~`?Ref:  Browsing through the Sections'  and there is a  way to
influence  the  way  *how*  the  help  sections  are  displayed,  see~`?Ref:
SetHelpViewer'. For  example you can  use an  external pager program,  a Web
browser,  `dvi'-previewer and/or  `pdf'-viewer for  reading {\GAP}'s  online
help.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Further Information introducing the System}

For large amounts of input data, it might be advisable to write your
input first into a file, and then read this into {\GAP};
see~"ref:Read", "ref:Edit" for this.

The definition of the {\GAP} syntax can be looked up in
Chapter~"ref:The Programming Language".
A complete list of command line editing facilities is found
in Section~"ref:Line Editing".
The break loop is described in Section~"ref:Break Loops".

Operators are explained in more detail in Sections~"ref:Expressions" and
"ref:Comparisons".
You will find more information about boolean values in
Chapters~"ref:Booleans" and "ref:Boolean Lists".
Permutations are described in Chapter~"ref:Permutations" and characters
in Chapter~"ref:Strings and Characters".

Variables and assignments are described in more detail in~"ref:Variables"
and "ref:Assignments".
A complete list of keywords is contained in~"ref:Keywords".

More about functions can be found in~"ref:Function Calls"
and~"ref:Procedure Calls".

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E  introduc.tex  . . . . . . . . . . . . . . . . . . . . . . . ends here