/usr/lib/swi-prolog/doc/Manual/debugoverview.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<HTML>
<HEAD>
<TITLE>SWI-Prolog 5.11.18 Reference Manual: Section 2.9</TITLE><LINK REL=home HREF="index.html">
<LINK REL=contents HREF="Contents.html">
<LINK REL=index HREF="DocIndex.html">
<LINK REL=summary HREF="summary.html">
<LINK REL=previous HREF="topvars.html">
<LINK REL=next HREF="compilation.html">
<STYLE type="text/css">
/* Style sheet for SWI-Prolog latex2html
*/

dd.defbody
{ margin-bottom: 1em;
}

dt.pubdef
{ background-color: #c5e1ff;
}

dt.multidef
{ background-color: #c8ffc7;
}

.bib dd
{ margin-bottom: 1em;
}

.bib dt
{ float: left;
margin-right: 1.3ex;
}

pre.code
{ margin-left: 1.5em;
margin-right: 1.5em;
border: 1px dotted;
padding-top: 5px;
padding-left: 5px;
padding-bottom: 5px;
background-color: #f8f8f8;
}

div.navigate
{ text-align: center;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
}

div.title
{ text-align: center;
padding-bottom: 1em;
font-size: 200%;
font-weight: bold;
}

div.author
{ text-align: center;
font-style: italic;
}

div.abstract
{ margin-top: 2em;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
margin-left: 10%; margin-right:10%;
}

div.abstract-title
{ text-align: center;
padding: 5px;
font-size: 120%;
font-weight: bold;
}

div.toc-h1
{ font-size: 200%;
font-weight: bold;
}

div.toc-h2
{ font-size: 120%;
font-weight: bold;
margin-left: 2em;
}

div.toc-h3
{ font-size: 100%;
font-weight: bold;
margin-left: 4em;
}

div.toc-h4
{ font-size: 100%;
margin-left: 6em;
}

span.sec-nr
{
}

span.sec-title
{
}

span.pred-ext
{ font-weight: bold;
}

span.pred-tag
{ float: right;
padding-top: 0.2em;
font-size: 80%;
font-style: italic;
color: #202020;
}

/* Footnotes */

sup.fn { color: blue; text-decoration: underline; }
span.fn-text { display: none; }
sup.fn span {display: none;}
sup:hover span
{ display: block !important;
position: absolute; top: auto; left: auto; width: 80%;
color: #000; background: white;
border: 2px solid;
padding: 5px; margin: 10px; z-index: 100;
font-size: smaller;
}
</STYLE>
</HEAD>
<BODY BGCOLOR="white">
<DIV class="navigate"><A class="nav" href="index.html"><IMG SRC="home.gif" BORDER=0 ALT="Home"></A>
<A class="nav" href="Contents.html"><IMG SRC="index.gif" BORDER=0 ALT="Contents"></A>
<A class="nav" href="DocIndex.html"><IMG SRC="yellow_pages.gif" BORDER=0 ALT="Index"></A>
<A class="nav" href="summary.html"><IMG SRC="info.gif" BORDER=0 ALT="Summary"></A>
<A class="nav" href="topvars.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="compilation.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>

<H2><A NAME="sec:2.9"><SPAN class="sec-nr">2.9</SPAN> <SPAN class="sec-title">Overview 
of the Debugger</SPAN></A></H2>

<A NAME="sec:debugoverview"></A>

<P>SWI-Prolog has a 6-port tracer, extending the standard 4-port Byrd 
box model tracer <CITE><A class="cite" href="Bibliography.html#Byrd:80">Byrd, 
1980</A>, <A class="cite" href="Bibliography.html#Clocksin:87">Clocksin &amp; 
Melish, 1987</A></CITE> with two additional ports. The optional <VAR>unify</VAR> 
port allows the user to inspect the result after unification of the 
head. The <VAR>exception</VAR> port shows exceptions raised by <A NAME="idx:throw1:87"></A><A class="pred" href="exception.html#throw/1">throw/1</A> 
or one of the built-in predicates. See
<A class="sec" href="exception.html">section 4.9</A>.

