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

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

<html>
<head>
<title>SWI-Prolog 7.1.10 Reference Manual: Section 7.4</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="practical.html">
<link rel="next" href="examples.html">

<style type="text/css">

/* Style sheet for SWI-Prolog latex2html
*/

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

dt.pubdef, dt.multidef
{ color: #fff;
padding: 2px 10px 0px 10px;
margin-bottom: 5px;
font-size: 18px;
vertical-align: middle;
overflow: hidden;
}

dt.pubdef { background-color: #0c3d6e; }
dt.multidef { background-color: #ef9439; }

.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: #fff;
}

div.caption
{ width: 80%;
margin: auto;
text-align:center;
}

/* Footnotes */
.fn {
color: red;
font-size: 70%;
}

.fn-text, .fnp {
position: absolute;
top: auto;
left: 10%;
border: 1px solid #000;
box-shadow: 5px 5px 5px #888;
display: none;
background: #fff;
color: #000;
margin-top: 25px;
padding: 8px 12px;
font-size: larger;
}

sup:hover span.fn-text
{ display: block;
}

/* Lists */

dl.latex
{ margin-top: 1ex;
margin-bottom: 0.5ex;
}

dl.latex dl.latex dd.defbody
{ margin-bottom: 0.5ex;
}

/* PlDoc Tags */

dl.tags
{ font-size: 90%;
margin-left: 5ex;
margin-top: 1ex;
margin-bottom: 0.5ex;
}

dl.tags dt
{ margin-left: 0pt;
font-weight: bold;
}

dl.tags dd
{ margin-left: 3ex;
}

td.param
{ font-style: italic;
font-weight: bold;
}

/* Index */

dt.index-sep
{ font-weight: bold;
font-size: +1;
margin-top: 1ex;
}

/* Tables */

table.center
{ margin: auto;
}

table.latex
{ border-collapse:collapse;
}

table.latex tr
{ vertical-align: text-top;
}

table.latex td,th
{ padding: 2px 1em;
}

table.latex tr.hline td,th
{ border-top: 1px solid black;
}

table.frame-box
{ border: 2px solid black;
}

</style>
</head>
<body style="background:white">
<div class="navigate"><a class="nav" href="index.html"><img src="home.gif" alt="Home"></a>
<a class="nav" href="Contents.html"><img src="index.gif" alt="Contents"></a>
<a class="nav" href="DocIndex.html"><img src="yellow_pages.gif" alt="Index"></a>
<a class="nav" href="summary.html"><img src="info.gif" alt="Summary"></a>
<a class="nav" href="practical.html"><img src="prev.gif" alt="Previous"></a>
<a class="nav" href="examples.html"><img src="next.gif" alt="Next"></a>
</div>
<h2 id="sec:debugging"><a id="sec:7.4"><span class="sec-nr">7.4</span> <span class="sec-title">Debugging</span></a></h2>

<a id="sec:debugging"></a> The CHR debugging facilities are currently 
rather limited. Only tracing is currently available. To use the CHR 
debugging facilities for a CHR file it must be compiled for debugging. 
Generating debug info is controlled by the CHR option <a class="flag" href="flags.html#flag:debug">debug</a>, 
whose default is derived from the SWI-Prolog flag <a class="flag" href="flags.html#flag:generate_debug_info">generate_debug_info</a>. 
Therefore debug info is provided unless the <strong>-nodebug</strong> is 
used.

<p><h3 id="sec:chrports"><a id="sec:7.4.1"><span class="sec-nr">7.4.1</span> <span class="sec-title">Ports</span></a></h3>

<a id="sec:chrports"></a> For CHR constraints the four standard ports 
are defined:

<dl class="latex">
<dt><strong>call</strong></dt>
<dd class="defbody">
A new constraint is called and becomes active.
</dd>
<dt><strong>exit</strong></dt>
<dd class="defbody">
An active constraint exits: it has either been inserted in the store 
after trying all rules or has been removed from the constraint store.
</dd>
<dt><strong>fail</strong></dt>
<dd class="defbody">
An active constraint fails.
</dd>
<dt><strong>redo</strong></dt>
<dd class="defbody">
An active constraint starts looking for an alternative solution.
</dd>
</dl>

<p>In addition to the above ports, CHR constraints have five additional 
ports:

<dl class="latex">
<dt><strong>wake</strong></dt>
<dd class="defbody">
A suspended constraint is woken and becomes active.
</dd>
<dt><strong>insert</strong></dt>
<dd class="defbody">
An active constraint has tried all rules and is suspended in the 
constraint store.
</dd>
<dt><strong>remove</strong></dt>
<dd class="defbody">
An active or passive constraint is removed from the constraint store.
</dd>
<dt><strong>try</strong></dt>
<dd class="defbody">
An active constraint tries a rule with possibly some passive 
constraints. The try port is entered just before committing to the rule.
</dd>
<dt><strong>apply</strong></dt>
<dd class="defbody">
An active constraint commits to a rule with possibly some passive 
constraints. The apply port is entered just after committing to the 
rule.
</dd>
</dl>

<p><h3 id="sec:chr-tracing"><a id="sec:7.4.2"><span class="sec-nr">7.4.2</span> <span class="sec-title">Tracing</span></a></h3>

<a id="sec:chr-tracing"></a> Tracing is enabled with the <a id="idx:chrtrace0:1548"></a><a class="pred" href="debugging.html#chr_trace/0">chr_trace/0</a> 
predicate and disabled with the <a id="idx:chrnotrace0:1549"></a><a class="pred" href="debugging.html#chr_notrace/0">chr_notrace/0</a> 
predicate.

<p>When enabled the tracer will step through the <code>call</code>,
<code>exit</code>, <code>fail</code>, <code>wake</code> and <code>apply</code> 
ports, accepting debug commands, and simply write out the other ports.

<p>The following debug commands are currently supported:

<pre class="code">
        CHR debug options:

                &lt;cr&gt;    creep           c       creep
                s       skip
                g       ancestors
                n       nodebug
                b       break
                a       abort
                f       fail
                ?       help            h       help
</pre>

<p>Their meaning is:

<dl class="latex">
<dt><strong>creep</strong></dt>
<dd class="defbody">
Step to the next port.
</dd>
<dt><strong>skip</strong></dt>
<dd class="defbody">
Skip to exit port of this call or wake port.
</dd>
<dt><strong>ancestors</strong></dt>
<dd class="defbody">
Print list of ancestor call and wake ports.
</dd>
<dt><strong>nodebug</strong></dt>
<dd class="defbody">
Disable the tracer.
</dd>
<dt><strong>break</strong></dt>
<dd class="defbody">
Enter a recursive Prolog top level. See <a id="idx:break0:1550"></a><a class="pred" href="toplevel.html#break/0">break/0</a>.
</dd>
<dt><strong>abort</strong></dt>
<dd class="defbody">
Exit to the top level. See <a id="idx:abort0:1551"></a><a class="pred" href="toplevel.html#abort/0">abort/0</a>.
</dd>
<dt><strong>fail</strong></dt>
<dd class="defbody">
Insert failure in execution.
</dd>
<dt><strong>help</strong></dt>
<dd class="defbody">
Print the above available debug options.
</dd>
</dl>

<p><h3 id="sec:predicates"><a id="sec:7.4.3"><span class="sec-nr">7.4.3</span> <span class="sec-title">CHR 
Debugging Predicates</span></a></h3>

<a id="sec:predicates"></a> The <code>library(chr)</code> module 
contains several predicates that allow inspecting and printing the 
content of the constraint store.

<dl class="latex">
<dt class="pubdef"><a id="chr_trace/0"><strong>chr_trace</strong></a></dt>
<dd class="defbody">
Activate the CHR tracer. By default the CHR tracer is activated and 
deactivated automatically by the Prolog predicates <a id="idx:trace0:1552"></a><a class="pred" href="debugger.html#trace/0">trace/0</a> 
and
<a id="idx:notrace0:1553"></a><a class="pred" href="debugger.html#notrace/0">notrace/0</a>.</dd>
<dt class="pubdef"><a id="chr_notrace/0"><strong>chr_notrace</strong></a></dt>
<dd class="defbody">
Deactivate the CHR tracer. By default the CHR tracer is activated and 
deactivated automatically by the Prolog predicates <a id="idx:trace0:1554"></a><a class="pred" href="debugger.html#trace/0">trace/0</a> 
and
<a id="idx:notrace0:1555"></a><a class="pred" href="debugger.html#notrace/0">notrace/0</a>.</dd>
<dt class="pubdef"><a id="chr_leash/1"><strong>chr_leash</strong>(<var>+Spec</var>)</a></dt>
<dd class="defbody">
Define the set of CHR ports on which the CHR tracer asks for user 
intervention (i.e. stops). <var>Spec</var> is either a list of ports as 
defined in <a class="sec" href="debugging.html">section 7.4.1</a> or a 
predefined `alias'. Defined aliases are: <code>full</code> to stop at 
all ports, <code>none</code> or <code>off</code> to never stop, and <code>default</code> 
to stop at the <code>call</code>,
<code>exit</code>, <code>fail</code>, <code>wake</code> and <code>apply</code> 
ports. See also <a id="idx:leash1:1556"></a><a class="pred" href="debugger.html#leash/1">leash/1</a>.</dd>
<dt class="pubdef"><a id="chr_show_store/1"><strong>chr_show_store</strong>(<var>+Mod</var>)</a></dt>
<dd class="defbody">
Prints all suspended constraints of module <var>Mod</var> to the 
standard output. This predicate is automatically called by the 
SWI-Prolog top level at the end of each query for every CHR module 
currently loaded. The Prolog flag
<code>chr_toplevel_show_store</code> controls whether the top level 
shows the constraint stores. The value <code>true</code> enables it. Any 
other value disables it.</dd>
<dt class="pubdef"><a id="find_chr_constraint/1"><strong>find_chr_constraint</strong>(<var>-Constraint</var>)</a></dt>
<dd class="defbody">
Returns a constraint in the constraint store. Via backtracking, all 
constraints in the store can be enumerated.
</dd>
</dl>

<p></body></html>
swi-prolog-nox 6.6.4-2ubuntu1 / usr / lib / swi-prolog / doc / Manual / debugging.html
