.NH
HOW TO USE THE INTERPRETER
.LP
To run Prolog under the AmigaDOS operating system type:
.DS C
1.PROLOG:> prolog file1 file2 ...
.DE
\fIfile1, file2\fR, ... contain Prolog programs which are
to be loaded before the user is asked to type
a command.
If a syntax error occurs in a file, the error
message will include the name of the file and the number of the line in
which it occurred.
.LP
When the files are loaded the system responds with a
prompt `:'.
The user may then enter programs or type in commands.
.LP
The \-s option may also be specified in the command line.
For example,

.ce
>1.PROLOG:> prolog \-s3000 file_name

This indicates that the variable stack is to increased
to 3000 units.
The default size is 1000.
This option should only be necessary when running
large programs.
.NH 2
Reading-in Programs
.LP
A  program  is  made  up  of  a sequence  of  clauses, possibly
interspersed with  directives  to  the interpreter. The clauses of a
procedure do not have to be immediately consecutive, but remember that
their  relative  order  may  be  important. The text of a program is
normally created separately in a file (or files), using the text editor.
.LP
To input a program from a file \fIfile\fR inside Prolog,
give the command:

.ce
load file!

which will instruct the interpreter to read-in the  program.  If  the
file name contains characters such as `.', its name is `prog.pl' say,
it is necessary to give the complete filename between quotes.
.LP
Any characters following the `%' character on any line are
treated as part of a comment and are ignored.
.LP
When a file is loaded, a predicate of the form

.ce
file(FileName, ProcedureList)

is asserted to be true.
\fIFileName\fR is the name of the loaded file and \fIProcedureList\fR
is a list of the names of the procedures defined in the file.
When the same file is loaded a second time, the definitions of
the procedures in \fIProcedureList\fR are first removed so that
clauses in the procedures are not duplicated.
.LP
Clauses may also be typed in directly at the terminal,  (although
this  is   only  recommended  if  the  clauses  will  not  be  needed
permanently, and are few in number).
.NH 2
Directives
.LP
Directives are either commands or questions.  Both  are ways  of
directing the system to execute some goal or goals.
.LP
Suppose list membership has been defined by:\-
.DS I
member(X, [X, .._]).
member(X, [_, ..L]) :\- member(X, L).
.DE
Note the use of anonymous variables written `_'. The command:\-

.ce
member(3, [1, 2, 3]), print(yes)!

directs the system to check whether 3 belongs to the list [1,@2,@3], and
to output "yes" if so.  Execution of a command terminates when all the
goals  in  the  command  have  been  successfully   executed.    Other
alternative  solutions  are  not  sought;  one may imagine an implicit
"cut" at the end of the command.  If no solution  can  be  found,  the
system simply returns with a prompt.
.LP
The syntax of a question is the same as a command, except that it
is ended by `?' instead of `!'. If the specified goal(s) can be
satisfied, the final value of  each  distinct  variable  is  displayed
(except  for anonymous  variables).
.LP
The outcome of some questions is  shown below.
.DS I
member(X, [tom, dick, harry])?
X = tom
X = dick
X = harry

member(X, [a, b, f(Y, c)]), member(X, [f(b, Z), d])?
Y = b
X = f(b, c)
Z = c

member(X, [f(_), g])?
X = f(_)
X = g
.DE

It is also possible to ask a question which involves no variables, for example,

.ce
member(3, [1, 2, 3])?

If the goal is satisfied, as would be the case in this example, then the system
responds
.ce
** yes

If the goal can be satisfied in more than one way, this response is repeated.
For example, the question

.ce
member(1, [1, 2, 3, 1, 1])?

would result in the response
.ce+3
** yes
** yes
** yes

If the goal is not satisfied, the system responds with `** no'.
.LP
\fINote:\fR For compatibility with Prolog-10 the prefix operators
`:\-' and `?\-' may also be used for commands and questions.
.NH 2
Editing Programs
.LP
It is possible to edit procedures and files within Prolog.
To edit the definition of a procedure, use the command:

