/usr/share/doc/swi-prolog-doc/Manual/debug.html

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

<HTML>
<HEAD>
<TITLE>SWI-Prolog 5.6.59 Reference Manual: Section A.9</TITLE><LINK REL=home HREF="index.html">
<LINK REL=contents HREF="Contents.html">
<LINK REL=index HREF="DocIndex.html">
<LINK REL=previous HREF="clpqr.html">
<LINK REL=next HREF="gensym.html">
<STYLE type="text/css">
/* Style sheet for SWI-Prolog latex2html
*/

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

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

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;
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="clpqr.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="gensym.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>

<H2><A NAME="sec:A.9"><SPAN class="sec-nr">A.9</SPAN> <SPAN class="sec-title">library( 
debug ): Some reusable code to help debugging applications</SPAN></A></H2>

<A NAME="debug"></A>

<P>This library provides an structured alternative for putting 
print-statements into your source-code to trace what is going on. Debug 
messages are organised in <EM>topics</EM> that can be activated and 
de-activated without changing the source. In addition, if the 
application is compiled with the <STRONG>-O</STRONG> flag these 
predicates are removed using <A NAME="idx:goalexpansion2:1481"></A><A class="pred" href="consulting.html#goal_expansion/2">goal_expansion/2</A>.

<P>Although this library can be used through the normal demand-loading 
mechanism it is adviced to load it explicitely before code using it to 
profit from goal-expansion, which removes these calls if compiled with 
optimisation on and records the topics from <A NAME="idx:debug3:1482"></A><A class="pred" href="debug.html#debug/3">debug/3</A> 
and <A NAME="idx:debugging1:1483"></A><A class="pred" href="debug.html#debugging/1">debugging/1</A> 
for
<A NAME="idx:listdebugtopics0:1484"></A><A class="pred" href="debug.html#list_debug_topics/0">list_debug_topics/0</A>.

<DL>
<DT class="pubdef"><A NAME="debug/3"><STRONG>debug</STRONG>(<VAR>+Topic, 
+Format, +Args</VAR>)</A></DT>
<DD class="defbody">
If <VAR>Topic</VAR> is a selected debugging topic (see <A NAME="idx:debug1:1485"></A><A class="pred" href="debug.html#debug/1">debug/1</A>) 
a message is printed using <A NAME="idx:printmessage2:1486"></A><A class="pred" href="exception.html#print_message/2">print_message/2</A> 
with level <CODE>informational</CODE>.
<VAR>Format</VAR> and <VAR>Args</VAR> are interpreted by <A NAME="idx:format2:1487"></A><A class="pred" href="format.html#format/2">format/2</A>. 
Here is a typical example:

<PRE class="code">
        ...,
        debug(init, 'Initialised ~w', [Module]),
        ...,
</PRE>

<P><VAR>Topic</VAR> can be any Prolog term. Compound terms can be used 
to make categories of topics that can be activated using <A NAME="idx:debug1:1488"></A><A class="pred" href="debug.html#debug/1">debug/1</A>.</DD>
<DT class="pubdef"><A NAME="debugging/1"><STRONG>debugging</STRONG>(<VAR>+Topic</VAR>)</A></DT>
<DD class="defbody">
Succeeds if <VAR>Topic</VAR> is a selected debugging topic. It is 
intended to execute arbitrary code depending on the users debug topic 
selection. The construct <TT>(debugging(Topic) -&gt; <VAR>Code</VAR> ; 
true)</TT> is removed if the code is compiled in optimise mode.</DD>
<DT class="pubdef"><A NAME="debug/1"><STRONG>debug</STRONG>(<VAR>+Topic</VAR>)</A></DT>
<DD class="defbody">
Select all registered topics that unify with <VAR>Topic</VAR> for 
debugging. This call is normally used from the toplevel to activate a 
topic for debugging. If no matching <VAR>Topic</VAR> is registered a 
warning is printed and the topic is registered for debugging as matching 
debug statements may be loaded later. Topics are de-activated using <A NAME="idx:nodebug1:1489"></A><A class="pred" href="debug.html#nodebug/1">nodebug/1</A>.</DD>
<DT class="pubdef"><A NAME="nodebug/1"><STRONG>nodebug</STRONG>(<VAR>+Topic</VAR>)</A></DT>
<DD class="defbody">
Deactivates topics for debugging. See <A NAME="idx:debug1:1490"></A><A class="pred" href="debug.html#debug/1">debug/1</A> 
for the arguments.</DD>
<DT class="pubdef"><A NAME="list_debug_topics/0"><STRONG>list_debug_topics</STRONG></A></DT>
<DD class="defbody">
List the current status of registered topics. See also <A NAME="idx:debugging0:1491"></A><A class="pred" href="debugger.html#debugging/0">debugging/0</A>.</DD>
<DT class="pubdef"><A NAME="assertion/1"><STRONG>assertion</STRONG>(<VAR>:Goal</VAR>)</A></DT>
<DD class="defbody">
<A NAME="idx:assertions:1492"></A>This predicate is to be compared to 
the C-library assert() function. By inserting this goal you explicitely 
state you expect
<VAR>Goal</VAR> to succeed at this place. As <A NAME="idx:assertion1:1493"></A><A class="pred" href="debug.html#assertion/1">assertion/1</A> 
calls are removed when compiling in optimized mode <VAR>Goal</VAR> 
should not have side-effects. Typical examples are type-tests and 
validating invariants defined by your application.

<P>If <VAR>Goal</VAR> fails the system prints a message, followed by a 
stack-trace and starts the debugger.

<P>In older versions of this library this predicate was called assume/1 
. Code using assume/1 is automatically converted while printing a 
warning on the first occurrence.

<P></DD>
</DL>

<P></BODY></HTML>
swi-prolog-doc 5.6.59-1 / usr / share / doc / swi-prolog-doc / Manual / debug.html
