
% The document below is a draft manual of Logic & Objects on IC Prolog ][
% A more complete version will be available soon. 
% For any comments or suggestions email to 'zb@doc.ic.ac.uk'
% Last update: 19 Nov 92


\documentstyle[12pt]{article}
\newcommand{\lno}{{\em L\&O\/}}
\newcommand{\f}{\tt}
\def\blh{\char'134}

\begin{document}

\begin{center}
{\large {\bf 
{\em \huge L \& O} 
\\
on IC PROLOG ][
\\
User's Guide DRAFT
\\
Z.Bobolakis 
\\
email:zb@doc.ic.ac.uk}}
\end{center}


\section{Introduction}

In this chapter, Logic \& Objects ({\lno} for short) on top of IC PROLOG ][ is
presented. It is not intended as a complete description of {\lno} but as a
user's guide to the system. {\lno} is defined in detail in the book {\em
Logic \& Objects\/} by F.G.McCabe, Prentice Hall, 1992. What is presented in
the following section is {\em only\/} an outline of some important concepts.

{\lno} is an extension to Prolog which supports an object-oriented notation.
An object consists of a {\em label\/} which identifies it (the label may be
parametrized) and program which defines its behaviour. The program describing
its behaviour is a Prolog program with some additional features. The most
important features will be described here.



\section{{\lno} programs}

\subsection{Object definitions}

An {\lno} object is defined as follows:
\begin{verbatim}
        Label: { Program }.
\end{verbatim}
{\f Label} is a Prolog atom or compound term which identifies the object. 
{\f Program} is a set of clauses which can be one of the following:
\begin{description}
\item[Relation definitions] Relations can be defined for the object locally 
using ordinary Prolog clauses. Standard Prolog syntax applies here, but the
body of a clause can  contain specific kinds of calls which are defined in
{\lno}. The following clauses are an example of relation definitions in
an object\footnote{The calls in the body will be explained later.}:
\begin{verbatim}
            age(Ag).
            likes(X) :- X:age(A),A<Ag.
            likes(X) :- X:likes(self).
\end{verbatim}


\item[Equations] Equations are used for defining functions. 

An example of equation is:
\begin{verbatim}
        route_length(T)=0 :-atom(T).
\end{verbatim}
or
\begin{verbatim}
        no_of_legs=2.
\end{verbatim}

The function (on the LHS of the head) evaluates to the value (on the RHS of
the head) if the body of the clause succeeds. If there is no body, it is
enough that the call unify with the LHS of the head. A function can be defined
using more than one clauses but the equations should
not overlap in defining the function\footnote{Otherwise they do not define
a function in the strict sense.}. Guaranteeing this, is not a mere
syntactic checking, so the responsibility for it lies with the programmer.


\item[Variable initializations] for example:
\begin{verbatim}
        foible:=34.
\end{verbatim}

Such variables in {\lno} are mutable, i.e. their value can change during the
execution of the program. The effect of the above clause is to assign the
variable to the value at the time the object is created, i.e. when the program
is loaded or consulted.

\end{description}


A call in the body of a clause can be:
\begin{description}
\item[Prolog call] It can be a call to an ordinary Prolog relation, built-in 
or user-defined, or to a relation defined within the same object. In both
cases the call is executed as an ordinary Prolog call\footnote{Inheritance can
also be used for such a call, see later for inheritance.}.

\item[A labelled call] for example
\begin{verbatim}
        animal:mode(X)
\end{verbatim}

The general form of a labelled call is 
\begin{verbatim}
        Label:Call
\end{verbatim}
A labelled call is a call to another object. {\f Label} ({\f animal} in the
example above) is an object and {\f Call} ({\f mode(X)} in the example) is 
a call to a predicate defined in that object. 


\item[A special {\lno} call] for example
\begin{verbatim}
        self:mode(X)
\end{verbatim}
or
\begin{verbatim}
        super:mode(X)
\end{verbatim}
Special calls will be presented later in this section.
\end{description}




\subsection{Inheritance}

Apart from object definitions, an {\lno} program can also contain inheritance
definitions. Different kinds of inheritance can be defined:
\begin{description}
\item[Ordinary inheritance] is defined as follows:
\begin{verbatim}
        L <= M.
\end{verbatim}
where {\f L} and {\f M} are two objects, for example
\begin{verbatim}
        horse <= animal.
\end{verbatim}
The effect of this rule is that any call of the form {\f horse:Call} can be
transformed to the call {\f animal:Call}. Therefore, the definition of the
relation specified in {\f Call} in {\f horse} is augmented with the 
corresponding definition in {\f animal}.

\item[Overriding inheritance] can be  defined as follows:
\begin{verbatim}
        L << M.
\end{verbatim}
for instance
\begin{verbatim}
        horse << animal.
\end{verbatim}
In this case, a call {\f horse:Call} is transformed to {\f animal:Call} 
but only if
the predicate to which {\f Call} is a call is not defined in the object {\f
horse}.
\item[Differential inheritance] relationships are defined as follows:
\begin{verbatim}
        L <= M-Preds.
\end{verbatim}
or
\begin{verbatim}
        L << M-Preds.
\end{verbatim}
for example
\begin{verbatim}
        bird <= animal-mode(walk).
\end{verbatim}
In this case, {\f bird} inherits {\f animal} except for calls of the form \\
{\f bird:mode(walk)}.
\end{description}



\subsection{Expressions}

Prolog provides the ability to use expressions in programs but in a clumsy
and not natural way. A variable should be used and the value of the variable
should be assigned to the expression's result after an explicit evaluation
using the {\f is} primitive. For example, instead of 
\begin{verbatim}
        ..., foo(X+1), ... 
\end{verbatim}
the programmer should write
\begin{verbatim}
        ..., X1 is X+1, foo(X1), ...
\end{verbatim}
This is only possible for primitive functions (such as {\f +/2}). For a 
user-defined function, a relation should be defined and called explicitly, 
for example, instead of defining the function {\f length/1} which returns 
the length of a list, one would write:
\begin{verbatim}
        length([], 0).
        length([_|X], N) :- ...
\end{verbatim}
and call it as follows:
\begin{verbatim}
        ..., length(List, L), foo(L), ... 
\end{verbatim}
instead of
\begin{verbatim}
        ..., foo(length(List)), ...
\end{verbatim}

{\lno} provides this ability to use expressions which can be evaluated.
In particular, built-in functions are provided as well as the ability
for the user to define functions.

In practice though (for various reasons), the kinds of expressions that 
are evaluated by the {\lno} system are more restricted. 

In particular, an expression is evaluated if:
\begin{itemize}
\item Its functor is a built-in function. The built-in functions are 
listed later in this chapter. Therefore, a call of the form
\begin{verbatim}
	p(2+3, length([a,b,c]))
\end{verbatim}
is the same (unlike in Prolog) as
\begin{verbatim}
        p(5, 3)
\end{verbatim}

\item It is explicitly labelled, i.e. it uses an equation defined in a
  different object. For example
\begin{verbatim}
	horse:no_of_legs
\end{verbatim}
is evaluated using the definition for {\f no\_of\_legs} in the object
{\f horse}.

\item It is a mutable variable, for example:
\begin{verbatim}
	p(c)
\end{verbatim}
is interpreted as {\f p(V)} where {\f V} is the current value of a mutable
variable {\f c}, if such a variable exists in the object (i.e. if there
exists an initialization clause for the variable).

\end{itemize}

{\lno} provides a `quote' operator {\f ` }  which prevents the expression 
on which it is
applied from being evaluated. So if an equation for {\f f(X)} in an object
defines {\f f(X) = 2*X}, then the expression {\f f(4)} evaluates to {\f 8}
while {\f `f(4)} is not evaluated, it stands for {\f f(4)} as a Prolog term.

Moreover, an `unquote' operator is provided, namely {\f \#}, which enforces
evaluation of the expression it is applied to, allowing so nested expressions.

Finally, the quote-hash operator {\f `\#} causes the function symbol of an
expression to be quoted while each of the arguments is unquoted. So the
expression {\f `\#(X+Y < Z-W)} is equivalent to {\f `(\#(X+Y) < \#(Z-W))},
where only the expressions {\f X+Y} and {\f Z-W} are evaluated.
 


\subsection{Special {\lno} calls}

\subsubsection{{\f self} and {\f super}}

\paragraph{The {\f self} keyword}

A call in the body of a clause in an object can have the form
\begin{verbatim}
        self:Call
\end{verbatim}
In order to see how the call is evaluated, consider an example:
\begin{verbatim}
person:{
        child :- self:age(X),
                 X < 18.
}.

tom:{
        age(14).
}.

tom <= person.
\end{verbatim}

Consider now the call
\begin{verbatim}
        tom:child
\end{verbatim}
This call cannot succeed using any clause in {\f tom}. Because {\f tom}
inherits {\f person}, the call is transformed to {\f person:child}. This call
is now tried in the object {\f person} using the clause for {\f child}. In the
body of the clause, {\f self:age(X)} has to be solved. This call is tranformed
to {\f tom:age(X)} because {\f self} refers to the original object that the
call originated before the inheritance. The last call succeeds binding {\f
X} to {\f 14} and the original call succeeds as expected.

More generally, {\f self} is a keyword which evaluates to the object to which
the call originated before inheritance transformations and can be used not
only as a label but in any place in a call.

When a call is transformed to another one through inheritance, {\f self} does
not change, it evaluates to the same value as before the transformation. On
the other hand, when a call like {\f tom:child} is made, {\f self} during the
evaluation of this call becomes {\f tom}, no matter what it was before.


\paragraph{The {\f super} label}

{\f super} can be use as a label to transfer the evaluation of a call from
the current object to one which it inherits. {\f super} cannot be used but as
a label.


\subsubsection{Broadcasting}

A call can be broadcasted to more than one objects and the
results can be combined in different ways to evaluate the result to the
broadcasted call.

\begin{description}
\item[filter broadcasting] A call of the form
\begin{verbatim}
        &^(L,C,M).
\end{verbatim}
returns a binding for {\f M} which is a sublist of {\f L}, namely those
elements {\f O} of the list for which {\f O:C} is true.
A functional notation can also be used, i.e.
\begin{verbatim}
        &^(L,C)
\end{verbatim}
evaluates to the filtered list.

\item[and-casting] A call of the form
\begin{verbatim}
        L&:C.
\end{verbatim}
succeeds iff for all {\f O} on the list {\f L}, {\f O:C} is true.

\item[or-casting] A call of the form
\begin{verbatim}
        L\:C.
\end{verbatim}
succeeds iff for some {\f O} on the list {\f L}, {\f O:C} is true.
\end{description}

\subsubsection{Variable assignment}

A mutable variable (defined by an initialization in the definition of an
object) can be assigned a new value using a call of the form:
\begin{verbatim}
        Variable := Expression
\end{verbatim}
where {\f Variable} is the variable and {\f Expression} evaluates to
its new value. {\f Expression} can contain the variable itself (as in 
an imperative language) allowing thus assignments like
\begin{verbatim}
        c := c+1
\end{verbatim}
 

\subsection{An example {\lno} program}

Consider the following program which describes an animal-world.
\begin{verbatim}
person(Ag) : {           
    age(Ag).           
    likes(X) :- X:age(A),A<Ag.
    likes(X) :- X:likes(self).
    no_of_legs=2.

    foible := 34
            }.
person(Ag)<<animal.
\end{verbatim}
In this object, {\f person(Ag)} is the label. The label is parametrized
({\f Ag} is interpreted here as the age of the person). Notice that the 
label arguments are global variables with respect to the program defining
the object. So the clauses  {\f age(Ag).} and {likes(X) :- X:age(A),A<Ag.}
can access this variable.

{\f age/1} and {\f likes/1} are relations for the object, while 
{\f no\_of\_legs=2.} defines a function (which happens to take no arguments,
i.e.\@it is a constant). On the other hand {\f foible := 34} initializes
a mutable variable.

A person (of any age) is also defined to inherit the object {\f animal} 
(defined later)
using overriding inheritance. Thus, although an animal (as we will see)
has 4 legs, a person has only 2 because {\f no\_of\_legs} is defined in
{\f person(Ag)} and therefore the definition is not inherited from {\f animal}.

 
\begin{verbatim}
tom <= person(32).
frank <= person(37).
\end{verbatim}
{\f tom} and {\f frank} are defined to inherit one instance of {\f person}
each. Their age is automatically defined through this inheritance.


\begin{verbatim}
animal:{
   mode(walk) :- self:no_of_legs>=2.
   mode(run) :- self:no_of_legs=2.
   mode(gallop) :- self:no_of_legs=4.
   mode(slither) :- self:no_of_legs=0.
   no_of_legs=4.
   }.
\end{verbatim}
For the object {\f animal}, the relation {\f mode/1} is defined. Its definition
uses the function {\f no\_of\_legs/0}. Notice that the calls to the function
use the keyword {\f self} and threfore
are executed using the definition of the particular animal we are refering to,
not {\f animal} in general. So {\f mode(X)} for a horse will use the 
definition of {\f no\_of\_legs} in {\f horse} while if the expression to
be evaluated is {\f animal:no\_of\_legs} then {\f no\_of\_legs=4} is used (as
in {\f animal}.


\begin{verbatim}
mammal : {
   mode(walk) :- self:no_of_legs>=2
   }.

mammal <= animal.
reptile <= animal.

horse <= mammal.
horse : {
   no_of_legs=4
   }.

beauty <= horse.
beauty : {
   mode(fly).
   }.

bird : {
   mode(fly).
   no_of_legs=2
   }.
bird <= animal.

penguin <= bird-[mode(fly)].
penguin : {
   mode(swim).
   }.
\end{verbatim}
Here, we define {\f penguin} to inherit {\f bird}. The inheritance is 
differential, so although for {\f bird} it is defined that {\f mode(fly)},
{\f penguin} does not inherit it. {\f mode(swim)} is defined for 
{\f penguin}.




\section{The {\lno} system}

\subsection{Starting {\lno} in IC-PROLOG ][}

Once ICP is has started, {\lno} can be loaded using the command
\begin{verbatim}
	[lo].
or
        ensure_loaded(lo).
\end{verbatim}
{\lno} files are now recognized and consulted/compiled.

\subsection{{\lno} file handling}

{\lno} programs should be included in files which have the extension {\f .lo}.
At this stage, {\lno} and ordinary Prolog code should not be mixed in the
same file.
The IC PROLOG ][ compiler can invoke a user-defined preprocessor to read the
source file and produce Prolog code which the compiler itself takes as input.
The {\lno} preprocessor is hooked to the compiler in this way.
The file extension is an indication to the compiler that the file to be
compiled is a special one and the {\f .lo} extension is reserved for {\lno}
for this purpose\footnote{In this way, IC PROLOG ][ provides the facility to
write any preprocessor and redirect its output to the standard Prolog
compiler.}.

{\lno} files are compiled using the same Prolog commands as with ordinary
Prolog files. For example, the file called {\f animals.lo} (which
contains the example program presented in the previous section)
can be consulted using:

\begin{verbatim}
| ?- consult(animals).
\end{verbatim}

Prolog will add the missing ending to the filename. Notice here that if a {\f
animals.pl} file exists, it will be consulted instead of {\f animals.lo}
because {\f .pl} files have priority. In order to avoid conflict, full
filename should be used in such cases, i.e.

\begin{verbatim}
| ?- consult('animals.lo').
\end{verbatim}

All conventions that hold for standard Prolog files also hold here, e.g.
filenames contaning {\f .} or {\f /} should be quoted, absolute filenames
(i.e. the ones that include the path) should contain the {\f .lo} extension
etc.

A file can also be consulted using square brackets, i.e. as follows:

\begin{verbatim}
| ?- [animals].
\end{verbatim}

Once a file has been consulted and subsequently modified, it should be
reconsulted using {\f reconsult/1} as in

\begin{verbatim}
| ?- reconsult(animals).
\end{verbatim}
or using
\begin{verbatim}
| ?- [-animals].
\end{verbatim}
(square brackets with a {\f -} preceding the filename).

Alternatively, {\f compile/1} and {\f load/1} should be used if optimized
compilation is preferred. These primitives behave as in standard Prolog, but
the comments made above for {\f consult/1} and {\f reconsult/1} also hold
here.

The differences between ordinary and optimized compilation hold here exactly
as with ordinary Prolog files.




\subsection{{\lno} query evaluation}

{\lno} queries have the form
\begin{verbatim}
        Label:Call
\end{verbatim}
where {\f Label} is an object label and {\f Call} is a call to a predicate
defined in {\f Label}.

{\lno} queries behave as usual Prolog queries (returning bindings, multiple
solutions etc).

In the simplest case, {\f Label} is ground and {\f Call} is a non-variable. It
can also be the case that {\f Label} is not ground. In this case, {\lno}
replies with bindings on variables occuring in {\f Label}, so that {\f Label}
is an object for which {\f Call} holds.

It is not allowed though that {\f Call} be a variable, it should be a
predicate call.

For example,
\begin{verbatim}
| ?- horse:mode(X).

X = walk ;

X = walk ;

X = gallop ;

no
\end{verbatim}
and
\begin{verbatim}
| ?- X:mode(gallop).

X = animal ;

X = beauty ;

X = horse ;

X = mammal ;

no
\end{verbatim}
are valid {\lno} queries and give the corresponding solutions while
\begin{verbatim}
| ?- horse:X.
\end{verbatim}
is not valid.


{\lno} queries can also be ones that evaluate expressions\footnote{How
expressions are evaluated is discussed later.}. In particular, they
can have the form
\begin{verbatim}
        Expression =? Value.
\end{verbatim}
The above query, evaluates {\f Expression} and unifies it with {\f Value}. The
query can also be given in a different form:
\begin{verbatim}
        Expression =? .
\end{verbatim}
It is important that in the last case {\f =?} and {\f .} are separated by a
space character. Otherwise a syntax error occurs.

The first form (using {\f =?} as infix) is necessary when the query is given
in a context where {\f Value} is a variable shared with other subqueries. 

For example, in the animals' program we can ask:
\begin{verbatim}
| ?- beauty:no_of_legs =? .
4

yes
\end{verbatim}
because {\f beauty} is a {\f horse} which has 4 legs and
\begin{verbatim}
| ?- penguin:no_of_legs =? .
2

yes
\end{verbatim}
because {\f penguin} is a {\f bird} (except for its {\f mode}) and therefore
has 2 legs.
because


\subsection{Dynamic code in {\lno} programs}

As in ordinary Prolog programs, programs can be modified dynamically in 
{\lno}. There are though some restrictions to what can be 
modified dynamically. This will be explained in this section.

\subsubsection{Adding new programs}

Objects, programs or rules can be asserted using the {\f assert\_object}
primitive. The primitive can be used as following:
\begin{itemize}
\item An object can be asserted by a call {\f assert\_object(L:B)} where
{\f L} is the label of the object and {\f B} is a program included in 
{\f \{\}}, that is, using the same syntax as with static objects. The
only difference is that the last clause in the program {\f B} should not
be followed by {\f '. '} as in static programs.
The object asserted should not already exist.
\item One or more clauses can be asserted to an already existing {\em
dynamic\/} object, using the call {\f assert\_object(L:B)}. Again, {\f L}
is the label and {\f B} is either a single clause or a set of clauses
Included in {\f \{\}}.
\item A new inheritance rule can be asserted using the call  \\
{\f assert\_object(L<=R)} or {\f assert\_object(L<<R)}. The objects need not
be dynamic. 
\end{itemize}

The restrictions in the kind of programs asserted are:
\begin{itemize}
\item No expressions are allowed in the objects.
\item No equations are allowed.
\item {\f self} can only be used as a label in explicitly labelled calls
in the body of a clause.
\end{itemize}

\subsubsection{Retracting programs}

Clauses or rules (not complete objects) can be retracted using the  \\
{\f retract\_object}
primitive. The primitive can be used as following:
\begin{itemize}
\item A clause can be retracted from an already existing {\em
dynamic\/} object, using the call {\f retract\_object(L:B)}. Again, {\f L}
is the label of the object and {\f B} is the clause to be retracted.
\item An inheritance rule can be retracted using the call \\ 
{\f retract\_object(L<=R)} or {\f retract\_object(L<<R)}. but the rule 
retracted should have been asserted dynamically.
\end{itemize}





\subsection{Debugging {\lno} programs}

{\lno} in ICP, provides a debugging facility for tracing queries.

\subsubsection{How the {\lno} tracer works}

The Prolog tracer might be used for {\lno} programs since the {\lno} 
preprocessor produces Prolog code. The problem is that the output from the
preprocessor is not in a form easy to understand from the {\lno} programmer's
point of view.

The {\lno} tracer is not implemented as an ordinary metainterpreter on 
programs. Instead, at the preprocessing/compilation phase, information
related to tracing is introduced to the program in the form of hooks.
 
Different kinds of hooks exist corresponding to different kinds of events
that might happen during the execution of an {\lno} query. In particular, the
hooks introduced in the Prolog code that is output by {\lno}, uses the
following hooks:
\begin{itemize}
\item {\f \#r\#} The initial entry to a relation in a class body.
\item {\f \#e\#} The entry to a clause for a call.
\item {\f \#s\#} The successful exit from a clause.
\item {\f \#f\#} The initial entry to a function in a class body.
\item {\f \#q\#} The entry to an equation or function.
\item {\f \#v\#} The completion of an equation.
\item {\f \#i\#} The use of an inheritance rule.
\item {\f \#d\#} The initialization of a dynamic variable.
\item {\f \#a\#} The reassignment of such a variable.
\item {\f \#u\#} A user specified print statement. This hook is compiled in
\item {\f \#l\#} The entry to a labelled variable call.
\item {\f \#k\#} Evaluation of a labelled expression.
when the programmer has inserted a {\f trace} ({\em message\/}) subgoal
into the body of a clause or equation. The {\em message\/} is printed
out in the trace of the execution whenever this hook is activated.
\end{itemize}

In this way, the programmer can activate some of the hooks only. Moreover,
a different interface for the tracer can be adapted to it (by
redefining the hooks only), as the one provided in this version is 
relatively low level.

In order for a hook to be invoked during the execution of a query, it has
to:
\begin{itemize}
\item be compiled in the code
\item be activated at the time of execution.
\end{itemize}
This means that the user can compile as many hooks as needed in the program
and then temporarily activate/deactivate any of them. 


\subsubsection{Using the {\lno} tracer}

\paragraph{Setting the tracing mode}

Which of the hooks are compiled by the preprocessor depends on a set of
flags being set. The flags are the following:
\begin{itemize}
\item {\f entry}
\item {\f user}
\item {\f exit}
\item {\f fail}
\item {\f redo}
\item {\f clauses}
\item {\f equations}
\item {\f inheritance}
\item {\f dynamic\_code}
\item {\f percentfs} ({\small restricted use - only for low-level programming})
\end{itemize}

Notice that the flags do not correspond one-to-one to the hooks. For example,
in order to trace a clause, the {\f clause} flag should be {\f on} and 
some of {\f entry}, {\f exit}, {\f fail}, {\f redo} depending on which
points the user needs to trace it (normally all of them).

The flags can be set on/off using the following primitives:
\begin{itemize}
\item {\f lo\_trace} sets all tracing flags (except {\f percentfs}) on.
\item {\f lo\_notrace} sets all tracing flags (except {\f percentfs}) off.
\item {\f tracing(X,Y)} sets all the flags on {\f X} and {\f Y} and the rest
  of them off. {\f X} should be a sublist of \\{\f [entry,exit,fail,redo]} and
  {\f Y} a sublist of \\ {\f
  [clauses,equations,inheritance,dynamic\_code,percentfs, \\user]}.
\item {\f tracing(X)} has the same effect as \\ {\f
  tracing([entry,exit,fail,redo],X)}.
\end{itemize}

Once the flags have been set, the program should be compiled/consulted.
If at some stage the user wants to deactivate/reactivate some of the
tracing hooks, the corresponding flags should be set on/off. This can be
done using the {\f tracing/1} or {\f tracing/2} primitives. 

Notice here 
that only hooks that have been compiled can be activated or deactivated. Flags
can be set on or off but the corresponding hooks are only modified at 
compilation.

For example, if before compiling a file the query {\f tracing([clauses])}
has been given, only clauses (at all points: entry, redo, exit, fail)
will be traced. 

If after compilation the user gives {\f tracing([clauses, 
equations])}, it will have no immediate effect, as {\f clauses} is 
already set on and {\f equations} related hooks have not been compiled. 

Though, the flag {\f equations} will be set on and if the program is 
compiled again, it will cause the equations related hooks to be activated 
(unless {\f equations} is set off before this compilation).

If on the other hand the user gives {\f tracing(off)} (which is the same
as {\f tracing([],[])}) or {\f tracing([])}, then {\f clauses} will be set 
off and, although the
hook is compiled, the clauses will not be traced. 

A subsequent call
{\f tracing([clauses])} will set {\f clauses} on again and, because the 
related hook is compiled, clauses {\em will\/} be traced.


\paragraph{Tracing a query}

When the tracing mode has been set, a query can be traced. The query is
given as usually and the system traces any activated hooks in the code and
reports them. The reporting information includes:
\begin{itemize}
\item the object currently active (and {\f self} if it is different 
from the object)
\item the type of the traced point ({\f enter}ing a relation/clause/equation 
etc, {\f redo}ing, {\f exit}ing successfully, {\f fail}ing, {\f report}ing
and inheritance rule)
\item the traced point ({\f clause}, {\f relation} etc.)
\end{itemize}

At every step, the system waits until a command is given. A command can 
be one of the following:
\begin{itemize}
\item `{\f c}' or {\em return\/} to continue with the next step.
\item `{\f s}' to skip the tracing of the current goal (allowed only 
when entering a call/clause/etc).
\item `{\f f}' to fail the current goal.
\item `{\f q}' to abort the top level query.
\item `{\f h}' for help (display these options)
\end{itemize}
If an illegal command is given then the tracer insists until a legal one
is given.

\subsubsection{An example using the tracer}

We now present and explain an {\lno} session using the tracer.  

\begin{verbatim}
laotzu(22)% icp

IC-Prolog ][ version 0.93  -   05 Nov 1992
(c) Imperial College 1992, Imagine Project

{consulting system.pl ...} 

| ?- ensure_loaded(lo).
{consulting lo.pl ...} 
{consulting looperators.pl ...} 
loading loenv.icp ... ok
loading lolow_level.icp ... ok
loading lodynamic.icp ... ok
loading lotranslator.icp ... ok
loading lotracing.icp ... ok
loading loexpressions.icp ... ok
loading lotop.icp ... ok

yes
| ?- [animals].
{consulting animals.lo ...} 

yes
| ?- lo_trace.

yes
| ?- beauty:mode(X).

X = fly ;

X = walk ;

X = walk ;

X = gallop ;

no
\end{verbatim}
Here, although the tracing mode has been set, the source file has been
consulted before, so the compiled code contains no calls to the hooks.
So we need to reconsult (the {\f lo\_trace} call should have preceded the
{\f [animals]} call).
\begin{verbatim}
| ?- [-animals].
{consulting animals.lo ...}

yes
| ?- beauty:mode(X).
enter(relation) beauty:(mode _45) ?
enter(clause) beauty:(mode fly) ?
exit(clause) beauty:(mode fly) ?

X = fly ;
redo(clause) beauty:(mode fly) ?
report(inherit) beauty:(beauty << horse) ?
report(inherit) horse/beauty:(horse << mammal) ?
enter(relation) mammal/beauty:(mode _45) ?
enter(clause) mammal/beauty:(mode walk) ?
report(inherit) beauty:(beauty << horse) ?
enter(function) horse/beauty:no_of_legs ?
enter(equation) horse/beauty:no_of_legs ?
exit(equation) horse/beauty:(no_of_legs = 4) ?
exit(clause) mammal/beauty:(mode walk) ?

X = walk ;
redo(clause) mammal/beauty:(mode walk) ?
report(inherit) mammal/beauty:(mammal << animal) ?
enter(relation) animal/beauty:(mode _45) ?
enter(clause) animal/beauty:(mode walk) ?
report(inherit) beauty:(beauty << horse) ?
enter(function) horse/beauty:no_of_legs ?
enter(equation) horse/beauty:no_of_legs ?
exit(equation) horse/beauty:(no_of_legs = 4) ?
exit(clause) animal/beauty:(mode walk) ?

X = walk ;
redo(clause) animal/beauty:(mode walk) ?
enter(clause) animal/beauty:(mode run) ?
report(inherit) beauty:(beauty << horse) ?
enter(function) horse/beauty:no_of_legs ?
redo(clause) animal/beauty:(mode run) ?
enter(clause) animal/beauty:(mode gallop) ?
report(inherit) beauty:(beauty << horse) ?
enter(function) horse/beauty:no_of_legs ?
enter(equation) horse/beauty:no_of_legs ?
exit(equation) horse/beauty:(no_of_legs = 4) ?
exit(clause) animal/beauty:(mode gallop) ?

X = gallop ;
redo(clause) animal/beauty:(mode gallop) ?
enter(clause) animal/beauty:(mode slither) ?
report(inherit) beauty:(beauty << horse) ?
enter(function) horse/beauty:no_of_legs ?
redo(clause) animal/beauty:(mode slither) ?
fail(relation) animal/beauty:(mode _45) ?
fail(relation) mammal/beauty:(mode _45) ?
fail(relation) beauty:(mode _45) ?

no
\end{verbatim}
Now the hook calls have been compiled in the code, so the tracer works. The
example above is the full tracing of the query {\f beauty:mode(X)}. Since 
everything is traced ({\f lo\_trace} call sets all flags on), all ports are 
reported ({\f enter}, {\f report}, {\f redo}, {\f exit}, {\f fail}) in all
the cases (clauses, equations, inheritance etc). If we now change the tracing
mode to trace only clauses, we have:
\begin{verbatim}
| ?- tracing([clauses]).

yes
| ?- beauty:mode(X).
enter(relation) beauty:(mode _45) ?
enter(clause) beauty:(mode fly) ?
exit(clause) beauty:(mode fly) ?

X = fly ;
redo(clause) beauty:(mode fly) ?
enter(relation) mammal/beauty:(mode _45) ?
enter(clause) mammal/beauty:(mode walk) ?
exit(clause) mammal/beauty:(mode walk) ?

X = walk 
\end{verbatim}
which causes clauses only to be traced (not equations, inheritance etc). 
This is obvious if we compare the traces of the query for the first
two solutions.
Although the calls to the hooks are still in the compiled code, they are
deactivated (except for the ones related to clauses).
\begin{verbatim}
| ?- [-animals].
{consulting animals.lo ...}

yes
| ?- tracing([equations]).

yes
\end{verbatim}
After the above queries, the only hook calls compiled are the ones for 
clauses (they were set on at the consultation time) but the only flags
set on are the ones for clauses. As a result, we should expect that nothing
will be traced.
\begin{verbatim}
| ?- beauty:mode(X).

X = fly ;

X = walk
| ?- [-animals].
{consulting animals.lo ...}

yes
| ?- beauty:mode(X).

X = fly ;
enter(function) horse/beauty:no_of_legs ?
enter(equation) horse/beauty:no_of_legs ?
exit(equation) horse/beauty:(no_of_legs = 4) ?

X = walk
\end{verbatim}
After reconsulting, equations-related hook calls are compiled (and the 
corresponding flags are set on) so the above query shows (as expected) that
only equations are traced.
\begin{verbatim}
| ?- tracing(all).

yes
| ?- penguin:no_of_legs=? .
enter(function) bird/penguin:no_of_legs ?
enter(equation) bird/penguin:no_of_legs ?
exit(equation) bird/penguin:(no_of_legs = 2) ?
2

yes
\end{verbatim}
Now, although although all flags are set on, only equations-related hooks
calls are compiled so only equations are traced. 
 
Finally, we will see the effect of possible responses to the tracer (in
the example above $<${\em return\/}$>$ was always the response which caused
tracing to proceed step-by-step.

\begin{verbatim}
| ?- [-animals].
{consulting animals.lo ...}

yes
| ?- beauty:mode(X).
enter(relation) beauty:(mode _45) ? 
enter(clause) beauty:(mode fly) ? 
exit(clause) beauty:(mode fly) ? 

X = fly ;
redo(clause) beauty:(mode fly) ? s

Options :
  <CR> - continue
   c   - continue
   s   - skip goal (only at entry)
   f   - fail goal
   q   - abort query
   h   - display this list

redo(clause) beauty:(mode fly) ? 
report(inherit) beauty:(beauty << horse) ? 
report(inherit) horse/beauty:(horse << mammal) ? 
enter(relation) mammal/beauty:(mode _45) ? s
exit(clause) mammal/beauty:(mode walk) ? 

X = walk ;
report(inherit) mammal/beauty:(mammal << animal) ? f
fail(relation) mammal/beauty:(mode _45) ? 
fail(relation) beauty:(mode _45) ? 

no
\end{verbatim}
Notice that when {\f s} (for {\em skip\/}) was given at an inappropriate
call, the system insisted with the same call (and displayed the options).
Skipping at a later call (an {\f enter} call) caused the evaluation of
the query to be skipped until {\f exit}ing this call. One solution was given
but after more solutions were required, the user gave {\f f} which caused
the evaluation to fail.

Finally, aborting ({\f q}) is also an option:
\begin{verbatim}
| ?- beauty:mode(X).
enter(relation) beauty:(mode _45) ? 
enter(clause) beauty:(mode fly) ? 
exit(clause) beauty:(mode fly) ? 

X = fly ;
redo(clause) beauty:(mode fly) ? 
report(inherit) beauty:(beauty << horse) ? 
report(inherit) horse/beauty:(horse << mammal) ? 
enter(relation) mammal/beauty:(mode _45) ? 
enter(clause) mammal/beauty:(mode walk) ? 
report(inherit) beauty:(beauty << horse) ? q

--- ABORTED ---


Unbound variable : X
\end{verbatim}
which causes the whole evaluation to stop.

\subsection{{\lno} built-in primitives}

\subsubsection{Keywords}
{\f self} and {\f super} are {\lno} keywords and therefore they should not be
used for other purposes.

\subsubsection{Functions}

The following functions (with trhe corresponding arity) are built-in in
{\lno}:

\begin{description}
\item[Mathematical functions]
\begin{itemize}
\item {\f +/2} for addition (integer or floating point)
\item {\f -/2} for subtraction (integer or floating point)
\item {\f -/2} for multiplication (integer or floating point)
\item {\f / /2} for division (integer or floating point)
\item {\f mod/2} for the remainder of integer division
\item {\f \blh\ /1} for bitwise negation
\item {\f /\blh\ /2} for bitwise and
\item {\f \blh /\ /2} for bitwise or
\item {\f ++ /2} for integer addition
\item {\f -- /2} for integer subtraction
\item {\f ** /2} for integer multiplication
\item {\f // /2} for integer division
\item {\f sqrt/1} for square root of a number
\item {\f abs/1} for absolute value of a number
\item {\f int/1} for integer part of a number
\item {\f ln/1} for logarithm (base e)
\item {\f pwr/2} or {\f \^{}/2} for power ({\f pwr(N,M)} is the {\f M}th power
of {\f N})
\item {\f sin/1}
\item {\f cos/1}
\item {\f tan/1}
\item {\f atan/1} for arctan
\item {\f exp/1} for exponential function
\end{itemize}

\item[Other functions] Several primitive functions have the form {\f F/A} and
return what {\f F/A+1} would return in Prolog in the last argument. The
following built-in functions are provided:
\begin{itemize}
\item {\f concat/2} returns the concatenation of two strings
\item {\f name/1} and {\f pname/1} (see ICP built-in primitives)
\item {\f length/1} returns the length of a list
\item {\f nint/1} returns the nearest integer of a number
\item {\f -/1} returns the opposite of a number
\item {\f \&\^{}/1} (see definition of filter casting)
\item {\f max/2} for maximum
\item {\f min/2} for minimum

\end{itemize}

\end{description}





\subsubsection{Reserved operators}

{\lno} reserves some operators for special purposes, either for the language
itself or for the internal representation. The operators with special
interpretation are defined as follows:
\begin{itemize}

\item {\f op(1198,xf,'=?')}, {\f op(1198,xfx,'=?')}, {\f op(698,fx,`)}, \\
  {\f
  op(698,fx,\#)} and {\f op(698,fx,`\#)} are used for expression
  evaluation.
\item {\f op(699,xfx,\&\^{ })}, {\f op(700,xfx,'\&:')} and
  {\f op(700,xfx,\blh :)} are used for broadcasting.
\item {\f op(700,xfx,':=')} is the assignment operator (assigns a mutable
  {\lno} variable to a value).
\item {\f op(1198,xfx,'<=')} and {\f op(1198,xfx,'<<')} are used for
  inheritance declarations.
\item {\f op(1200,yfy,'. ')} and {\f op(1200,xfy,'..')} are used as clause
  separators in a class body.
\item {\f op(699,fx,':')} is also reserved for internal representation.
\end{itemize}


\newpage
\appendix

\section{Implementation of the tracer hooks}

Here we present in brief the way the tracer hooks are implemented. For the
method by which the tracer is built, see the discussion in the corresponding
section above.

Depending on the environment used, the tracer may be implemented in a 
different way, by changing only the definitions of the hooks.

For each hook call that is introduced in the Prolog code produced by {\lno},
it is initially checked (using the {\f is\_traced/1} calls to flags) whether 
the related flags are set on (i.e.\@ whether
the hook is active or not) and, if they are, a dialogue is invoked with
parameters depending on the type of the hook. The dialogue is invoked using
the {\f trace\_dialogue/5} call. The arguments passed to the 
{\f trace\_dialogue/5} predicate are the following (as they are ordered):
\begin{itemize}
\item The type of hook, in fact the information displayed to the user, e.g.\@ 
{\f enter(relation)}.
\item Information about the position in the source code in the form \\
{\f '@x'(Id,P,IX,C)} where {\f Id} is the name of the source file, {\f P}
is the position of the current object in the file (as the position of the
first character of the label), {\f IX} is the order of the clause within 
the object and {\f C} is the order of the Prolog clause for the Prolog
predicate output from the preprocessor. This is not always possible since 
some hooks do not correspond to a particular clause in the source code 
(e.g.\@when entering a relation call) and in this case {\f true} is the 
value passed in this argument. All this information can be used for
a source-level debugging interface (which is not provided now). 
\item The {\f self} of the current object.
\item The label of the current object.
\item The call traced (also displayed to the user).
\end{itemize}
 
\subsection{Code for the tracer hooks}

\begin{itemize}
\item {\f \#r\#} The initial entry to a relation in a class body.
\begin{verbatim}
'#r#'(A,L,S):- 
   is_traced(clauses),is_traced(entry),!,
   (trace_dialog(enter(relation),true,S,L,A);
   trace_dialog(fail(relation),true,S,L,A),fail).
'#r#'(_,_,_).
\end{verbatim}

\item {\f \#e\#} The entry to a clause for a call.
\begin{verbatim}
'#e#'(A,L,S,C):- 
   is_traced(clauses),is_traced(entry),!,
   (trace_dialog(enter(clause),C,S,L,A);
   trace_dialog(redo(clause),C,S,L,A),fail).
'#e#'(_,_,_,_).
\end{verbatim}

\item {\f \#s\#} The successful exit from a clause.
\begin{verbatim}
'#s#'(A,L,S,C):- 
   is_traced(clauses),is_traced(exit),!,
   trace_dialog(exit(clause),C,S,L,A).
'#s#'(A,L,S,C):- 
   skip_trace(S,L,A),!,   
   '#s#'(A,L,S,C).
'#s#'(_,_,_,_).
\end{verbatim}

\item {\f \#f\#} The initial entry to a function in a class body.
\begin{verbatim}
'#f#'(E,L,S):- 
   is_traced(equations),is_traced(entry),!,
   trace_dialog(enter(function),true,S,L,E).
'#f#'(_,_,_).
\end{verbatim}

\item {\f \#q\#} The entry to an equation or function.
\begin{verbatim}
'#q#'(E,L,S,C):-  
   is_traced(equations),is_traced(entry),!,
   trace_dialog(enter(equation),C,S,L,E).
'#q#'(_,_,_,_).
\end{verbatim}

\item {\f \#v\#} The completion of an equation.
\begin{verbatim}
'#v#'(EX,R,L,S,C):-  
   is_traced(equations),is_traced(exit),!,
   trace_dialog(exit(equation),C,S,L,EX=R).
'#v#'(EX,R,L,S,C):-
   skip_trace(S,L,EX),!,
   '#v#'(EX,R,L,S,C).
'#v#'(_,_,_,_,_).
\end{verbatim}

\item {\f \#i\#} The use of an inheritance rule.
\begin{verbatim}
'#i#'(L,M,_,C,S):-  
   is_traced(inheritance),is_traced(entry),!,
   trace_dialog(report(inherit),C,S,L,(L<<M)).
'#i#'(_,_,_,_,_).
\end{verbatim}

\item {\f \#d\#} The initialization of a dynamic variable.
\begin{verbatim}
'#d#'(V,R,L,S,C):- 
   is_traced(dynamic_code),is_traced(entry),!,
   trace_dialog(report(declare),C,L,S,V:=R).
'#d#'(_,_,_,_,_).
\end{verbatim}

\item {\f \#a\#} The reassignment of such a variable.
\begin{verbatim}
'#a#'(L,V,R,C):- 
   is_traced(dynamic_code),is_traced(entry),!,
   trace_dialog(report(assign),C,L,L,V:=R).
'#a#'(_,_,_,_).
\end{verbatim}

\item {\f \#l\#} The entry to a labelled variable call.
\begin{verbatim}
'#l#'(A,L,S):- 
   is_traced(clauses),is_traced(entry),!,
   (trace_dialog(entry(relation),true,S,L,A);
   trace_dialog(fail(relation),true,S,L,A),fail).
'#l#'(_,_,_).
\end{verbatim}

\item {\f \#k\#} Evaluation of a labelled expression.
\begin{verbatim}
'#k#'(E,L,S):-
   is_traced(equations),is_traced(entry),!,
   trace_dialog(entry(function),true,S,L,E).
'#k#'(_,_,_).
\end{verbatim}

\item {\f \#u\#} A user specified print statement. 
\begin{verbatim}
'#u#'(M,L,C,S):- 
   is_traced(user),is_traced(entry),!,
   trace_dialog(report(user),C,S,L,M).
'#u#'(_,_,_,_).
\end{verbatim}

\end{itemize}

\subsection{The tracing dialogue}

{\f trace\_dialogue} is implemented as explained here. The possible 
responses of the user are:
\begin{itemize}
\item {\f Help} in a non-standard response (none of the below).
\item {\f Quit} in which case the query is aborted (using {\f abort/0}).
\item {\f Continue} in which case the call succeeds.
\item {\f Fail} in which case the call is enforced to fail (using {\f fail/0}).
\item {\f Skip} which is more complicated. It is important here that any
implementation of the reaction to a {\f Skip} response be compatible with
the implementation of the hooks. {\f Skip} is only valid when {\f enter}ing
a call and {\f trace\_dialogue} should check that (reject an invalid {\f Skip}
message and, either insist or react in a default manner, e.g.\@{\f Continue}).
If the {\f Skip} response is valid, it should deactivate the hooks, save the
tracing mode (i.e.\@which flags are set on/off) and succeed. Saving the 
tracing mode is done using the calls
\begin{verbatim} 
   is_tracing(T),
   set_prop('#tracing#','#mode#',trace(Sf,LbL,Call,T)), 
\end{verbatim}
which checks which flags are set on and uses the IC PROLOG ][ properties 
database to save the state. ({\f Sf} is the self of the current object,
{\f LbL} is its label, {\f Call} is the current call and {\f T} is the
tracing mode. 
Of course, the tracing mode should be recovered later on, when the call 
skipped has succeeded. The implementation of the hooks should ensure that
this is done (that is what we meant by `compatibility'  a few lines above.
Only the {\f \#s\#} and {\f \#v\#} hooks need to recover the tracing mode.
In our implementation, this is done through the {\f skip\_trace(S,L,A)}
call which is defined as:
\begin{verbatim}
skip_trace(S,L,A):-
  get_prop('#tracing#','#mode#',trace(S,L,A,T)),!,
  tracing(T),
  del_prop('#tracing#','#mode#').
\end{verbatim}
This call, checks whether the call that it currently exits was skipped,
finds the previous tracing mode, resets it and removes any saved 
tracing mode related info. 
Notice here that these two actions (tracing mode saving and skip-checking while
exiting) should be implemented in any tracer interface, although not 
necessarily in this way. 
\end{itemize}





\end{document}











