PLOGHELP SPY                                 Simon Nichols, October 1990

    ?- spy.
    ?- spy Spec.

How to set spy-points on predicates in order to debug them
and the options available at spy-ports.


    CONTENTS - (Use <ENTER> g to access required sections)

 -- Setting spy-points
 -- Setting spy-points from VED
 -- The procedure box model of Prolog execution
 -- Options available at a spy-port
 -- ... Changing the flow of control at the current port
 -- ... Changing the behaviour of the debugger
 -- ... Displaying the current goal and the current predicate
 -- ... Interrupting the current goal
 -- ... Getting help
 -- Changing the behaviour of the debugger
 -- Related documentation


-- Setting spy-points -------------------------------------------------

The evaluable predicate spy/0 causes spy-points to be placed on all
currently defined user predicates, except those whose names begin with
'prolog_' (which are typically defined by the Prolog system).

The single argument form spy/1 places a spy-point on all the predicates
specified by its argument Spec: this is either a predicate specification
of the form Name or Name/Arity, or a list of such specifications. Name
is an atom representing the function symbol of one or more predicates.
The following are examples of valid spy goals:

    ?- spy append.

    ?- spy append/3.

    ?- spy [member/2, append, rev/3].

When the Name is given without the Arity this refers to all predicates
with the given name (function symbol), regardless of their arity, which
currently have definitions. If there are no predicates defined which
match Spec, the Prolog top-level interpreter will inform you of this and
nothing will be done.

It is not possible to spy on system predicates.

You can find out whether a particular predicate has a spy-point set by
using predicate_info/2: see PLOGHELP * PREDICATE_INFO for details. You
can remove spy-points by means of the evaluable predicates nospy/0 and
nospy/1: see PLOGHELP * NOSPY.


-- Setting spy-points from VED ----------------------------------------

You can also set spy-points from the VED command line. Typing

    <ENTER> spy

to VED is the same as typing:

    :- spy.

to Prolog, while

    <ENTER> spy Spec

(where Spec is some valid predicate specification as described above) is
the same as:

    :- spy Spec.

Note that the VED commands don't have terminating full stops.


-- The procedure box model of Prolog execution ------------------------

The Poplog Prolog debugger uses the procedure box model of Prolog
execution to provide a simple way of illustrating the control flow of a
program. When a spy-point is placed on a predicate, information is
presented about the flow of control through the four ports (call, exit,
redo and fail) of the procedure box. These four ports represent the
significant events (or critical points) in the execution of a Prolog
predicate. Whenever the control flow of a procedure with a spy-point set
reaches one of the ports, a debugging message is printed showing you the
invocation number, port and current goal, for example:

    ** (2) Call : append([b], [c, d], _2)?

The query shows you that the debugger is waiting for some response. User
interaction is only requested when leashing is turned on. Often the
response will be to continue (which is signaled by pressing the <RETURN>
key), but the following kinds of options are available to you:

    -- change the control flow at this port

    -- change the behaviour of the debugger at spy-ports

    -- display the current goal and the current predicate

    -- interrupt the current goal, temporarily or permanently


-- Options available at a spy-port ------------------------------------

The options available at a leashed spy-port are listed in detail below.
A note on terminology: the "current predicate" is the predicate
currently executing at a particular spy-port. In terms of the procedure
box model, control has reached one of the four ports of that predicate.
The "current goal" is the goal which caused the current predicate to be
invoked.


-- ... Changing the flow of control at the current port ---------------

c   Continue to the next port. <RETURN> has the same effect.

;   Backtrack:  transfers control to the redo port of the current
    predicate, i.e. it causes the current predicate to backtrack.

f   Fail: transfers control to the fail port of the current predicate,
    i.e. it causes the current predicate to fail.

r   Retry: this can only be used at the exit port of a predicate. It
    transfers control to the call port of the current predicate.


-- ... Changing the behaviour of the debugger -------------------------

s   Skip:  this is only valid at the call or redo ports of a predicate.
    It skips over the execution of the predicate, i.e. you will not see
    anything until control returns to the current predicate at either
    the exit port or the fail port.

o   Off:  switches debugging off. The evaluable predicate nodebug/0 has
    the same effect. See PLOGHELP * NODEBUG.

u   Unleash: this turns off prompting at spy-ports. Only debugging
    messages will be printed. The evaluable predicate unleash/0 has the
    same effect. See PLOGHELP * LEASH, * UNLEASH.


-- ... Displaying the current goal and the current predicate ----------

l   Listing: lists the clauses for the current predicate.

p   Prints the  current goal, using print/1. See PLOGHELP * PRINT.

w   Prints the current goal, using write/1. See PLOGHELP * WRITE.

d   Prints the current goal, using display/1. See PLOGHELP * DISPLAY.


-- ... Interrupting the current goal ----------------------------------

a   Abort: aborts the current execution, returning to the Prolog top
    level. This is the same as the evaluable predicate abort/0.

b   Break: calls the evaluable predicate break/0 which creates a new
    invocation of the top level. The execution so far is effectively
    suspended, but will be resumed back at the debugging prompt when you
    type the end of file character.

e   Exit from Poplog. Warning: if you do this by mistake, you will lose
    your work.  However, it does ask you first, and if you really want
    to exit, answer "yes".


-- ... Getting help ---------------------------------------------------

?   Displays a summary of options valid at the current port.

h   Help: displays this file.


-- Changing the behaviour of the debugger -----------------------------

The interaction described above is the default behaviour of the spy
debugger, but it can be changed. Spy-ports can be "unleashed", which
means that the debugger will still print a message there, but won't
prompt for a command; you can also elect to ignore a particular port or
ports, or define a different action altogether. For details, see
PLOGHELP * SPY_ACTION and PLOGHELP * UNLEASH, * LEASH.


-- Related documentation ----------------------------------------------

PLOGHELP * DEBUG
 Overview of the debugging facilities provided by Poplog Prolog

PLOGHELP * DEBUGGING
 Predicate which lists currently active spy-points

PLOGHELP * LEASH
 Predicate which enables user interaction at spy-ports

PLOGHELP * NOSPY
 Predicate which removes spy-points from specified predicates

PLOGHELP * QUIETSPY
 Predicate which disables the printing of messages when spy-points are
 set or removed

PLOGHELP * SPY_ACTION
 Predicate which changes the action of the debugger at spy-ports

PLOGHELP * UNLEASH
 Predicate which disables user interaction at spy-ports


--- C.all/plog/help/spy
--- Copyright University of Sussex 1992. All rights reserved. ----------
