/usr/lib/swi-prolog/doc/Manual/debugger.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 4.37</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="protocol.html">
<LINK REL=next HREF="statistics.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="protocol.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="statistics.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>

<H2><A NAME="sec:4.37"><SPAN class="sec-nr">4.37</SPAN> <SPAN class="sec-title">Debugging 
and Tracing Programs</SPAN></A></H2>

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

<P>This section is a reference to the debugger interaction predicates. A 
more use-oriented overview of the debugger is in <A class="sec" href="debugoverview.html">section 
2.9</A>.

<P>If you have installed XPCE, you can use the graphical front-end of 
the tracer. This front-end is installed using the predicate <A NAME="idx:guitracer0:1169"></A><A class="pred" href="guitracer.html#guitracer/0">guitracer/0</A>.

<DL class="latex">
<DT class="pubdef"><A NAME="trace/0"><STRONG>trace</STRONG></A></DT>
<DD class="defbody">
Start the tracer. <A NAME="idx:trace0:1170"></A><A class="pred" href="debugger.html#trace/0">trace/0</A> 
itself cannot be seen in the tracer. Note that the Prolog top-level 
treats <A NAME="idx:trace0:1171"></A><A class="pred" href="debugger.html#trace/0">trace/0</A> 
special; it means `trace the next goal'.
</DD>
<DT class="pubdef"><A NAME="tracing/0"><STRONG>tracing</STRONG></A></DT>
<DD class="defbody">
True if the tracer is currently switched on. <A NAME="idx:tracing0:1172"></A><A class="pred" href="debugger.html#tracing/0">tracing/0</A> 
itself can not be seen in the tracer.
</DD>
<DT class="pubdef"><A NAME="notrace/0"><STRONG>notrace</STRONG></A></DT>
<DD class="defbody">
Stop the tracer. <A NAME="idx:notrace0:1173"></A><A class="pred" href="debugger.html#notrace/0">notrace/0</A> 
itself cannot be seen in the tracer.
</DD>
<DT class="pubdef"><A NAME="guitracer/0"><STRONG>guitracer</STRONG></A></DT>
<DD class="defbody">
Installs hooks (see <A NAME="idx:prologtraceinterception4:1174"></A><A class="pred" href="tracehook.html#prolog_trace_interception/4">prolog_trace_interception/4</A>) 
into the system that redirects tracing information to a GUI front-end 
providing structured access to variable-bindings, graphical overview of 
the stack and highlighting of relevant source-code.
</DD>
<DT class="pubdef"><A NAME="noguitracer/0"><STRONG>noguitracer</STRONG></A></DT>
<DD class="defbody">
Reverts back to the textual tracer.
</DD>
<DT class="pubdef"><A NAME="trace/1"><STRONG>trace</STRONG>(<VAR>+Pred</VAR>)</A></DT>
<DD class="defbody">
Equivalent to <CODE>trace(<VAR>Pred</VAR>, +all)</CODE>.
</DD>
<DT class="pubdef"><A NAME="trace/2"><STRONG>trace</STRONG>(<VAR>+Pred, 
+Ports</VAR>)</A></DT>
<DD class="defbody">
Put a trace-point on all predicates satisfying the predicate 
specification
<VAR>Pred</VAR>. <VAR>Ports</VAR> is a list of port names (<CODE>call</CODE>,
<CODE>redo</CODE>, <CODE>exit</CODE>, <CODE>fail</CODE>). The atom <CODE>all</CODE> 
refers to all ports. If the port is preceded by a <CODE><CODE>-</CODE></CODE> 
sign the trace-point is cleared for the port. If it is preceded by a <CODE><CODE>+</CODE></CODE> 
the trace-point is set.

<P>The predicate <A NAME="idx:trace2:1175"></A><A class="pred" href="debugger.html#trace/2">trace/2</A> 
activates debug mode (see <A NAME="idx:debug0:1176"></A><A class="pred" href="debugger.html#debug/0">debug/0</A>). 
Each time a port (of the 4-port model) is passed that has a trace-point 
set the goal is printed as with <A NAME="idx:trace0:1177"></A><A class="pred" href="debugger.html#trace/0">trace/0</A>. 
Unlike <A NAME="idx:trace0:1178"></A><A class="pred" href="debugger.html#trace/0">trace/0</A> 
however, the execution is continued without asking for further 
information. Examples:

<P>
<CENTER>
<TABLE BORDER=0 FRAME=void RULES=groups>
<TR VALIGN=top><TD><CODE>?- trace(hello).</CODE> </TD><TD>Trace all 
ports of hello with any arity in any module. </TD></TR>
<TR VALIGN=top><TD><CODE>?- trace(foo/2, +fail).</CODE> </TD><TD>Trace 
failures of foo/2 in any module. </TD></TR>
<TR VALIGN=top><TD><CODE>?- trace(bar/1, -all).</CODE> </TD><TD>Stop 
tracing bar/1.</TD></TR>
</TABLE>

</CENTER>

<P>The predicate <A NAME="idx:debugging0:1179"></A><A class="pred" href="debugger.html#debugging/0">debugging/0</A> 
shows all currently defined trace-points.</DD>
<DT class="pubdef"><A NAME="notrace/1"><STRONG>notrace</STRONG>(<VAR>:Goal</VAR>)</A></DT>
<DD class="defbody">
Call <VAR>Goal</VAR>, but suspend the debugger while <VAR>Goal</VAR> is 
executing. The current implementation cuts the choice-points of <VAR>Goal</VAR> 
after successful completion. See <A NAME="idx:once1:1180"></A><A class="pred" href="metacall.html#once/1">once/1</A>. 
Later implementations may have the same semantics as <A NAME="idx:call1:1181"></A><A class="pred" href="metacall.html#call/1">call/1</A>.</DD>
<DT class="pubdef"><A NAME="debug/0"><STRONG>debug</STRONG></A></DT>
<DD class="defbody">
Start debugger. In debug mode, Prolog stops at spy- and trace-points, 
disables last-call optimisation and aggressive destruction of choice 
points to make debugging information accessible. Implemented by the 
Prolog flag <A class="flag" href="flags.html#flag:debug">debug</A>.

<P>Note that the <CODE>min_free</CODE> parameters of all stacks is 
enlarged to 8&nbsp;K-cells if debugging is switched off to avoid 
excessive GC. GC complicates tracing because it renames the <I>_G&lt;<VAR>NNN</VAR>&gt;</I> 
variables and replaces unreachable variables with the atom
<CODE>\bnfmeta{garbage_collected}</CODE>. Calling <A NAME="idx:nodebug0:1182"></A><A class="pred" href="debugger.html#nodebug/0">nodebug/0</A> 
does <EM>not</EM> reset the initial free-margin because several parts of 
the toplevel and debugger disable debugging of system code-regions. See 
also <A NAME="idx:setprologstack2:1183"></A><A class="pred" href="memory.html#set_prolog_stack/2">set_prolog_stack/2</A>.</DD>
<DT class="pubdef"><A NAME="nodebug/0"><STRONG>nodebug</STRONG></A></DT>
<DD class="defbody">
Stop debugger. Implemented by the Prolog flag <A class="flag" href="flags.html#flag:debug">debug</A>. 
See also <A NAME="idx:debug0:1184"></A><A class="pred" href="debugger.html#debug/0">debug/0</A>.</DD>
<DT class="pubdef"><A NAME="debugging/0"><STRONG>debugging</STRONG></A></DT>
<DD class="defbody">
Print debug status and spy points on current output stream. See also the 
Prolog flag <A class="flag" href="flags.html#flag:debug">debug</A>.
</DD>
<DT class="pubdef"><A NAME="spy/1"><STRONG>spy</STRONG>(<VAR>+Pred</VAR>)</A></DT>
<DD class="defbody">
Put a spy point on all predicates meeting the predicate specification
<VAR>Pred</VAR>. See <A class="sec" href="listing.html">section 4.4</A>.
</DD>
<DT class="pubdef"><A NAME="nospy/1"><STRONG>nospy</STRONG>(<VAR>+Pred</VAR>)</A></DT>
<DD class="defbody">
Remove spy point from all predicates meeting the predicate specification
<VAR>Pred</VAR>.
</DD>
<DT class="pubdef"><A NAME="nospyall/0"><STRONG>nospyall</STRONG></A></DT>
<DD class="defbody">
Remove all spy points from the entire program.
</DD>
<DT class="pubdef"><A NAME="leash/1"><STRONG>leash</STRONG>(<VAR>?Ports</VAR>)</A></DT>
<DD class="defbody">
Set/query leashing (ports which allow for user interaction). <VAR>Ports</VAR> 
is one of <VAR>+Name</VAR>, <VAR>-Name</VAR>, <VAR>?Name</VAR> or a list 
of these.
<VAR>+Name</VAR> enables leashing on that port, <VAR>-Name</VAR> 
disables it and
<VAR>?Name</VAR> succeeds or fails according to the current setting. 
Recognised ports are: <CODE>call</CODE>, <CODE>redo</CODE>, <CODE>exit</CODE>, <CODE>fail</CODE> 
and
<CODE>unify</CODE>. The special shorthand <CODE>all</CODE> refers to all 
ports,
<CODE>full</CODE> refers to all ports except for the unify port 
(default).
<CODE>half</CODE> refers to the <CODE>call</CODE>, <CODE>redo</CODE> and <CODE>fail</CODE> 
port.</DD>
<DT class="pubdef"><A NAME="visible/1"><STRONG>visible</STRONG>(<VAR>+Ports</VAR>)</A></DT>
<DD class="defbody">
Set the ports shown by the debugger. See <A NAME="idx:leash1:1185"></A><A class="pred" href="debugger.html#leash/1">leash/1</A> 
for a description of the port specification. Default is <CODE>full</CODE>.</DD>
<DT class="pubdef"><A NAME="unknown/2"><STRONG>unknown</STRONG>(<VAR>-Old, 
+New</VAR>)</A></DT>
<DD class="defbody">
Edinburgh-prolog compatibility predicate, interfacing to the ISO prolog 
flag <A class="flag" href="flags.html#flag:unknown">unknown</A>. Values 
are <CODE>trace</CODE> (meaning <CODE>error</CODE>) and <CODE>fail</CODE>. 
If the <A class="flag" href="flags.html#flag:unknown">unknown</A> flag 
is set to
<CODE>warning</CODE>, <A NAME="idx:unknown2:1186"></A><A class="pred" href="debugger.html#unknown/2">unknown/2</A> 
reports the value as <CODE>trace</CODE>.</DD>
<DT class="pubdef"><A NAME="style_check/1"><STRONG>style_check</STRONG>(<VAR>+Spec</VAR>)</A></DT>
<DD class="defbody">
Set style checking options. <VAR>Spec</VAR> is either <TT>+&lt;<VAR>option</VAR>&gt;</TT>,
<TT>-&lt;<VAR>option</VAR>&gt;</TT>, <TT>?(&lt;<VAR>option</VAR>&gt;)</TT><SUP class="fn">74<SPAN class="fn-text">In 
older versions `<CODE><CODE>?</CODE></CODE>' was a prefix operator. 
Inversions after 5.5.13, explicit brackets are needed.</SPAN></SUP> or a 
list of such options. <TT>+&lt;<VAR>option</VAR>&gt;</TT> sets a style 
checking option, <TT>-&lt;<VAR>option</VAR>&gt;</TT> clears it and <TT>?(&lt;<VAR>option</VAR>&gt;)</TT> 
succeeds or fails according to the current setting. <A NAME="idx:consult1:1187"></A><A class="pred" href="consulting.html#consult/1">consult/1</A> 
and derivatives resets the style checking options to their value before 
loading the file. If---for example---a file containing long atoms should 
be loaded the user can start the file with:

