UNSW PROLOG USER MANUAL

     This document describes a Prolog interpreter for VAX-11 and  PDP-11
computers running under the Unix operating system.  The original version
was written by L.M.  Pereira,  F.C.N.  Pereira  and  D.H.D.  Warren  for
DECsystem-10 Prolog.  It has been adapted for UNSW Prolog by Claude Sam-
mut.  The interpreter was written in C by Claude Sammut while he was  at
the  Department  of Computer Science, University of New South Wales.  He
was assisted by Shaun Arundell (UNSW) and later modifications were  sug-
gested by Alan Feuer, Bell Labs, Murray Hill.  Wherever possible we have
tried to make this system compatible with Prolog-10, however, there  are
significant differences and it should not be taken for granted that pro-
grams can be ported without change.

     This section provides an introduction to the syntax  and  semantics
of   a  certain subset of logic (`definite clauses', also known as `Horn
clauses'), and indicates how this subset forms the basis of Prolog.


     The data objects of the language are called `terms'.   A  term   is
either a `constant', a `variable' or a `compound term'.

     The constants include `integers' such as:

                            0 1   999   -512

     In UNSW Prolog, integers are restricted  to  the  range  -2^31   to
2^31-1 on the VAX and -2^15 to 2^15-1 on the PDP-11.

     Constants also include atoms such as:

                    a void   =   := `Algol-68'   []

     The symbol for an atom can be any  sequence  of  characters,  which
should  be  written  in quotes if there is possibility of confusion with
other symbols (such as variables, integers). As  in  conventional   pro-
gramming  languages,   constants   are  definite elementary objects, and
correspond to proper nouns in natural language.

     Variables are distinguished by an initial capital  letter   or   by
the initial character "_", eg.

                      X Value A   A1  _3   _RESULT

     If a variable is only referred to once, it does  not  need  to   be
named  and   may   be  written as an `anonymous' variable indicated by a
single underline character:
                                   _

A variable should be thought of as  standing for   some   definite   but
unidentified  object.    This  is   analogous to the use of a pronoun in
natural language.  Note that a variable  is  not  simply   a   writeable
storage   location   as  in  most programming languages;  rather it is a
local name for some data object.


                                 - 1 -


     The structured data objects of  the  language   are   the  compound
terms.  A compound  term  comprises  a `functor' (called the `principal'
functor of the term) and a  sequence of  one  or   more   terms   called
`arguments'. A functor is characterised by its `name', which is an atom,
and its `arity' or number of arguments.  For example the  compound  term
whose   functor  is named `point' of arity 3, with arguments X, Y and Z,
is written:

                              point(X,Y,Z)

Note that an atom is considered to be a functor of arity 0.


     Functors are generally  analogous  to  common  nouns   in   natural
language.    One   may  think  of  a  functor  as  a record type and the
arguments of a compound term as the  fields   of   a   record.  Compound
terms are usefully pictured as trees.  For example, the term:

                  s(np(john),vp(v(likes),np(mary)))

would be pictured as the structure:

        s
    /        \
np               vp
 |             /     \
john        v          np
            |          |
            likes      mary


   Sometimes it is convenient to write certain functors as `operators'.
2-ary functors may be declared as `infix' operators and 1-ary  functors
as `prefix' or `postfix' operators.  Thus it is possible to write, eg.

X+Y     (P;Q)     X<Y +X     P;

instead of:

+(X,Y)   ;(P,Q)   <(X,Y) +(X)   ;(P)

The use of operators is described fully in Section 1.4.

     An important class of data structures are the `lists'.  These   are
essentially   the   same  as  the  lists  of Lisp.  A list either is the
atom:

                                   []

representing the empty list, or is a compound term  with two   arguments
which   are   respectively the head and tail of the list.  Thus  a  list
of  the  first three  natural numbers  is is written, in a special  list
notation, as:

[1, 2, 3]

                                 - 2 -


The special list notation in the case when the tail of  a  list   is   a
variable is exemplified by:

[X, ..L] [a, b, ..L]

For compatibility with Prolog-10 the notation:

[X|L] [a, b | L]

may also be used.

     A fundamental unit of a logic program is the  `goal' or  `procedure
call'.  Examples are:

gives(tom,apple,teacher)   reverse([1,2,3],L)   X<Y


     A goal is merely a special kind of term,  distinguished   only   by
the context  in  which it appears in the program.  The (principal) func-
tor of a goal is called a `predicate'.  It corresponds roughly to a verb
in  natural  language, or to a procedure name in a conventional program-
ming language.

     A logic `program' consists  simply of  a  sequence  of   statements