<P>The standard ports are called <CODE>call</CODE>, <CODE>exit</CODE>, <CODE>redo</CODE>,
<CODE>fail</CODE> and <CODE>unify</CODE>. The tracer is started by the <A NAME="idx:trace0:88"></A><A class="pred" href="debugger.html#trace/0">trace/0</A> 
command, when a spy point is reached and the system is in debugging mode 
(see <A NAME="idx:spy1:89"></A><A class="pred" href="debugger.html#spy/1">spy/1</A> 
and <A NAME="idx:debug0:90"></A><A class="pred" href="debugger.html#debug/0">debug/0</A>) 
or when an exception is raised.

<P>The interactive top-level goal <A NAME="idx:trace0:91"></A><A class="pred" href="debugger.html#trace/0">trace/0</A> 
means ``trace the next query''. The tracer shows the port, displaying 
the port name, the current depth of the recursion and the goal. The goal 
is printed using the Prolog predicate <A NAME="idx:writeterm2:92"></A><A class="pred" href="termrw.html#write_term/2">write_term/2</A>. 
The style is defined by the Prolog flag
<A class="flag" href="flags.html#flag:debugger_print_options">debugger_print_options</A> 
and can be modified using this flag or using the <CODE>w</CODE>, <CODE>p</CODE> 
and <CODE>d</CODE> commands of the tracer.

<PRE class="code">
min_numlist([H|T], Min) :-
        min_numlist(T, H, Min).

min_numlist([], Min, Min).
min_numlist([H|T], Min0, Min) :-
        Min1 is min(H, Min0),
        min_numlist(T, Min1, Min).
</PRE>

<PRE class="code">
1 ?- visible(+all), leash(-exit).
true.

2 ?- trace, min_numlist([3, 2], X).
   Call: (7) min_numlist([3, 2], _G0) ? creep
   Unify: (7) min_numlist([3, 2], _G0)
   Call: (8) min_numlist([2], 3, _G0) ? creep
   Unify: (8) min_numlist([2], 3, _G0)
^  Call: (9) _G54 is min(2, 3) ? creep
^  Exit: (9) 2 is min(2, 3)
   Call: (9) min_numlist([], 2, _G0) ? creep
   Unify: (9) min_numlist([], 2, 2)
   Exit: (9) min_numlist([], 2, 2)
   Exit: (8) min_numlist([2], 3, 2)
   Exit: (7) min_numlist([3, 2], 2)
X = 2.
</PRE>

<TABLE ALIGN=center WIDTH="75%"><TR><TD>
<B>Figure 2 : </B>Example trace of the program above showing all ports. 
The lines marked <CODE><CODE>^</CODE></CODE> indicate calls to <EM>transparent</EM> 
predicates. See <A class="sec" href="modules.html">section 5</A>.</TABLE>

<A NAME="fig:tracer"></A>

<P>On <EM>leashed ports</EM> (set with the predicate <A NAME="idx:leash1:93"></A><A class="pred" href="debugger.html#leash/1">leash/1</A>, 
default are
<CODE>call</CODE>, <CODE>exit</CODE>, <CODE>redo</CODE> and <CODE>fail</CODE>) 
the user is prompted for an action. All actions are single character 
commands which are executed <B>without</B> waiting for a return, unless 
the command-line option <STRONG>-tty</STRONG> is active. Tracer options:

