@c -*-texinfo-*-
@node Tracer, Operators, Foreign Interface, Top
@comment  node-name,  next,  previous,  up
@chapter Prolog Tracer User Guide 

@cindex debugging
@cindex tracing
When programs do not work as expected, the next step is to use a Prolog 
tracer to trace through the execution step by step. Our tracer uses an 
extended set of the four port model described by Clocksin and 
Melish @cite{Programming in Prolog}, Springer Verlag.

The tracer knows about the following eight ports: call, exit, redo, fail, unify,
try_match, succeed_match, and fail_match. On invoking the tracer the first
five of these are set on leash.  Leashed ports are always echoed, and skipping
and unleashing are allowed at call and redo ports only. At leashed ports the
`?' prompt awaits for the user to take action by typing one of
@kbd{@key{RET} s u n a e l p d !}
The effect is as follows:

@table @kbd
@item @key{RET} creeping takes place
@item s
the current goal is skipped
@item u
the current goal is unleashed
@item n
the trace continues by
@item a
tracing is aborted
@item e
the predicate set_leashes is called
@item l
the predicate set_lechoes is called
@item p
information is displayed indicating the ports that are currently
  leashed/echoed
@item d
the ICP debugger is entered
@item !
the user is allowed to solve a prolog query. On the user selecting
  this option the tracer types ! and awaits for a prolog query to be typed at
  the terminal. Once the query has been solved, control returns to the tracer.
@end table

@table @code
@item trace
@findex trace/0
Turns the tracer on. All top level queries will be traced.

@item notrace
@findex notrace/0
Turns the tracer off.

@item set_echoes
@findex set_echoes/0
Gives the user the opportunity to turn echoes on or off on any of the tracer's
ports.

set_echoes types the message `...ports to be leashed?' and awaits for the
user to type a term of the form @kbd{<Ports>}:

@table @kbd
@item <Ports>
::=  all | none | <PortSeq>
@item <PortSeq>
::= <Port> | -<Port> | <Port>,<Ports> | -<Port>,<Ports>
@item <Port>
::= call | exit | redo | fail | try_match | succeed_match | fail_match
@end table

If the term is `all' then the echo is set to be on all the tracer's ports.

If the term is `none' then the echo and leash is set to be off on all tracer's
ports.

If the term has a subterm of the form <Port> then the echo is set to be on
on the corresponding port.

If the term has a subterm of the form -<Port> then the echo and leash are
set to be off on the corresponding port.

The port names call, exit, redo, fail, try_match, succeed_match, and
fail_match can be respectively abbreviated to c, e, r, f, tm, sm, and fm.


@item set_leashes
@findex set_leashes/0
Gives the user the opportunity to turn leashes on or off on any of the
tracer's ports.

set_echoes types the message `...ports to be leashed?' and awaits for the
user to type a term of the form <Ports> (see set_echoes).

If the term is `all' then the echo and leash is set to be on all the tracer's
ports.

If the term is `none' then the leash is set to be off on all tracer's ports.

If the term has a subterm of the form <Port> then the echo and leash are
set to be on on the corresponding port.

If the term has a subterm of the form -<Port> then the leash is set to be
off on the corresponding port.

@item ?? @var{+Goal}
@findex ??/1
@var{Goal} is traced.  This operator can be used to trace a single goal
when the tracer is off. Only dynamic code can be traced and if during a
trace a query for a static predicate is encountered, the query is solved
by a standard call to prolog.
@end table