.ce
ed \fBProcedureName\fR!

The procedure will be printed onto a temporary file and the
standard text editor will automatically be called by Prolog.
When the editor is exited, Prolog will replace the old definition
of the procedure with the edited form.
If the procedure had been loaded from a file, that file
is \fInot\fR changed by \fBed\fR.
.LP
Files of procedures (also called \fImodules\fR) may be edited using
the command:

.ce
em \fBFileName\fR!

The standard text editor will be invoked and the file may be 
changed.
On exit from the editor, the file will be reloaded.
Any changed made to the file will be permanent.
.LP
Any file, whether it contains Prolog code or not may be edited
by using the command:

.ce
ef \fBFileName\fR!

As with \fIem\fR, the text editor will be invoked automatically.
However, the file is \fInot\fR read by Prolog on exit from the editor.
.LP
If your system has more than one text editor, you can specify
which one Prolog is to use by assigning the name of the editor
to the environment variable EDITOR.
This should be done before running Prolog.
.NH 2
Saving A Program
.LP
Once a program has been read, the interpreter will have available
all  the information necessary for its execution.
.LP
A program may be saved on disk for future execution.
To save a program into a file \fIfile\fR, perform the command:

.ce
save \fBFile\fR!
.LP
The result is a text file which can be edited normally.
Procedures are listed in an arbitrary order.
The program can be restored later by executing,

.ce
load \fBFile\fR!
.NH 2
Program Execution And Interruption
.LP
Execution of a program is started by  giving  the  interpreter  a
directive which contains a call to one of the program's procedures.
.LP
Only when  execution  of  one  directive  is  complete  does  the
interpreter  become  ready  for  another  directive. However, one may
interrupt the normal execution of a directive by typing <CTRL-C>
This <CTRL-C>  \fIinterruption\fR  has the  effect  of terminating the
execution of the command.
The system will then respond with a prompt.
.LP
Execution may also be terminated if the program
runs out of stack space.
When this occurs, the user may save the current program
and reexecute Prolog with more stack space
by using the \-s option in the shell command.
.br
.ul
Warning:
make sure that the reason the program
ran out of stack space was not due to an error in your program
before increasing the size.
.NH 2
Tracing
.LP
The Prolog interpreter provides a tracing facility.
Procedures may be individually traced enabling each call the
procedure to be displayed
on the terminal with the  current  values  of  its  arguments.
.LP
Tracing of procedure \fIprocedure\fR is enabled by the command:\-

.ce
trace \fBProcedure\fR!

A number of procedures may be traced by the command:

.ce
trace \fB[proc1, proc2, ..]\fR!

Tracing is disabled by the command:

.ce
untrace \fBProcedure\fR!

and more than one procedure may be untraced by:

.ce
untrace \fB[proc1, proc2, ..]\fR!
.LP
At the beginning of a line output by the trace procedure, Prolog
prints either of the following:

.DS I
C>
E<
F<
R>
.DE

\&`C' indicates that a procedure is being called for the first time.
A line beginning with `E' shows the interpreter exiting a clause
after all the goals have been satisfied.
\&`F' indicates an exit from a clause due to a failure in satisfying
a goal.
After a failure, Prolog will attempt to redo a procedure call if there
are alternative clauses left in the procedure definition.
This is shown by an `R'.
.LP
An example of tracing output is shown below:

.DS I
f(A, b) :\- g(A).

g(A) :\- A = a.
g(c).

trace [f, g]!
f(c, B)?

C\||\|>f(c, b)
C\||\|\||\|>g(c)
R\||\|\||\|>g(c)
E\||\|\||\|<g(c)
E\||\|<f(c, b)

B = b.
.DE

.NH 2
Exiting From The Interpreter
.LP
To exit from the interpreter and return to the shell
type ^\ (control@\).
