Summary of function
===================

This tool is used to debug and trace the execution of ECLiPSe programs.  It
is based on a Box Model of execution, which is described in the User Manual.


Layout
======

Menu bar:

     Windows
          Raise top-level: this raises the toplevel window (be it the
             ECLiPSe toplevel or an application's, if the tool set is used
             from within that application). 
	  Predicate Browser: open/raise the predicate brower tool.
	  Delayed Goals: open/raise the delayed goals display window.
          Close tracer: quits the tracer and continue execution (if a query
             was executing).

     Options
	  Configure filter: Open a window that allows to specify multiple
	     filter conditions for continuing execution.
          Change print options: change the output mode (the way goals/terms
	     are printed or abbreviated) for the tracer. 
	  Analyze failure: Display information about the reason for the
	     most recent failure, and allow to jump to the corresponding
	     invocation number when the query is re-run.
	  Refresh goal stack now:  cause the call stack to be
	     refreshed, so that the ancestors of the current goal will
	     be displayed with their current bindings.  Their colour
	     is changed to blue to reflect that their bindings are
	     current.  This can be used to display ancestors that are
	     missing from the call stack, but note that if the refresh
	     is done at a fail port, then binding information may be
	     lost for some of the ancestors (from current goal up to
	     where there was a choice-point). 
          Refresh delayed goals at every trace line: if set, then this
             causes the delay goals displayed in the delay goals viewer to
             be updated at every trace line.

Call Stack:

    This is the execution call stack.  It shows the goal at the
    current trace line, and all its (viewable) ancestors. 

Command buttons:

    Buttons for executing various debugger commands.

Trace Log:

    This shows the execution trace.

Close button:

    quits from tracer.


Functionality
=============

The start of tracing is initiated outside of the tracer window. In general,
it is initiated by running a query while the tracer window is opened. It
can also be initiated during the middle of an execution, if the system
encounters a goal whose predicate has the `start_tracing' and `spy'
predicate properties set (this can be done using the predicate browser).

Call Stack
----------

The current goal and its ancestors are shown in this window. The status of
the current goal is indicated by its colour: blue if it is at a call, redo
or delay port, green if it at an exit port, and red if it is at a failed
port. Note that the port name is not updated in the call stack to FAIL when
the goal fails. The failure is indicated by the colour (red), and also in
the trace log (although the bindings on calling the goal are not shown
there).

Ancestor goals whose printed bindings may no longer be current, e.g.
because they have changed due to subsequent execution, are shown in black.
The display can be updated using the refresh-stack option on the popup menu.

The goals are shown in their order in the stack, with the depth of a
particular goal indicated by how far it is from the top of the window,
e.g. a goal at depth 3 will be 4 lines from the top (depth starts from 0;
the goal at depth 0 is a call to trace/1 with the query is the query is
traced from the start, or the goal that caused the tracing to be
initiated). If a particular ancestor goal was untraceable, a blank line
would be shown. The stack is updated at each trace-line. Goals which shows
non-current bindings (because the execution could have updated the
bindings) are shown in black.

A popup menu can be invoked for each goal in the call stack by the
right mouse button.  The predicate name of the goal and its module are
shown, and a few options are available from the menu: 

	toggle the spying/nospying of the predicate.

        display the source for the predicate

        inspect the contents of the goal using the inspector: note that no
           binding information for the goal is available at a fail port.

	observe the entire goal for changes to any of its arguments. A
           display matrix will be created with the goal when ECLiPSe continue 
           execution. Individual terms in the goal can also be selected for
           observation from inside the inspector. See the display matrix help
           file for more information on observing terms. 

        force failure of the selected goal

        cause the tracer to jump to the next trace line with the same
           invocation number (to a port for that particular goal).

        cause the tracer to jump to the next trace line with the same depth
           as the goal. This can be used to run until the exit from a
	   deeply nested execution.

        cause the call stack to be refreshed
	   (same as Refresh goal stack option in the Options menu)

Double left clicking on a goal will directly invoke the inspector to allow
the user to examine the goal.

Note that if the written form of a predicate is different from its internal
representation, then the predicate name shown in summary of the popup menu
is in the written form, but in the internal form elsewhere in the menu.
 
Trace Log
---------

This shows the trace of execution via the trace line. This is similar to
what is available in a traditional tty debugger. Each time the tracer stops
at a debug port, a new trace line is displayed in the trace log. Again, the
colour of the text indicates which port the trace line is at: blue for call
and redo, green for exit, and red for fail. In addition, the depth
information is also given by the indentation of the trace line from the
left edge of the window indicates the depth of the goal at the trace line
(as in the tty debugger trace line, the invocation number and depth are
also printed).