called  `sentences',   which  are  analogous  to  sentences  of  natural
language.  A sentence comprises a `head' and a `body'. The  head  either
consists   of  a   single  goal  or  is  empty.   The body consists of a
sequence of zero or more goals (ie.  it too may be empty). If  the  head
is not empty, the sentence is called a `clause'.

     If the body of a clause is non-empty,  the  clause  is   called   a
`non-unit clause', and is written in the form:

                 P :- Q, R, S.

where P is the head goal and Q, R and S are the goals which make  up the
body.  We can read such a clause either `declaratively' as:

                 "P is true if Q and R and S are true."

or `procedurally' as:

             "To satisfy goal P, satisfy goals Q, R and S."


     If the body of a clause is empty, the clause  is  called  a   `unit
clause', and is written in the form:

                                   P.

where P is the head goal.  We interpret this declaratively as:

                              "P is true."

and procedurally as:
                         "Goal P is satisfied."

                                 - 3 -


     A sentence with an empty head is called a `directive', of which the
most important kind is called a `question' and is written in the form:

                                 P, Q ?

where P and Q are the goals of the body.  Such   a   question  is   read
declaratively as:
                          "Are P and Q true?"

and procedurally as:
                        "Satisfy goals P and Q."


     Sentences generally contain variables.  Note  that   variables   in
different   sentences  are completely independent, even if they have the
same name - ie.  the `lexical scope' of a variable  is  limited   to   a
single   sentence.    Each   distinct  variable in  a sentence should be
interpreted as  standing  for  an  arbitrary entity,   or   value.    To
illustrate   this,   here   are  some  examples of  sentences containing
variables, with possible declarative and procedural readings:

(1)     employed(X) :- employs(Y,X).

"Any X is employed if any Y employs X."

"To find whether a person X is employed,
find whether any Y employs X."

(2)     derivative(X,X,1).

"For any X, the derivative of X with respect to X is 1."

"The goal of finding a derivative for the expression X
with respect to X itself is satisfied by the result 1."

(3)     ungulate(X), aquatic(X) ?

"Is it true, for any X, that X is an ungulate and X is
aquatic?"

"Find an X which is both an ungulate and aquatic."


     In any program, the  `procedure'  for a particular predicate is the
sequence   of  clauses   in   the  program  whose  head goals  have that
predicate as principal functor.  For example,  the   procedure   for   a
ternary    predicate   `append'   might   well   consist   of  the   two
clauses:

append([X,..L1],L2,[X,..L3]) :- append(L1,L2,L3).
append([],L,L).

where `append(L1,L2,L3)' means "the list L1 appended with the list L2 is
the list L3".

                                 - 4 -


     Certain predicates are predefined by `built-in procedures' supplied
by    the    Prolog   system.  Such  predicates  are  called `evaluable
predicates'.

     As we have seen, the goals in the body of a sentence are linked  by
the operator `,' which can be interpreted as conjunction ("and").  It is
sometimes convenient to use an additional  operator  `|',  standing  for
disjunction ("or"). (The precedence of `|' is such that it dominates `,'
but is dominated by `:-'). An example is the clause:

grandfather(X,Z) :-
     (mother(X,Y) | father(X,Y)), father(Y,Z).

which can be read as:

"For any X, Y and Z,
     X has Z as a grandfather if
     either the mother of X is Y or the father of X is Y,
     and the father of Y is Z.

     Such uses of disjunction can always be eliminated  by  defining  an
extra predicate - for instance the previous example is equivalent to:

grandfather(X,Z) :- parent(X,Y), father(Y,Z).
parent(X,Y) :- mother(X,Y).
parent(X,Y) :- father(X,Y).

- and so disjunction will not be mentioned  further  in  the  following,
more formal, description of the semantics of clauses.

     Note: For compatibility with Prolog-10 `;'  may  also  be  used  to
represent `or'.

     The semantics of definite clauses should be fairly clear  from  the
informal  interpretations already given.  However it is useful to have a
precise definition.  The `declarative semantics' of  definite  clauses
tells   us   which   goals  can be  considered true according to a given
program, and is defined recursively as follows.

    A goal is `true' if it is the head of some clause instance and  each
of   the  goals  (if  any) in  the body of that clause instance is true,
where an `instance' of a clause (or term) is obtained  by  substituting,
for  each  of  zero  or  more  of  its  variables,  a  new  term for all
occurrences of the variable.

     For example, if a program contains the  preceding   procedure   for
