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 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 spy to VED is the same as typing: :- spy. to Prolog, while 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 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. 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. ----------