% from 20.3.1989 hk, version 0.03
% revised 5.11.1989 hk, version 0.30
% restructured 24.1.90
% corrections by haible 25.9.90
% revised 21.2.91, version 0.6

%tutorial chap 1, 2

\chapter{Introduction} %--------------------

MAS is a computer algebra system in contrast to 
symbol\index{symbol} manipulation systems.
The MAS data objects are not considered as 
symbolic expressions, 
but they are considered to be elements of 
algebraic structures\index{structure}.
So working with MAS usually requires that you have to decide 
in which algebraic structure you want to compute. 
Data objects can then be converted from their external representation
(character sequences) to their internal representation 
(lists over numbers).
These internal objects can then be used as inputs to
programs which are implementations of algebraic functions.  

In contrast, other symbol manipulation programs such as  
Derive\index{Derive} \cite{Rich 88},
Reduce\index{Reduce} \cite{Hearn 87},
Maple\index{Maple} \cite{Geddes 86},
Mathematica\index{Mathematica} \cite{Wolfram 88}, 
or Macsyma\index{Macsyma} \cite{Pavelle 85}
view their input\index{input} as untyped expressions built from
numbers, symbols, operators and functions.
The user has then a wide variety of tools to 
manipulate expressions 
(like expanding expressions, collecting or extracting subexpressions
or applying substitutions or rewrite rules to the expressions).
The interpreter of the
Scratchpad\index{Scratchpad} II \cite{Jenks 84,Jenks 85} 
computer algebra system is further
equipped with an algebraic `knowledge\index{knowledge}' 
and tries to determine the algebraic domain 
to which the input expression belong.

On the other hand in MAS an expression is evaluated 
and is normally not manipulated. 
Algebraic objects are constants for the interpreter and can
only be modified using appropriate methods from the 
respective algebraic structures. 
The mathematical knowledge\index{knowledge} 
of MAS is only contained in the 
algorithm\index{algorithm} libraries
(either Modula--2 programs or specification definitions).


\section{Getting Started} %------------------

In this section we give a first look on the usage of the 
MAS system. 

To start the program,
select the directory\index{directory} containing the 
MAS program and data files.
\begin{verbatim}
       start:           MAS.PRG or MAS.TTP or MAS.EXE
       banner:          MAS Version r.xu
       system prompt:   MAS: 
       system answer:   ANS: 
       leave with:      EXIT. 
\end{verbatim}

When MAS is started, it first initializes all available 
storage\index{storage} for
list processing\index{list processing}. Then it reads the data set
`mas.ini' from the current
directory\index{directory}. It next issues the following prompt: 

\begin{verbatim}
       MAS: 
\end{verbatim}

Now MAS is waiting for a program to be typed in. The program has to
be in a Modula--2 like syntax\index{syntax} (see below). 
The parser\index{parser} reads the parts
of the program: declarations\index{declaration} and statements. 
A simple assignment\index{assignment} like
\verb/a:=1./ suffices as program. 
From this program the parser generates
a LISP\index{LISP} S--expression\index{S--expression} 
which is then fed into the evaluator. The result
is displayed after 

\begin{verbatim}
       ANS: 
\end{verbatim}

Then the read-eval-print loop is repeated.

Example 1:
\begin{verbatim}
       MAS: a:=2*3.   (* this is a one statement program *)
       ANS: 6. 