<PRE class="code">
:- style_check(-atom).
</PRE>

<P>Currently available options are:

<P>
<CENTER>
<TABLE BORDER=2 FRAME=box RULES=groups>
<TR VALIGN=top><TD>Name</TD><TD ALIGN=center>Default</TD><TD>Description </TD></TR>
<TBODY>
<TR VALIGN=top><TD><CODE>singleton</CODE> </TD><TD ALIGN=center>on</TD><TD><A NAME="idx:readclause1:1188"></A><A class="pred" href="termrw.html#read_clause/1">read_clause/1</A> 
(used by <A NAME="idx:consult1:1189"></A><A class="pred" href="consulting.html#consult/1">consult/1</A>) 
warns on variables only appearing once in a term (clause) which have a 
name not starting with an underscore. See <A class="sec" href="syntax.html">section 
2.15.1.5</A> for details on variable handling and warnings. </TD></TR>
<TR VALIGN=top><TD><CODE>atom</CODE> </TD><TD ALIGN=center>on</TD><TD><A NAME="idx:read1:1190"></A><A class="pred" href="termrw.html#read/1">read/1</A> 
and derivatives will produce an error message on quoted atoms or strings 
longer than 5 lines. </TD></TR>
<TR VALIGN=top><TD><CODE>dollar</CODE> </TD><TD ALIGN=center>off</TD><TD>Accept 
dollar as a lower case character, thus avoiding the need for quoting 
atoms with dollar signs. System maintenance use only. </TD></TR>
<TR VALIGN=top><TD><CODE>discontiguous</CODE> </TD><TD ALIGN=center>on</TD><TD>Warn 
if the clauses for a predicate are not together in the same source file. </TD></TR>
<TR VALIGN=top><TD><CODE>string</CODE> </TD><TD ALIGN=center>off</TD><TD>Backward 
compatibility. See the Prolog flag
<A class="flag" href="flags.html#flag:double_quotes">double_quotes</A> (<A NAME="idx:currentprologflag2:1191"></A><A class="pred" href="flags.html#current_prolog_flag/2">current_prolog_flag/2</A>). </TD></TR>
<TR VALIGN=top><TD><CODE>charset</CODE> </TD><TD ALIGN=center>off</TD><TD>Warn 
on atoms and variables holding non-ASCII characters that are not quoted. 
See also
<A class="sec" href="syntax.html">section 2.15.1.1</A>. </TD></TR>
</TABLE>

</CENTER>
</DD>
</DL>

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