`append', then the declarative semantics tells us that:

                         append([a],[b],[a,b])

is true, because this goal is the head of a certain  instance   of   the
first clause for `append', namely,

              append([a],[b],[a,b]) :- append([],[b],[b]).

and we know that the only goal in the body of this clause  instance   is
true,   since  it  is an instance of the unit clause which is the second
clause for `append'.
                                 - 5 -


 
     Note that the declarative semantics makes  no  reference   to   the
sequencing  of  goals within the body of a clause, nor to the sequencing
of clauses within a program. This sequencing  information  is,  however,
very  relevant   for   the `procedural semantics'  which Prolog gives to
definite clauses.  The procedural semantics defines   exactly  how   the
Prolog   system   will execute a goal, and the sequencing information is
the means by which the Prolog programmer directs the system  to  execute
his   program  in  a sensible way.  The effect of executing a goal is to
enumerate, one by one, its true instances.  Here then  is   an  informal
definition of the procedural semantics.

     To `execute' a goal, the system searches for the first clause whose
head `matches' or `unifies'  with  the goal.  The `unification'  process
finds the  most  general common  instance  of  the  two  terms, which is
unique if it exists. If a match is found, the matching  clause  instance
is then `activated' by executing in turn, from left to right, each of the
goals  (if  any) in its body. If at any time the system  fails to find a
match for a goal, it `backtracks', ie. it   rejects  the  most recently 
activated  clause,  undoing any substitutions made by the match with the
head of the clause.   Next  it  reconsiders  the  original  goal   which
activated  the  rejected  clause,  and tries to find a subsequent clause
which also matches the goal.

     For example, if we execute the goal expressed by the question:

                          append(X,Y,[a,b]) ?

we  find  that  it  matches  the  head  of  the   first    clause    for
`append',  with X instantiated to [a, ..X1]. The new variable X1 is con-
strained by the new goal produced,  which  is  the  recursive  procedure
call:
                            append(X1,Y,[b])

Again  this  goal  matches  the  first  clause,  instantiating   X1   to
[b, ..X2], and yielding the new goal:

                           append(X2, Y, [])

Now this goal will only match the second clause, instantiating  both  X2
and  Y to []. Since there are no further goals to be executed, we have a
solution:
                    X = [a, b]
                    Y = []
ie.  a true instance of the original goal is:

                       append([a, b], [], [a, b])

If this solution is rejected, backtracking will generate   the   further
solutions:
                    X = [a]
                    Y = [b]

                    X = []
                    Y = [a,b]
in that order, by re-matching, against the second clause  for  `append',
goals already solved once using the first clause.

                                 - 6 -





     Besides the sequencing of goals and clauses, Prolog  provides   one
other   very   important  facility  for  specifying control information.
This is the `cut' symbol, written `!'. It is  inserted  in the   program
just  like   a   goal, but is not to be regarded as part of the logic of
the program and should be ignored as far as the  declarative   semantics
is concerned.

     The  effect  of the  cut  symbol  is  as   follows.    When   first
encountered   as   a  goal,  cut  succeeds immediately.  If backtracking
should later return to the cut, the effect  is  to  fail   the   "parent
goal",   ie.   that goal which matched the head of the clause containing
the cut, and caused the clause to be activated.  In other   words,   the
cut  operation `commits' the system to all choices made since the parent
goal was invoked, and causes other alternatives to be  discarded.    The
goals   thus   rendered   `determinate' are  the parent goal itself, any
goals occurring before the cut in the clause containing the   cut,   and
any   subgoals   which  were   executed  during  the  execution of those
preceding goals.  Examples:

(1)     member(X,[X,..L]) :- !.
        member(X,[Y,..L]) :- member(X,L).

The only result produced by executing:

                         member(X, [a, b, c]) ?

is X = a, the other two potential solutions being discarded.

(2)     compile(S,R) :- parse(S,T), !, translate(T,R).

The procedure `compile' only calls `translate' for  the  first  solution
produced  by  `parse'. Alternative solutions which `parse' might produce
are discarded.

     The Prolog syntax caters for operators  of  three   main  kinds   -