\end{verbatim}
By this one statement program \verb/2*3/ is evalauted and 
the result \verb/6/ is bound to the symbol (or variable) `a'. 
Comments are enclosed in \verb/(*/ and \verb/*)/.
\index{comment} 

The next example shows the usage of the WHILE statement.

Example 2:
\begin{verbatim}
       MAS: d:=0. i:=0.    (* two one statement programs *)
       ANS: 0                 
       ANS: 0                 
       MAS: WHILE i < 17 DO     
                  i:=i+1; d:=d+i*i 
                  END.              
       ANS: 1785                 
\end{verbatim}
First the symbol `d' is bound to 0 and also 
the symbol `i' is bound to 0. 
Then commes a WHILE--loop in Modula--2 style. 
In its body the squares of `i'are computed and 
summed to `d'.
Observe that statements have values as in LISP.
However constructions like
\verb/d:=IF cond THEN ... END/ are {\bf syntactically} 
invalid in the MAS language\index{language}.
\index{IF}\index{WHILE}

It is possible to access compiled functions and procedures.
\index{compiled function}
However you {\bf must} use the corresponding 
write procedures to display the object not as 
list.

Example 3:
\begin{verbatim}
       MAS: p:=APPI().  
       ANS: (2 (221327762 71487876 210828714)) 
       MAS: APWRIT(p).  
       0.314159265358979323846E1 
       ANS: ()          
\end{verbatim}

In this example \verb/APPI/ denotes a function from
the arbitrary precision floating point library which returns
the value of $\pi$ in the actual precision 
(initially 20 decimal digits). 
The computed value in in internal lisp representation and 
to display the value in readable form the 
procedure \verb/APWRIT/ must be called.
\index{APPI}\index{APWRIT}\index{floating point} 

To find out which compiled procedures are accessible there is a
`HELP' command.
With `HELP\index{HELP}.' you get a list of all available functions
together with their signature\index{signature}.
During the display
screen scrolling can be stopped by pressing any key 
(in particular $<$CNTRL$>$-S will work), 
output\index{output} can be resumed by
again pressing any key (e.g. $<$CNTRL$>$-Q).

If the specification\index{specification} support is loaded it is 
possible to declare variables\index{variable} 
and to use generic assignments\index{assignment}.
If further generic parse is enabled (with \verb/PRAGMA(GENPARSE)/)
then also generic expressions are possible.

Example 4:
\begin{verbatim}
       MAS: VAR f: FLOAT.        (* declare FLOAT variable *)
       ANS: FLOAT.                 
       MAS: f:="1.0E99".      
       ANS: "0.100000000000000000000E100"
       MAS: f:= "2.0": FLOAT * f - f.         
       ANS: "0.100000000000000000000E100"
\end{verbatim}

In this example MAS uses the type information of the variable `f' 
to determine the correct conversion
function from the string "1.0E99" to the internal representation
of floating point\index{floating point} numbers. 
During the evaluation the data object
is tagged, so that the output 
routine can call the correct printing function.
If \verb/PRAGMA(GENPARSE)/ was executed, then 
the arithmetical operators (like \verb/*/ and \verb/-/ 
in line 5) are associated with generic functions 
(in this case with \verb/PROD/ and \verb/DIF/).
The constant \verb/2.0/ form the FLOAT structure can be entered 
in the form \verb/"2.0": FLOAT/.
The generic operations can also be used within 
algorithms.

In this section we have seen that 
{\bf control statements} can be entered directly from the keyboard,
that {\bf compiled functions} can be accessed 
and that {\bf variable declarations} and
{\bf generic expressions} are available in MAS.


\chapter{Elementary Concepts} %--------------------

In this section we will discuss some of the key features and
concepts of MAS. 

Starting point for the development of MAS 
was the requirement for a computer algebra system 
with an up to date language and design which makes 
the existing ALDES / SAC--2 algorithm libraries available. 
At this time there have been about 650 algorithms 
in ALDES / SAC--2 and in addition I had 450 algorithms 
developed on top of ALDES / SAC--2.
The tension of reusing existing software 
in an interactive environment with specification 
capabilities contributes most to the evolution of MAS.

The resulting view of the software has many 
similarities with the model theoretic view of algebra.
The abstract specification capabilities are 
realized in a way that an interpretation in an 
example structure (a model) can be denoted. 
This means that is is not only possible to compute in 
term models modulo some congruence relation, but 
it is moreover possible to exploit an fast interpretation 
in some optimized (or just existing) piece of software.  

The main {\bf design concepts} are:
MAS replaces the ALDES language \cite{Loos 76} and
the FORTRAN implementation system of SAC--2
by the Modula--2 language \cite{Wirth 85a}.
Modula--2 is well suited for the development of large
program libraries; the language is powerful enough to
implement all parts of a computer algebra system and the
Modula--2 compilers have easy to use program development
environments.

To provide an interactive calculation system a
LISP interpreter is implemented in Modula--2 with
full access to the library modules.
LISP\index{LISP} was chosen because it seemed to be
most flexible and well understood to provide a basis for 
an interactive system and experimenting with generic functions.
Using Modula--2 procedure types\index{procedure type}\index{type}, 
the compiled procedures are made accessible from the LISP\index{LISP} 
interpreter. To add a new compiled procedure one has to compile an 
interface module coded in Modula--2 with the appropriate 
import lists and declaration procedures 
and then one re--links the MAS main program. 
This guarantees maximum efficiency of the developed
algorithms\index{algorithm}.

As mentioned above, the mathematical knowledge\index{knowledge} 
of MAS is only contained in the Modula--2 algorithm libraries. 
Thus the Modula--2 compiler\index{compiler} 
with its linker serves as a knowledge\index{knowledge} 
acquisition system without requiring any further effort 
to setup knowledge--based computer algebra 
systems as suggested by \cite{Calmet 87}.

For better usability a Modula--2 like
imperative (interaction) language was defined, including 
a type system and function overloading capabilities.
The MAS parser\index{parser} generates LISP\index{LISP} 
S--expressions\index{S--expression}, 
which are then evaluated by the LISP 
interpreter.\index{evaluation}

To increase expressiveness high--level specification 
language constructs have been included together 
with conditional term rewriting capabilities.
They resemble facitilies known from 
algebraic specification languages like ASL \cite{Wirsing 86}.

The MAS language and its interpreter has no 
{\em knowledge of mathematics} and mathematical objects; 
however it is capable to describe (specify) and implement 
mathematical objects and to 
use libraries of implemented mathematical methods. 
Further the imperative programming, the conditional rewriting 
and function overloading concepts are seperated in a clean way.

The type declaration concept equips the interpreter with the 
knowledge\index{knowledge}
that some variables\index{variable} and objects have 
types\index{type}. Applying generic functions
to these typed variables\index{variable} or objects causes the 
interpreter to look for an executable function, 
which can work with the specific object types\index{type}. 

The system design also assures high portability of the software. 
All storage\index{storage} and input\index{input}/output\index{output} 
management is handled by only two library\index{library}
modules MASSTOR and MASBIOS. They have been first implemented for
an Atari 1040 computer running TOS\index{TOS} and GEM\index{GEM} 
and are also running on other computers.

In the following sections we explain how to make efficient use of MAS:
editing files, reading files, browsing definition modules.
Further some basic arithmetic functions are explained and 
the error handling of MAS is discussed.


\section{Edit--run--debug Cycle}

In general you will not type every statement directly to the MAS 
terminal. It is much more convenient to use your favourable 
editor\index{editor} 
to prepare a sequence of statements for MAS. 
Then you can feed this
data set into MAS, save some output\index{output} and 
determine your next action.

Although editors are computer and 
operating system\index{operating system} dependent, 
any implementation\index{implementation} of MAS should provide 
some similar statements as discussed
now for the Atari implementation.

On the Atari there are two ways to call an editor\index{editor}:
\verb/EDIT("data-set-name")/ or via the 
operating system\index{operating system} 
\verb/DOS("editor-name data-set-name")/.
After return from the editor the data set can be read in 
with 
\verb/IN("data-set-name")/. Output can be saved in a file with
\verb/OUT("data-set-name")/ and then the file can be closed 
using 
\verb/SHUT("data-set-name")/.

To speedup this cycle and minimize typing 
you can use the following two procedures

\begin{verbatim}
       VAR what: STRING.

       PROCEDURE doit;
       BEGIN what:="data set name";
             EDIT(what) END doit.

       PROCEDURE run;
       IN(what) run.
\end{verbatim}

So typing \verb/doit./ will call the editor and after return
typing \verb/run./ will execute the file. You can also place
several procedures like `doit' in the startup file
`MAS.INI', so that they are ready to be used. 
\verb/run/ will then always execute the last edited file. 

The editor can also be used to browse the appropriate 
definition modules during editing.
If the editor is programmable (like microEMACS)
further improvements of this procedure are possible 
and are described in the section on `getting help'.


\section{Elementary Arithmetic}

As mentioned above, the interpreter only knows about atoms and 
lists\index{atom},
that means the arithmetic\index{arithmetic} 
operators `$+$, $-$, $*$, $/$' and relations 
`$<$, $=$, $<=$, $>$, $>=$' are only valid with atoms as arguments. 
But this is not checked,
and may lead to unpredictable results, so you are {\em self}
responsible to supply the correct arguments to the 
compiled subroutines. 

In the next example we will discuss the computation of
$n$ factorial for different values of $n$.   
If you know that you need factorial($n$) only for 
small values of $n$, 
such that factorial($n$) $<$ beta $= 2^{29}$, 
that is for $n <= 12$ you may write:

\begin{verbatim}
       MAS: PROCEDURE fac(n);
            VAR   d, i: ANY;
            BEGIN d:=1; i:=n;
                  WHILE i > 1 DO
                        d:=d*i; i:=i-1          
                        END;
                  RETURN(d)
                  END fac;
            fac(6).
       ANS: 720
\end{verbatim}
   
For bigger values of $n$ you must use arbitrary precision 
integers\index{integer} as 
provided with the ALDES/SAC-2 subroutine libraries. Here we use
IPROD\index{IPROD} for multiplication ($*$) and 
IWRITE\index{IWRITE} to display 
the result, otherwise the internal
SAC-2 list representation of arbitrary 
precision integers is displayed.
 
\begin{verbatim}
       MAS: PROCEDURE fac(n);
            VAR   d, i: ANY;
            BEGIN d:=1; i:=n;
                  WHILE i > 1 DO
                        d:=IPROD(d,i); i:=i-1   
                        END;
                  RETURN(d)
                  END fac;
            j:=fac(50).
       ANS: (0 373030912 375187572 439570590 300896040 
               154982421 452089979 2365)
       MAS: IWRITE(j).
            30414093201713378043612608166064768844377641
            568960512000000000000
\end{verbatim}

Note that since \verb/i/ contains only small integers, 
the built-in operations
can be used. The computing time for `fac(50)' is 4 seconds
on an Atari 1040 ST and 2 seconds are needed to print the result. 

{\bf Question:} 
how are the arbitrary precision integers\index{integer} internally 
represented if you know that $2^{29}$ is represented by the 
list $(0,1)$ and $-2^{29}$ by $(0,-1)$. 

It is also possible to use 
recursion as with LISP or Modula--2:

\begin{verbatim}
       PROCEDURE fac(n);
       IF n <= 1 THEN RETURN(1)
                 ELSE RETURN(IPROD(n,fac(n-1))) END fac. 
\end{verbatim}

Now let's try a more difficult example:  
compute 50 digits\index{digit} of $e$ using 
arbitrary precision rational\index{rational} numbers. 

The function `Exp' takes $x$ and the desired precision $eps$ as 
input parameter. It computes the taylor series of the 
exponential function: 
$\sum_{i=1,\ldots} \frac{x^i}{\mbox{fac}(i)}$.
The summation runs  
until $\frac{x^i}{\mbox{fac}(i)} < \frac{eps}{2}$,
that is the rest is smaller than the desired precision.
Integers are converted to rational numbers 
by the function `RNINT' or `RNRED'.
`RNPROD', `RNSUM', `RNABS' and `RNCOMP' denote the
product, sum, absolute value and comparison of 
rational numbers.
\index{RNINT}\index{RNRED}
\index{RNPROD}\index{RNSUM}\index{RNABS}\index{RNCOMP}

\begin{verbatim}
       dig:=50.
       Eps:=RNRED(1,IEXP(10,dig)). 

       PROCEDURE Exp(x,eps);
       (*Exponential function. eps is the 
       desired precision. *)
       VAR   s, xp, i, y, p: ANY;
       BEGIN 
       (*1*) y:=RNINT(1); s:=RNINT(1); i:=0; 
             p:=RNPROD(eps,RNRED(1,2));
       (*2*) REPEAT i:=i+1; xp:=RNRED(1,i);
                    y:=RNPROD(y,x); y:=RNPROD(y,xp);
                    s:=RNSUM(s,y)
                    UNTIL RNCOMP(RNABS(y),p) <= 0;
             RETURN(s)
       (*9*) END Exp.
\end{verbatim}

The results of the computation can be displayed by the 
functions `RNDWR' and `RNWRIT'.
RNWRIT\index{RNWRIT} writes out a rational\index{rational} 
number as `nominator/denominator' and
RNDWR\index{RNDWR} writes a rational  
number as decimal number with
specified number of digits\index{digit} after the decimal point.
\index{RNWRIT}\index{RNDWR}

\begin{verbatim}
       one:=RNINT(1).
       e:=Exp(one,Eps).

       BEGIN CLOUT("AbsErr = "); RNDWR(Eps,dig); BLINES(0) END. 
       BEGIN CLOUT("Result = "); RNDWR(e,dig); BLINES(0) END. 
       BEGIN CLOUT("Result = "); RNWRIT(e); BLINES(0) END. 
\end{verbatim}

The following output is produced:

\begin{verbatim}
       {0 sec} ANS: (1 1)
 
       {20 sec} ANS: ((119769761 450433631 444044040 360650700 
                      406458113 17125896) (0338539520 159342123 
                      356614372 176392732 6300265))
 
       AbsErr = 0.000000000000000000000000000000000
                  00000000000000001
 
       Result = 2.718281828459045235360287471352662
                  49775724709369996-
 
       Result = 76384051975228859737656454938414688
                9815927382313633/281001223550575979
                708628521248902313987276800000000
\end{verbatim}

The computing time for `Exp(1)' is 20 seconds
on an Atari 1040 ST and 4 seconds are needed to 
print the result with `RNDWR'. 


\section{Specification Component}

As already mentioned MAS views mathematics in the 
sense of universal algebra and model theory and is 
in some parts influenced by category theory.
In contrast to other computer algebra systems
(like Scratchpad II \cite{Jenks 85}),
\index{Scratchpad II}
the MAS concept provides a clean seperation of 
computer science and mathematical concepts. 
The MAS language and its interpreter has no 
{\em knowledge of mathematics} and mathematical objects; 
however it is capable to describe (specify) and implement 
mathematical objects and to 
use libraries of implemented mathematical methods. 
Further the imperative programming, the conditional rewriting 
and function overloading concepts are seperated in a clean way.
\index{algebra}\index{universal algebra}\index{model theory}
\index{category theory}

MAS includes the capability to 
join {\em specifications} and to rename sorts and operations 
during import of specifications. 
This allows both the specification of abstract objects 
(rings, fields),
concrete objects (integers, rational numbers) and 
concrete objects in terms of abstract objects 
(integers as a model of rings). 
Specifications can be parameterized in the sense of 
$\lambda$ abstraction.
\index{join}\index{rename}
\index{concrete objects}\index{abstract objects}

The specification language constructs are discussed 
in detail in chapter \ref{spec.chap}. 
In this overview we will just 
describe the advantages in the interactive usage 
which are gained when using the specification component.

In this section we will only discuss some features 
of the interactive use of the specification component 
by means of the following example:

\begin{verbatim}
        VAR r, s: RAT.             ANS: RAT().

        r:="2222222222.777777777777777".
        ANS: "2222222222777777777777777/1000000000000000".

        s:=r/r.                    ANS: "1".

        s:=r^0 + s - "1": RAT.     ANS: "1".
\end{verbatim}

The first line declares the variables \verb/r/ and \verb/s/ 
to be of type \verb/RAT/, that is to be rational numbers. 

The second line is a so called generic assignment. 
Depending on the type of \verb/r/ the character string on the
right hand side is read (or converted to internal form). 
Internally an object with type, value and descriptor information 
is created. This information is then used by the 
generic write function \verb/WRITE(RAT)/ for displaying 
the result in the next line.

The fourth line shows the computation of \verb.r/r.. 
According to the type information of \verb/r/ the 
corresponding generic function is determined. 
Then the interpretation of the generic function in 
the rational numbers is determined and executed.

Finally the information on the output parameters 
is used to create a new typed object. 
This object is then bound to 
the variable \verb/s/ and finally it is displayed.

The last line shows the computation of a more 
complex expression \verb/r^0 + s - "1": RAT/.
The term \verb/"1": RAT/ denotes a constant from 
the rational numbers, namely \verb/1/. The contents of the 
character string are read by the generic function 
\verb/READ(RAT)/ and a new typed object is created. 
The expression \verb/r^0/ is computed by an abstract function 
(namely \verb/EXP/) of the abstract \verb/RING/ implementation.

We have seen, that the usage of the specification component 
is easy when the specification libraries are available. 
However a detailed explanation of the complete truth 
is somewhat complex and cannot be discussed here. 


\section{Getting Help}

One problem in using MAS is that information is required 
on what functions are available. 
Further the specifications of the functions are often 
required.
MAS provides several help facilities which are
discussed in this section.
\index{help facilities}

\subsection{HELP Command}
 
There is 
a HELP\index{HELP} command showing all accessible 
compiled functions, all interpreter functions and 
all signatures,
a EXTPROCS\index{EXTPROCS} command showing accessible 
external compiled functions,
an SIGS\index{SIGS} command showing defined 
signatures\index{signature} of functions,
a VARS\index{VARS} command which displays defined 
variables\index{variable},
a SORTS\index{SORTS} command which displays defined 
sorts\index{SORT},
a GENERICS\index{GENERICS} command listing all 
generic\index{generic} functions, 
a LISTENV\index{LISTENV} command to display values of 
variables\index{variable},
and a system browse\index{browse} facility for Modula--2 
definition\index{definition} modules.

Use the HELP\index{HELP} command to display a list of all 
compiled functions accessible from the interpreter.  
The HELP command output is like the following:

\begin{verbatim}
       List of all functions and procedures: 
        
       SIGNATURE add(nat nat): nat 
       GENERIC   add 
       SIGNATURE and(bool bool): bool 
       GENERIC   and 
       PROCEDURE arith()
       SIGNATURE Adefault(): atom 
       ...
       FUNCTION  RNABS(LIST): LIST
       FUNCTION  RNCOMP(LIST,LIST): LIST
       FUNCTION  RNDEN(LIST): LIST
       SIGNATURE RNDIF(RAT RAT): RAT 
       FUNCTION  RNDIF(LIST,LIST): LIST
       SIGNATURE RNDRD(RAT): RAT 
       FUNCTION  RNDRD(): LIST
       ...
       SIGNATURE ZERO(INT): INT 
       GENERIC   ZERO 
        
       145 signatures, 
       75 interpreter procedures, 
       188 compiled functions, 
       42 compiled procedures 
       accessible.
\end{verbatim}

From this list you can deduce the name of a function 
and its `arity', that is the number of input  
or output parameters\index{parameter}.
For example the function named `RNCOMP\index{RNCOMP}' has 
two input parameters, 
or `ZERO\index{ZERO}' is a generic function 
which has an interpretation in the integers `INT\index{INT}'. 

For the specification of these functions you must refer 
to the respective ALDES / SAC--2 or MAS documentation or
to the corresponding Modula--2 definition modules.

\subsection{System Browser}

For better online help it would be nice if the  
Modula--2 program development system has some 
browser\index{browse} facilities as in the 
Smalltalk--80 system with its class hierarchy 
browser\index{browse} \cite{Goldberg 81}. 

We have added macros\index{macro} and data sets for the
microEMACS editor\index{editor} 
to mimic some system browsing facilities.
Therefore if you use the microEMACS editor\index{editor}, 
you can browse\index{browse} 
a system file containing a procedure to module cross reference.
\index{cross reference}
When pressing the function key `F3', an editor window is
opened with the following contents:

\begin{verbatim}
       Procedure to module cross-reference:

       saci.def 10:     AADV(L: LIST; VAR AL,LP: LIST);
       sacsym.def 18:   ACOMP(A,B: LIST): LIST;
       sacsym.def 23:   ACOMP1(A,B: LIST): LIST;
       masstor.def 44:  ADV(L: LIST; VAR a, LP: LIST);
       saclist.def 10:  ADV2(L: LIST; VAR AL,BL,LP: LIST);
       saclist.def 15:  ADV3(L: LIST; VAR AL1,AL2,AL3,LP: LIST);
       saclist.def 20:  ADV4(L: LIST; VAR AL1,AL2,AL3,AL4,LP: LIST);
       sacanf.def 10:   AFDIF(AL,BL: LIST): LIST;
       sacanf.def 15:   AFINV(M,AL: LIST): LIST;
       sacanf.def 21:   AFNEG(AL: LIST): LIST;
       sacanf.def 26:   AFPROD(M,AL,BL: LIST): LIST;
       sacanf.def 32:   AFQ(M,AL,BL: LIST): LIST;
       sacanf.def 38:   AFSIGN(M,I,AL: LIST): LIST;
       sacanf.def 44:   AFSUM(AL,BL: LIST): LIST; 
       masapf.def 67:   APABS(A: LIST): LIST; 
       masapf.def 73:   APCMPR(A,B: LIST): LIST;
       masapf.def 12:   APCOMP(ML,EL: LIST): LIST;
       masapf.def 103:  APDIFF(A,B: LIST): LIST;
       masapf.def 115:  APEXP(A,NL: LIST): LIST;
       masapf.def 23:   APEXPT(A: LIST): LIST;
       masapf.def 38:   APFINT(N: LIST): LIST;
       masapf.def 121:  APFRN(A: LIST): LIST;
       ...
\end{verbatim}

The three columns have the following meaning:
1) name of the definition module containing the procedure,
2) the line number of the procedure within the definition module,
3) the procedure header with formal parameter declarations.

From the variable names it is sometimes possible to remember 
the meaning of the variables. If this information is not
sufficient the corresponding definition module can be
browsed.
Place the cursor in the line with the procedure 
you are interested in and press function key `F4'.
Then the system browser window is replaced by a window 
containing the corresponding definition module.
The cursor is moved to the comment of the function. 

\begin{verbatim}
       ...
       PROCEDURE APSPRE(N: LIST);
       (*Arbitrary precision floating point set precision.
       N is the desired precision of the floating point numbers. *)

       PROCEDURE APFINT(N: LIST): LIST;
       (*Arbitrary precision floating point from integer.
       The integer N is converted to an arbitrary precision
       floating point number. *)
       ...
\end{verbatim}

So browsing the definition modules you 
can determine which programs you want to call.
Then using the HELP function you
can determine if the program is accessible from the interpreter.

\subsection{Signatures, Generic Functions and Sorts}

The signature shows more verbose and  
mnemonic names of the data types of the formal parameters of
the procedures. 
Signature declarations for the most often used procedures are 
contained in separate files and can be loaded upon request 
(or automatically during startup). 
This information can then be displayed using the
SIGS\index{SIGS} command.

Generic functions are defined in an abstract structure 
and have an interpretation in some model. 
The information which interpretations are available 
for a generic function can be displayed using the
GENERICS\index{GENERICS} command.

The specification declarations are 
discussed in more detail in chapter \ref{spec.chap}.

\begin{verbatim}
       List of all signatures: 
        
       SIGNATURE add(nat nat): nat.
       SIGNATURE and(bool bool): bool.
       SIGNATURE Adefault(): atom.
       SIGNATURE ADD(atom atom): atom.
       SIGNATURE ADV(list object list).
       SIGNATURE Aone(): atom.
       SIGNATURE APDIF(FLOAT FLOAT): FLOAT.
       SIGNATURE APFINT(INT): FLOAT.
       ...
       SIGNATURE DIRPPR(dirp dirp): dirp.
       SIGNATURE DIRPSM(dirp dirp): dirp.
       SIGNATURE equal(nat nat): bool.
       SIGNATURE equival(bool bool): bool.
       SIGNATURE EQUAL(object object): atom.
       ...
       SIGNATURE TRUE(): bool.
       SIGNATURE WRITE(INT).
       SIGNATURE ZERO(INT): INT.
 
       145 signatures.
\end{verbatim}

For example `and\index{and}' is a function 
(actually a rewrite rule) taking two elements of 
an Boolean ring (`bool\index{bool}') as input and returns
a Boolean element. 
`EQUAL\index{EQUAL}', tests two objects 
if they are the same sequences of atoms and 
returns \verb/0/ or \verb/1/.

The available interpretations for the 
`EXP\index{EXP}', `PROD\index{PROD}' and `equal' 
functions could look as follows: 

\begin{verbatim}
       EXP:
       MAP (ipol atom) -> IPEXP(DESC, VAL, VAL). 
       MAP (dirp dirp) -> DIRPEX(VAL, VAL). 
       PROCEDURE EXP(X, n); 
          BEGIN 
          VAR x: LIST(ring, ()); 
          VAR i: LIST(atom, ()); 
          IF (n <= 0) THEN x:=ONE(X); RETURN(x) END; 
          i:=n; x:=X; 
          WHILE (i > 1) DO i:=(i-1); 
                x:=PROD(x, X) END; 
          RETURN(x) END EXP. 
       ...
       PROD:
       MAP (atom atom) -> MUL(VAL, VAL). 
       MAP (INT INT) -> IPROD(VAL, VAL). 
       MAP (nat nat) -> prod(VAL, VAL). 
       MAP (ipol ipol) -> IPPROD(DESC, VAL, VAL) WHEN EQ(DESC, DESC). 
       MAP (dirp dirp) -> DIRPPR(VAL, VAL). 
       MAP (RAT RAT) -> RNPROD(VAL, VAL). 
       MAP (MI MI) -> MIPROD(DESC, VAL, VAL) WHEN EQ(DESC, DESC). 
       MAP (FLOAT FLOAT) -> APPROD(VAL, VAL). 
       ...
       equal:
       RULE equal(X, X) => TRUE(). 
       RULE equal(succ(X), null()) => FALSE(). 
       RULE equal(null(), succ(X)) => FALSE(). 
       RULE equal(succ(null()), null()) => FALSE(). 
       RULE equal(succ(X), succ(Y)) => equal(X, Y). 
       ...
       66 generic items.
\end{verbatim}

A list of defined sorts can be obtained by the 
`SORTS\index{SORTS}' command. The output may look 
as follows: 

\begin{verbatim}
       List of all sorts: 
        
       ag, atom, bool, dc, diip, dip, dirp, elem, field, 
       fm, func, FLOAT, gbring, ipol, INT, list, melem, 
       mod, MI, name, nat, nint, obj, object, pair, pol, 
       rep, ring, RAT 
        
       29 sorts.
\end{verbatim}


\section{Handling Errors}

There is a wide variety of sources for errors\index{error}:

If the {\bf parser} detects any syntax\index{syntax} 
errors\index{error} he tries to skip invalid 
program parts, at least until he finds a period ( = end of program mark )
in the input\index{input} source.
Then he returns a quoted expression of what he was able to generate 
so far. So only syntactically correct programs become 
evaluated.

Errors during {\bf evaluation} are reported, 
but execution can usually be continued
if the errors are not too severe. 

Errors occurring at runtime in {\bf compiled code} are also reported.
This includes errors trapped by the processor (p.e. division by zero).
Whether execution is continued depends on the severity of the error.
Such a case may look like:

\begin{verbatim}
       5 Division by Zero 
       ** fatal error: processor interrupt 
       (a)bort, (b)reak, (c)ontinue (d)ebug or <ENTER> ? <ENTER>
       Trying to restart processor ...

       MAS: 
\end{verbatim}
  
In general you should hit $<$ENTER$>$ or $<$RETURN$>$ and the system will
take the appropriate action: 

\begin{deflist}{fatal error}
\item[error\index{error}:] continue, that means take some corrective action
                           and try to continue
\item[fatal error\index{fatal error}:] break, that means return to the 
                top level command loop
\item[confusion\index{confusion}:]  abort, that means execute processor 
                                 HALT instruction 
\end{deflist}

You should not respond with a `softer' reaction than the system 
would do unless you know what you are doing. 
But you can freely break to the top level command\index{command} 
loop or abort the run completely.  
  
The error handler executes the command loop as a coroutine to the
main MAS program. It further installs itself into the error handler
provided by the Modula--2 runtime support. By these mechanisms the 
error handler can catch runtime errors and most software errors.
However as with any LISP\index{LISP} system incorrect input data may
cause infinite loops, which cannot be handled. Only if MAS is 
still producing output you may press the ESC key, which will cause a 
fatal error\index{fatal error}.
In other cases you must rely on the reset button (or some software 
monitors providing hotkeys).

As you may have noticed in the above example, there is also a
{\bf debug} option. Typing `d' will take you to the command loop
of a debug processor. It is usually a restricted form of
the main MAS command loop. The commands entered must be in 
LISP\index{LISP} syntax\index{syntax} to emphasize its role as 
emergency\index{emergency} aid. New errors 
produced during debugging\index{debugging} count higher and may 
very quickly lead to total program abort. 
Beside these considerations you can use almost all LISP functions,
especially you can list variable contents or modify variables.
Finally typing `EXIT\index{EXIT}' takes you back to the 
error prompt.  


\section{Talking LISP}

Not all LISP constructs have an equivalent in the 
MAS language\index{language}, 
e.g. the `DM' define macro\index{macro} is not available in the 
MAS language.
So it can be necessary to switch to LISP by calling the 
\verb/PRAGMA(LISP)/ procedure which switches  
the parser\index{parser} to LISP syntax.
\index{PRAGMA}\index{LISP}\index{MODULA}
To return to Modula style input\index{input} you must use the 
\verb/(PRAGMA MODULA)/
procedure in LISP syntax\index{syntax} to switch the 
MAS parser back on. 

\begin{verbatim}
       MAS:  PRAGMA(LISP).         (* switch to LISP *)
       ANS:  ()                 
       LISP: (SETQ a 5)            (* use LISP syntax now *)
       ANS: 5
       LISP: (PRAGMA MODULA)              (* switch to MAS *)
       ANS: ()
\end{verbatim}

A macro\index{macro} example for those who miss a FOR--statement:
\index{FOR}

\begin{verbatim}
      PRAGMA(LISP).

      (DM FOR (X)
          (LIST (QUOTE PROGN)
                (CAR  (CDR X)) 
                (LIST (QUOTE WHILE)
                      (CAR (CDR (CDR X)))
                      (LIST (QUOTE PROGN)
                            (CAR (CDR (CDR (CDR (CDR X)))))
                            (CAR (CDR (CDR (CDR X))))
                            ) ) ) )

      (PRAGMA MODULA)

      a:=0.
      FOR( SETQ(i,0), LEQ(i,10), SETQ(i,i+1), SETQ(a,a+i*i) ).

      ANS: 11
\end{verbatim}

The syntax\index{syntax} is similar to the syntax of the 
FOR--statement in C.
Only the executed statement must be included in the 
parameter list  of the FOR macro\index{macro}:

\begin{verbatim}
      FOR(init,cond,step,stat)  ==  (FOR init cond step stat)
\end{verbatim}

The semantics of the FOR macro is defined by the following 
WHILE statement:

\begin{verbatim}
      init; WHILE cond DO stat; step END  ==
      (PROGN init (WHILE cond (PROGN stat step)))
\end{verbatim}

The MAS language\index{language} (like Modula--2) does not allow 
assignments as expressions, so all parameters\index{parameter} 
of the FOR macro must be calls of the SETQ\index{SETQ} 
function or expressions.
In C\index{C} the FOR statement would be:

\begin{verbatim}
      FOR( i:=0, i <= 10, i:=i+1) a:=a+i*i
\end{verbatim}

The evaluation can be traced using the \verb/TRACE/ procedure
which turns the trace flag in the evaluator ON and OFF.