Outputs sent to debug_output stream will also appear in this window. This
stream is flushed before each trace line. Outputs to the debug_output
stream will only appear when the stream is flushed. If the flushing occurs
while the tracer window is not active, the flushed output will be lost.

Debugger command buttons
------------------------

Creep button - this causes the tracer to creep, i.e. to continue
execution and stop at the next traceable goal's debug port. Typing `c'
anywhere in the tracer window will also cause the tracer to creep. Holding
down the left mouse button over the creep button would cause the tracer to
repeatedly creep until the button is released. 

Skip button - this causes the tracer to skip and continue execution until
the exit or fail port of the goal it was at, or creep if the current trace
line is at at fail or exit port. Typing `s' anywhere in the tracer window
will also cause the tracer to skip.

Up button - this causes the tracer to continue execution until any port
that is one level higher in the call stack (i.e. back to the parent).

Leap button - this causes the tracer to continue execution until it reaches
a goal with spy point set on it. Typing `l' anywhere in the tracer window
will also cause the tracer to leap.

Filter button - this causes the tracer to continue execution until it
reaches a port that satisfies certain filter conditions.  The filter
conditions can be edited by selecting "Configure filter" from the
Options menu.

Abort button - this causes the tracer to abort the execution.

Nodebug button - this turns off the debugger and continue the execution of
the program. Note that there will be no more interaction with the user in
the tracer window (unless the program turns debug on again), so the
top-level window is raised by this command.

To Invoc button - this causes the debugger to continue execution until it
hits a goal with the invocation number indicated by the box next to the
button. This number can be altered by the user, and it defaults to the
invocation number of the goal from the most current trace line. 

To Depth button - this causes the debugger to continue execution until it
hits a goal with a depth in the range indicated by the boxes next to the
button. These numbers can be altered by the user, and they both default to
the depth of the goal from the most current trace line.

To Port button - this causes the debugger to continue execution until it
arrives at a debugger port of the type selected in the box to the right.
The first entry in this box is "Not Current" which stands for any port
different from the one where the execution is currently stopped.
This is useful for quickly skipping over sequences of fail or exit ports.
When a program raises and error, the error location can quickly be found
by going to a leave-port.

Configure filter
----------------

The "Configure filter" window allows to specify a more complex condition
which must be met at the port at which execution is to be stopped. You may
specify a range of invocation numbers, a range of nesting depths and
the ports types where execution should be stopped.

You can also specify a predicate specification which must be met by
the current goal in question. "Any predicate" (the default) will
impose no restriction on the form of the current goal. "Any predicate
with a spypoint" will only allow stops at predicates with
spypoints. "Specific predicate instance" allows you to set a detailed
specifiction of the form of the goal for the next stopping port:

"Defining module" is any module where the template predicate is
visible from. You must select a module where the a predicate matching
the template is defined.

For "Goal template" you should write a term which your goal will be an
instance of (i.e. your term should be at least as general as the goal
terms you would like to match). For example, entering p(X,_,4) will
cause execution to be stopped when the goal is p(5,4,4) but not when
it is p(5,4,3). Note that a variable can be used, in which case it can be
manipulated in the Condition. By default this field is empty in which case
it will match any goal. Do not terminate the template with a full stop.

For "Condition" you can enter any ECLiPSe goals which must succeed if
execution is to be stopped at the port. These can mention variables
used in the first field. For example if you had "Goal template:
p(X,_,4)" and "Condition: X > 3, X < 10", then execution would be
stopped when the current goal is "p(4, 4, 4)" but not when it is "p(2,
4, 4)". Any bindings make during the test will be undone when the test
suceeds. Do not terminate the condition with a full stop.

"Calling module" specifies current module when the goal is called. If
it is left blank (the default), calling the goal from any module will
cause execution to be suspended.

Clicking on the "Go" button will continue execution of the program --
the tracer will only stop again when it encounters a port which meets
all your conditions.  The "Filter" button on the main tracer window
has the same function.  The system will remember the filter conditions
even when the "Configure filter" window is closed. If execution continues
beyond code that can be traced (e.g. beyond the goal in which tracing was
started), the execution will stop at any traced goal when tracing is 
started again.

Note that the tracer cannot stop at the fail and leave ports when the
specific predicate instance option is used. 