infix, prefix  and postfix. Each operator has a `precedence', which is a
number from  1  to  1200.  The  precedence  is   used  to   disambiguate
expressions   where   the  structure  of  the  term  denoted is not made
explicit through the use  of  brackets.   The  general   rule,   in   an
otherwise  ambiguous  subexpression, is that it is the operator with the
HIGHEST precedence that is the principal functor.  Thus if `+'   has   a
higher precedence than `/', then

                           a+b/c     a+(b/c)

are equivalent. Note that parentheses  are  necessary  if  you  wish  to
write:
                                (a+b)/c

     If there are two operators in the subexpression having   the   same
highest  precedence, the  ambiguity must be resolved from the `types' of
the operators.  The possible types for an infix operator are:

                          xfx     xfy     yfx


                                  - 7 -





     With an operator of type `xfx', it is a requirement that  both   of
the  two  subexpressions which are the arguments of the operator must be
of LOWER precedence  than  the  operator  itself,  ie. their   principal
functors   must   be  of  lower  precedence, unless the subexpression is
explicitly  bracketed  (which  gives it   zero   precedence).  With   an
operator  of  type `xfy', only the first or left-hand subexpression must
be of lower precedence;  the second can be of the SAME   precedence   as
the main operator;  and vice versa for an operator of type `yfx'.

     For example, if the operators `+' and `-' both  have   type   `yfx'
and are of the same precedence, then the expression:

                               a - b + c
is valid, and means:

                                (a-b)+c

Note that the expression would be invalid if the  operators   had   type
`xfx', and would mean:

                                a-(b+c)

if the types were both `xfy'.

     The possible types for a prefix operator are:

                                fx    fy

and for a postfix operator they are:

                                xf    yf

The meaning of the types should be clear by  analogy  with   those   for
infix   operators.    As   an  example, if `-' were declared as a prefix
operator of type `fy', then:
                                 - - P

would be permissible. If  the  type  were `fx', the preceding expression
would not be legal, although:

                                  - P

would still be a permissible form.

     In UNSW Prolog, a functor named  NAME  is declared  as an operator
of type TYPE and precedence PRECEDENCE by the command:

                      op(PRECEDENCE, TYPE, NAME)!

The argument name can also be a list of names of operators of  the  same
type and precedence.


                                 - 8 -


     It is possible to have more than one operator of the   same   name,
so  long  as they are of different kinds, ie.  infix, prefix or postfix.
An operator of any kind may be redefined by a new declaration   of   the
same  kind.  This   applies  equally  to operators which are provided as
standard in UNSW Prolog, namely:

op(1200, xfx, :-)!
op(1200,  fx, [:-, ?-])!
op(1200,  xf, [?, !])!
op(1100, xfy, ['|', ';'])!
op(1050, xfy, ->)!
op(700,  xfx, [=, ==, /=, is, <, >, =<, >=])!
op(700,   fx, [load, unload, trace, untrace, ed, ef, em])!
op(500,  yfx, [+, -])!
op(500,   fx, [+, -])!
op(400,  yfx, [*, /])!
op(300,  xfx, mod)!