<DL class="latex">
<DT><STRONG>Spy</STRONG> (<CODE>+</CODE>)</DT>
<DD class="defbody">
Set a spy point (see <A NAME="idx:spy1:94"></A><A class="pred" href="debugger.html#spy/1">spy/1</A>) 
on the current predicate.
</DD>
<DT><STRONG>No spy</STRONG> (<CODE>-</CODE>)</DT>
<DD class="defbody">
Remove the spy point (see <A NAME="idx:nospy1:95"></A><A class="pred" href="debugger.html#nospy/1">nospy/1</A>) 
from the current predicate.
</DD>
<DT><STRONG>Find</STRONG> (<CODE>/</CODE>)</DT>
<DD class="defbody">
Search for a port. After the `/', the user can enter a line to specify 
the port to search for. This line consists of a set of letters 
indicating the port type, followed by an optional term, that should 
unify with the goal run by the port. If no term is specified it is taken 
as a variable, searching for any port of the specified type. If an atom 
is given, any goal whose functor has a name equal to that atom matches. 
Examples: 
<CENTER>
<TABLE BORDER=0 FRAME=void RULES=groups>
<TR VALIGN=top><TD><TT>/f</TT></TD><TD>Search for any fail port </TD></TR>
<TR VALIGN=top><TD><TT>/fe solve</TT></TD><TD>Search for a fail or exit 
port of any goal with name <CODE>solve</CODE> </TD></TR>
<TR VALIGN=top><TD><TT>/c solve(a, _)</TT></TD><TD>Search for a call to solve/2 
whose first argument is a variable or the atom <CODE>a</CODE> </TD></TR>
<TR VALIGN=top><TD><TT>/a member(_, _)</TT></TD><TD>Search for any port 
on <A NAME="idx:member2:96"></A><A class="pred" href="lists.html#member/2">member/2</A>. 
This is equivalent to setting a spy point on <A NAME="idx:member2:97"></A><A class="pred" href="lists.html#member/2">member/2</A>. </TD></TR>
</TABLE>

</CENTER>
</DD>
<DT><STRONG>Repeat find</STRONG> (<CODE>.</CODE>)</DT>
<DD class="defbody">
Repeat the last find command (see `/').
</DD>
<DT><STRONG>Alternatives</STRONG> (<CODE>A</CODE>)</DT>
<DD class="defbody">
Show all goals that have alternatives.
</DD>
<DT><STRONG>Context</STRONG> (<CODE>C</CODE>)</DT>
<DD class="defbody">
Toggle `Show Context'. If <CODE>on</CODE>, the context module of the 
goal is displayed between square brackets (see <A class="sec" href="modules.html">section 
5</A>). Default is <CODE>off</CODE>.
</DD>
<DT><STRONG>Listing</STRONG> (<CODE>L</CODE>)</DT>
<DD class="defbody">
List the current predicate with <A NAME="idx:listing1:98"></A><A class="pred" href="listing.html#listing/1">listing/1</A>.
</DD>
<DT><STRONG>Abort</STRONG> (<CODE>a</CODE>)</DT>
<DD class="defbody">
Abort Prolog execution (see <A NAME="idx:abort0:99"></A><A class="pred" href="toplevel.html#abort/0">abort/0</A>).
</DD>
<DT><STRONG>Break</STRONG> (<CODE>b</CODE>)</DT>
<DD class="defbody">
Enter a Prolog break environment (see <A NAME="idx:break0:100"></A><A class="pred" href="toplevel.html#break/0">break/0</A>).
</DD>
<DT><STRONG>Creep</STRONG> (<CODE>c</CODE>)</DT>
<DD class="defbody">
Continue execution, stop at next port. (Also return, space).
</DD>
<DT><STRONG>Display</STRONG> (<CODE>d</CODE>)</DT>
<DD class="defbody">
Set the <CODE>max_depth(Depth)</CODE> option of <A class="flag" href="flags.html#flag:debugger_print_options">debugger_print_options</A>, 
limiting the depth to which terms are printed. See also the <CODE>w</CODE> 
and <CODE>p</CODE> options.
</DD>
<DT><STRONG>Exit</STRONG> (<CODE>e</CODE>)</DT>
<DD class="defbody">
Terminate Prolog (see <A NAME="idx:halt0:101"></A><A class="pred" href="toplevel.html#halt/0">halt/0</A>).
</DD>
<DT><STRONG>Fail</STRONG> (<CODE>f</CODE>)</DT>
<DD class="defbody">
Force failure of the current goal.
</DD>
<DT><STRONG>Goals</STRONG> (<CODE>g</CODE>)</DT>
<DD class="defbody">
Show the list of parent goals (the execution stack). Note that due to 
tail recursion optimization a number of parent goals might not exist any 
more.
</DD>
<DT><STRONG>Help</STRONG> (<CODE>h</CODE>)</DT>
<DD class="defbody">
Show available options (also `?').
</DD>
<DT><STRONG>Ignore</STRONG> (<CODE>i</CODE>)</DT>
<DD class="defbody">
Ignore the current goal, pretending it succeeded.
</DD>
<DT><STRONG>Leap</STRONG> (<CODE>l</CODE>)</DT>
<DD class="defbody">
Continue execution, stop at next spy point.
</DD>
<DT><STRONG>No debug</STRONG> (<CODE>n</CODE>)</DT>
<DD class="defbody">
Continue execution in `no debug' mode.
</DD>
<DT><STRONG>Print</STRONG> (<CODE>p</CODE>)</DT>
<DD class="defbody">
Set the Prolog flag <A class="flag" href="flags.html#flag:debugger_print_options">debugger_print_options</A> 
to <TT>[quoted(true), portray(true), max_depth(10), priority(699)]</TT>. 
This is the default.
</DD>
<DT><STRONG>Retry</STRONG> (<CODE>r</CODE>)</DT>
<DD class="defbody">
Undo all actions (except for database and i/o actions) back to the call 
port of the current goal and resume execution at the call port.
</DD>
<DT><STRONG>Skip</STRONG> (<CODE>s</CODE>)</DT>
<DD class="defbody">
Continue execution, stop at the next port of <B>this</B> goal (thus 
skipping all calls to children of this goal).
</DD>
<DT><STRONG>Up</STRONG> (<CODE>u</CODE>)</DT>
<DD class="defbody">
Continue execution, stop at the next port of <B>the parent</B> goal 
(thus skipping this goal and all calls to children of this goal). This 
option is useful to stop tracing a failure driven loop.
</DD>
<DT><STRONG>Write</STRONG> (<CODE>w</CODE>)</DT>
<DD class="defbody">
Set the Prolog flag <A class="flag" href="flags.html#flag:debugger_print_options">debugger_print_options</A> 
to <CODE>[quoted(true), attributes(write), priority(699)]</CODE>, 
bypassing <A NAME="idx:portray1:102"></A><A class="pred" href="termrw.html#portray/1">portray/1</A>, 
etc.
</DD>
</DL>

<P>The ideal 4 port Byrd box model <CITE><A class="cite" href="Bibliography.html#Byrd:80">Byrd, 
1980</A></CITE> as described in many Prolog books <CITE><A class="cite" href="Bibliography.html#Clocksin:87">Clocksin &amp; 
Melish, 1987</A></CITE> is not visible in many Prolog implementations 
because code optimisation removes part of the choice- and exit-points. 
Backtrack points are not shown if either the goal succeeded 
deterministically or its alternatives were removed using the cut. When 
running in debug mode (<A NAME="idx:debug0:103"></A><A class="pred" href="debugger.html#debug/0">debug/0</A>) 
choice points are only destroyed when removed by the cut. In debug mode, 
last call optimisation is switched off.<SUP class="fn">4<SPAN class="fn-text">This 
implies the system can run out of local stack in debug mode, while no 
problems arise when running in non-debug mode.</SPAN></SUP>

<P>Reference information to all predicates available for manipulating 
the debugger is in <A class="sec" href="debugger.html">section 4.37</A>.

<P></BODY></HTML>
swi-prolog-nox 5.10.4-3ubuntu1 / usr / lib / swi-prolog / doc / Manual / debugoverview.html