Note that the  arguments  of  a  compound  term   written   in  standard
syntax  must  be expressions of precedence BELOW 1000. Thus it is neces-
sary to bracket the expression `P:-Q' in:

                             assert((P:-Q))

     Note carefully the following syntax restrictions, which  serve   to
remove potential ambiguity associated with prefix operators.
(1) In a term written in standard syntax, the  principal   functor   and
its   following   `('  must  NOT be separated by any intervening spaces,
newlines etc.  Thus:
                             point (X,Y,Z)
is invalid syntax.
(2) If the argument of a prefix operator starts with a `(',   this   `('
must  be   separated   from  the operator by at least one space or other
non-printable character.  Thus:

                             :-(p | q) , r.

is invalid syntax, and must be written as eg.

                            :- (p | q) , r.

(3) If a prefix  operator  is  written  without  an  argument,   as   an
ordinary   atom,   the  atom  is  treated  as  an expression of the same
precedence as the prefix operator, and  must  therefore   be   bracketed
where necessary.  Thus the brackets are necessary in:

                                X = (?-)

     A further source of ambiguity in Prolog is  arises from the ability
to define infix and prefix operators with the same name.  In some Prolog
systems, these operators would be considered identical.  In UNSW Prolog,
this  is  not  the  case.  For example, in C, there is a prefix operator
`++' and also a postfix operator  `++'  which  have  slighlty  different
functions.  If we declare:

op(300, fx, ++)!
op(300, xf, ++)!
                                 - 9 -



Then we are creating two completely distinct atoms (which are also  dis-
tinct  from  the atom `++' which is not an operator).  If an operator is
to be referred to outside of its normal context as a  principal  functor
of  a  compound term then, the operator must be preceded by a type name.
For example:

X =.. [infix +, 1, 2]?
X = 1 + 2

This uses the infix operator `+' to create a new compound term using the
`univ' predicate.  Similarly:

X =.. [prefix ++, x]?
X = ++ x

X =.. [postfix ++, x]?
X = x ++

     To run Prolog under the Unix operating system type:

$ prolog FILE1 FILE2 ...

FILE1, FILE2, ... 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.

     When the files are loaded the system responds with  a  prompt  `:'.
The user may then enter programs or type in commands.

     The -s option may also be specified in the command line.  For exam-
ple,
                       $ 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.

     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.

     To input a program from a file FILE inside Prolog,  give  the  com-
mand:
                               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.

                                 - 10 -



     Any characters following the `%' character on any line are  treated
as part of a comment and are ignored.

     When a file is loaded, a predicate of the form

                     file(FileName, ProcedureList)


is asserted to be true. `FileName' is the name of the  loaded  file and
`ProcedureList' 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 ProcedureList are first removed so that clauses in the
procedures are not duplicated.

     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).

     Directives are either commands or questions.  Both   are  ways   of
directing the system to execute some goal or goals.

     Suppose list membership has been defined by:

member(X, [X, .._]).
member(X, [_, ..L]) :- member(X, L).

Note the use of anonymous variables written "_". The command:

                     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.

     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 satis-
fied, the final  value  of   each   distinct   variable   is   displayed
(except  for anonymous  variables).

     The outcome of some questions is  shown below.

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
                                 - 11 -


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

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

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

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

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

would result in the response
                                 ** yes
                                 ** yes
                                 ** yes

If the goal is not satisfied, the system responds with `** no'.

     Note: For compatibility with Prolog-10 the  prefix  operators  `:-'
and `?-' may also be used for commands and questions.

     It is possible to edit procedures and files within Prolog.  To edit
the definition of a procedure, use the command:

                           ed ProcedureName!

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
`not' changed by ed.

   Files of procedures (also called `modules') may be edited  using  the
command:

                              em FileName!

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.

     Any file, whether it contains Prolog code or not may be  edited  by
using the command:

                              ef FileName!

As with `em', the text editor will be invoked automatically.  However
the file is `not' read by Prolog on exit from the editor.

     If your Unix 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
shell environment variable EDITOR.  This should be done  before  running
Prolog.

                                 - 12 -


     Once a program has been read, the interpreter will  have  available
all  the information necessary for its execution.

     A program may be saved on disk for future  execution.   To  save  a
program into a file FILE, perform the command:

                               save FILE!

     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,

                               load FILE!

     Execution of a program is started by  giving  the   interpreter   a
directive which contains a call to one of the program's procedures.

     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  <delete>  This
<delete> `interruption' has the  effect  of terminating the execution of
the command.  The system will then respond with a prompt.

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

     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.

     Tracing of procedure PROCEDURE is enabled by the command:

                            trace PROCEDURE!

A number of procedures may be traced by the command:

                       trace [proc1, proc2, ..]!

Tracing is disabled by the command:

                           untrace procedure!

and more than one procedure may be untraced by:

                      untrace [proc1, proc2, ..]!

     At the beginning of a line output by the  trace  procedure,  Prolog
prints either of the following:


C>
E<
F<
R>
                                 - 13 -



`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'.

     An example of tracing output is shown below:


f(A, b) :- g(A).

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

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

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

B = b.



     To exit from the interpreter  and  return  to  the  shell  type  ^d
(control d).

   Built-in procedures are also referred to as `evaluable predicates'.

     A total of twenty I/O streams may be open at  any  one   time   for
input   and  output.  These include the standard input, output and error
files.  A stream to a file F is opened for  input  by the first `see(F)'
executed.  F then becomes the current input stream.  Similarly, a stream
to file H  is  opened  for  output  by  the  first `tell(H)'   executed.
H   then   becomes   the  current   output  stream.  Subsequent calls to
`see(F)' or to `tell(H)' make F or H  the   current  input   or   output
stream,  respectively.   Any  input  or  output is always to the current
stream.

     When no input or output stream has been specified,  standard  input
and  output  are used.  Normally these are the user's terminal, however,
both input and output may be redirected in the  usual  way  in  Unix  by
using  `<'  and  `>' in the shell command.  When the terminal is waiting
for input on a new line, the prompt `:' is displayed.  [If the  standard
input file is not a terminal, no prompt is displayed]

     When the current output stream is closed, standard  output  becomes
the current output stream.  When the current input stream is closed, the
program file becomes the new input stream.  The program file may be  the
user's  terminal  or  a file loaded by the `load' directive or a file in
the shell command.

                                 - 14 -



   A file is referred to by its name, `written as an atom', eg.

        myfile
        '123'
        'fred.data'
        '/lib/prolog.lib'


     All I/O errors normally cause a failure of  the procedure and warn-
ings are issued on the standard error file.

     End of file is signalled when the predicate  `eof'  is  true.   Any
more   input  requests  for a file whose end has been reached return the
atom `end_of_file'.

consult(F)

     Instructs the interpreter to read-in the program which is  in  file
     F.   When   a directive is read it is immediately executed.  When a
     clause is read it is put after any clauses already  read   by   the
     interpreter   for  that  procedure. When a file has been consulted,
     a predicate file(F, PProc_List) is asserted. PProc_List is  a  list
     of the procedures defined in F.

unload F

     Retracts all procedures defined in F (according to the contents  of
     file(F,.PProc_list).  Also retracts file(F,.PProc_list).

load F

     same as consult, except unloads F first, i.e. prevents redefinition
     of procedures. It shouldn't matter if F had not been consulted pre-
     viously.

ed PP

     A listing of procedure PP is output to a temporary file.  The  text
     editor  is  the  called to allow the user to change the definition.
     When the editor is terminated, the file is read in causing the pro-
     cedure  to  be  redefined  if  no syntax errors were found.  If the
     interpreter discovered syntax errors, the user is asked if the pro-
     cedure is to be re-edited.  If the response is `n', the old defini-
     tion is restored.  Any other  response  causes  the  editor  to  be
     invoked again.

ef F

     edit file F.  The file is not read by Prolog.

em F

     Equivalent to : unload F, ef F, consult(F).

                                 - 15 -


file(F, PProc_list)

     Both F and PProc_list must be uninstantiated.   F  is  successively
     bound  to the names of consulted files.  PProc_list is bound to the
     list of procedure names defined in the respective files.

see(F)

     File F becomes the current input stream.

seeing(F)

     F is unified with the name of the current input file.

seen

     Closes current input stream.

read_from_this_file

     Unless `see' has changed the current input stream, all requests for
     input  use  the  standard input file.  Thus, when a read command is
     executed from a file being loaded by Prolog, the input  will  nor-
     mally  come  from  the  standard  input file, not the program file.
     `read_from_this_file' will cause the input to be taken from the
     program file instead of the standard input.

tell(F)

     File F becomes the current output stream.

telling(F)

     F is unified with the name of the current output file.

told

     Closes the current output stream.

close(F)

     File F, currently open for input or output, is closed.

eof

     Becomes true when the end of the  current  input  stream  has  been
     reached.

read(X)

     The next term, delimited by a `fullstop' (ie.  a `.'  followed   by
     <cr>   or   a  space),  is  read  from the current input stream and
     unified with X. The syntax of the term must accord   with   current
     operator  declarations.   If a call `read(X)' causes the end of the
     current input stream to be reached, X is unified  with   the   term
     `end_of-file'.   If  the  program requests input from the terminal,
     the user is prompted by the current  prompt  string.   The  default
     prompt is `> '.
                                 - 16 -


ratom(X)

     The next lexical token on the current input stream is bound  to  X.
     eg,

             ratom(X)?
             > fred
             X = fred.

             ratom(X)?
             > 123
             X = 123         % X is an integer

             ratom(X)?
             > <=
             X = <=

             ratom(X)?
             > ,
             X = ','


prompt(Ol.PPrompt, Ne.PPrompt)
     The current prompt string is bound to  Ol.PPrompt,  and  Ne.PPrompt
     becomes  the  new prompt string.  The goal `prompt(X, X)' binds the
     current prompt to X without changing it.   Note:  only  the  `read'
     prompt is changed.  The system prompt `: ' cannot be changed.

ask(Question, Answer)

     The user is prompted by the string Question.  The next token on the
     input stream is bound to Answer.

print(X, ...)

     `print' will accept a variable number of arguments,  printing  each
     term  on  the  same  line.  If an argument is a string (enclosed in
     `"') then the string is printed without quotes. This `print' may be
     used  to  output  messages.  A newline character is appended to the
     output.  The special character sequences `\n' and `\t'  are  recog-
     nized as newline and tab respectively.

prin(X, ...)

     Same as `print' except no newline is appended.

write(X)

     The term X is written to the current output stream   according   to
     current operator declarations.

nl

     A new line is started on the current output stream.

 
                                 - 17 -

 
 
getc(X)

     Unifies X with the next character in the current input stream.

skip(C)

     Skips to just after the next character C.
putc(X)

     The character X is output the the current output steam.

ascii(C, I)

     If C is a single character atom, I is  instantiated  to  the  ascii
     code  representing C.  If C is a variable and I is an integer, C is
     instantiated to the appropriate single character atom

tab(N)

     N spaces are output to the current output stream.  N  may   be   an
     integer expression.

rename(F,N)

     If file F is currently open, closes it and renames it to N.  If   N
     is `[]', deletes the file.

     Arithmetic is performed by  built-in  procedures   which  take   as
arguments  `integer  expression'  and  `evaluate'   them.   An  integer
expression is a term built from  `evaluable  functors',   integers   and
variables.    At   the  time  of evaluation, each variable in an integer
expression must be bound to an integer, or, for the  interpreter   ONLY,
to  an  integer  expression.

     Each evaluable functor stands for an  arithmetic  operation.    The
evaluable   functors   are   as follows,  where  X  and  Y  are  integer
expressions:

X+Y   integer addition

X-Y   integer subtraction

X*Y   integer multiplication

X/Y   integer division

X^Y    exponentiation (Y >_ 0).

X mod Y   X modulo Y

-X   unary minus

                                 - 18 -

 

The arithmetic built-in procedures are as follows, where X and  Y  stand
for arithmetic expressions, and Z for some term:

Z is X

     Integer expression X is evaluated and the result is unified with Z.
     Fails if X is not an integer expression.

X == Y

     The values of X and Y are equal.

X /= Y

     The values of X and Y are not equal.

X < Y

     The value of X is less than the value of Y.

X > Y

     The value of X is greater than the value of Y.

X <= Y

     The value of X is less than or equal to the value of Y.

X >= Y

     The value of X is greater than or equal to the value of Y.

     The comparison operations described in the  previous  section  also
apply to X and Y if the are instantiated to atoms.

(X, Y)

     X and Y.

X | Y also X; Y

     X or Y.

X = Y

     Defined as if by clause " Z = Z. ".

length(L,N)

     L must be instantiated to a list  of  determinate   length.    This
     length is unified with N.

findall(V, PP, L)

     Find all all terms, V, such that PP is true.  Append V to the list,
     L.  Findall uses backtracking to find all the solutions to PP.

                                 - 19 -

 
 
!
     See earlier description of cut.

not(PP)

     If the goal PP has a solution, fail,  otherwise  succeed.   It   is
     defined as if by:

     not(PP) :- PP, !, fail.
     not(_).

PP -> Q | R also PP -> Q; R
 
     Analogous to
                            "if PP then Q else R"

     i.e. defined as if by:

     PP -> Q | R :- PP, !, Q.
     PP -> Q | R :- R.

PP -> Q

     When occurring other than as one of the alternatives of a  disjunc-
     tion, is equivalent to:

                               PP -> Q | fail.
repeat

     Generates  an  infinite sequence  of   bactracking   choices.    It
     behaves (but doesn't use store!) as if defined by the clauses:

     repeat.
     repeat :- repeat.

fail

     Always fails.

true

     Always succeeds.


var(X)

     Tests whether X is currently instantiated to a variable.


nonvar(X)

     Tests whether X is currently instantiated to a non-variable term.

atom(X)

     Checks that X is  currently  instantiated  to  an   atom  (ie.    a
     non-variable term of arity 0, other than an integer).

                                 - 20 -

 

integer(X)

     Checks that X is currently instantiated to an integer.

atomic(X)

     Checks that X is currently instantiated to an atom or integer.

functor(T,F,N)

     The principal functor of term T has name F and arity N, where  F is
     either   an   atom  or,  provided  N  is 0, an integer.  Initially,
     either T must be instantiated to a non-variable, or F and  N   must
     be    instantiated    to,   respectively,  either  an  atom  and  a
     non-negative integer or an integer and 0. If these  conditions  are
     not  satisfied,  an error message is given.  In the case where T is
     initially instantiated to a variable, the result of the call  is to
     instantiate  T  to the most general term having the principal func-
     tor indicated.

arg(I,T,X)

     Initially, I must be instantiated to a positive integer and T  to a
     compound   term.  The result of the call is to unify X with the Ith
     argument of term  T.   (The   arguments   are   numbered   from   1
     upwards.)  If  the initial conditions are not satisfied or I is out
     of range, the call merely fails.

X =.. Y

     Y is a list whose head is the atom corresponding to  the  principal
     functor of X and whose tail is the argument list of that functor in
     X. eg.:

               product(0, N, N - 1) =.. [product, 0, N, N - 1]

     If X is instantiated to a variable, then Y must be  instantiated to
     a   list   of determinate length whose head is atomic (ie.  an atom
     or integer).

name(X,L)

     If X is an atom or integer then L is a list of  the  characters  of
     the name of X. eg.:

                     name(product, [p, r, o, d, u, c t])

     If X is instantiated to a variable, L must be instantiated   to   a
     list of characters.  eg.:

                           name(X, [f, r, e, d])?

     `name' is defined in terms of `concat' and `char'

                                 - 21 -



concat(L, A)

     The members of list L are concatenated to form  the  atom  A.   For
     example,

             concat([abc, def], X)?
             X = abcdef

             concat([f, r, e, d, 12], X)?
             X = fred12

     The members of L must be atoms or integers.  If X  is  instantiated
     then its value is compared with the result of the concatenation.

char(I, A, C)

     The Tth character of atom A is C.  I and A must be instantiated.

X

     If X is instantiated to a term which would be acceptable  as   body
     of   a   clause,   the  goal  X is executed exactly as if that term
     appeared textually in place of the X. In particular, any  cut (`!')
     occurring  in X is interpreted as if it occurred in the body of the
     clause containing X.  If X is not  instantiated  as  described  the
     clause fails.

assert(C)

     The current instance of C is interpreted as a clause and  is  added
     to   the  current   interpreted program (with new private variables
     replacing any uninstantiated variables). The position of  the   new
     clause   within  the procedure concerned is implementation-defined.
     C must be instantiated to a non-variable.

asserta(C)

     Like `assert(C)', except that the new clause  becomes   the   first
     clause for the procedure concerned.

assertz(C)

     Like `assert(C)', except that the new  clause  becomes   the   last
     clause for the procedure concerned.

clause(PP,Q)

     PP  must be  bound  to  a  non-variable term,   and   the   current
     interpreted  program is searched for clauses whose head matches PP.
     The head and body of those clauses  are unified  with  PP   and   Q
     respectively.    If  one of the clauses is a unit clause, Q will be
     unified with `true'.

                                 - 22 -

 

retract(C)

     The first clause in the current interpreted program that  matches C
     is erased.  C must be initially instantiated to a non-variable, and
     becomes unified with the value of  the  erased  clause.   The space
     occupied by  the  erased  clause  will  be recovered when instances
     of the clause are no longer in use.

retractall(PP)

     All clauses in the current interpreted program whose  head  matches
     PP are `retract'ed.  PP must be bound to a non-variable term.

pp A

     Lists in the current output stream all  the   interpreted   clauses
     for predicates with name A, where A is bound to an atom.

listing

     Lists in the current output stream all the clauses in  the  current
     interpreted program.

numbervars(X,N,M)

     Unifies each of the variables in term X with a special   term,   so
     that  `write(X)'  prints each of those variables as `_I', where the
     Is are consecutive integers from N to M-1.  N must be  instantiated
     to an integer.

ancestors(L)

     Unifies L with a list of ancestor goals for  the  current   clause.
     The   list   starts   with the  parent  goal and ends with the most
     recent ancestor coming from a `call' in a compiled  clause.

subgoal_of(S)

     The goal `subgoal_of(S)' is equivalent to the sequence of goals:-

     ancestors(L), in(S,L)

     where the predicate `in' successively matches  its  first  argument
     with  each of the elements of its second argument.
 
trace PP also trace [PPList]

     Enable tracing of single procedure PP or a list of procedures.  For
     example, to trace all the procedures defined in file `fred', type:

                           file(fred, L), trace L!

untrace PP also untrace .PPlist]

     Disable tracing of a single procedure PP  or  of  a  list  of  pro-
     cedures, PPlist.

                                 - 23 -



op(PPriority, Type, Name)

     Treat name Name as an operator of the stated Type   and  PPriority.
     Name  may  also  be  a  list  of  names in which case all are to be
     treated as operators of the  stated  Type  and PPriority.  If  Name
     is already an operator or list of operators, PPriority and Type are
     successively bound to the priority and type of Name.

save F

     The system saves the current procedure definitions  in  the  system
     into file  F.

statistics

     Display on the terminal statistics relating to  stack  usage
sh

     The Prolog session is suspended and a new shell is  forked.   When
     the shell terminates (by typing ^d), Prolog resumes.

system(ShellCommand)

     ShellCommand is an atom or string which is passed to the  shell  to
     executes as a normal Unix command.

     If UNSW Prolog was compiled with PRINC_VARS defined then  the  fol-
lowing is allowed:

f(1).

g(X, Y) :- X(Y).

g(f, X)?

X = 1

The principal functor of a compound term may be a variable.  Prolog will
perform  unification on the principal functor in the same way is it uni-
fies the arguments of a term.  Note that `X' must be bound before a goal
such as `X(Y)' can be satisfied.


                                 - 24 -