/usr/lib/swi-prolog/doc/Manual/practical.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.16 Reference Manual: Section 7.3</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="SyntaxAndSemantics.html">
<link rel="next" href="debugging.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="SyntaxAndSemantics.html"><img src="prev.gif" alt="Previous"></a>
<a class="nav" href="debugging.html"><img src="next.gif" alt="Next"></a>
</div>
<h2 id="sec:practical"><a id="sec:7.3"><span class="sec-nr">7.3</span> <span class="sec-title">CHR 
in SWI-Prolog Programs</span></a></h2>

<a id="sec:practical"></a>
<h3 id="sec:chr-embedding"><a id="sec:7.3.1"><span class="sec-nr">7.3.1</span> <span class="sec-title">Embedding 
in Prolog Programs</span></a></h3>

<a id="sec:chr-embedding"></a>

<p>The CHR constraints defined in a <code>.pl</code> file are associated 
with a module. The default module is <code>user</code>. One should never 
load different <code>.pl</code> files with the same CHR module name.

<p><h3 id="sec:chr-declarations"><a id="sec:7.3.2"><span class="sec-nr">7.3.2</span> <span class="sec-title">Constraint 
declaration</span></a></h3>

<a id="sec:chr-declarations"></a>

<dl class="latex">
<dt class="pubdef"><a id="chr_constraint/1">:- <strong>chr_constraint</strong>(<var>+Specifier</var>)</a></dt>
<dd class="defbody">
Every constraint used in CHR rules has to be declared with a
<a id="idx:chrconstraint1:1545"></a><a class="pred" href="practical.html#chr_constraint/1">chr_constraint/1</a> 
declaration by the <em>constraint specifier</em>. For convenience 
multiple constraints may be declared at once with the same
<a class="pred" href="practical.html#chr_constraint/1">chr_constraint/1</a> 
declaration followed by a comma-separated list of constraint specifiers.

<p>A constraint specifier is, in its compact form, <code><var>F</var>/<var>A</var></code> 
where
<var>F</var> and <var>A</var> are respectively the functor name and 
arity of the constraint, e.g.:

<pre class="code">
:- chr_constraint foo/1.
:- chr_constraint bar/2, baz/3.
</pre>

<p>In its extended form, a constraint specifier is
<code><var>c</var>(<var>A_1</var>, ... ,<var>A_n</var>)</code> where <var>c</var> 
is the constraint's functor,
<var>n</var> its arity and the <var>A_i</var> are argument specifiers. 
An argument specifier is a mode, optionally followed by a type. Example:

<pre class="code">
:- chr_constraint get_value(+,?).
:- chr_constraint domain(?int, +list(int)),
                  alldifferent(?list(int)).
</pre>

<p></dd>
</dl>

<p><b>Modes</b> 

<p>A mode is one of:

<dl class="latex">
<dt><strong><code>-</code></strong></dt>
<dd class="defbody">
The corresponding argument of every occurrence of the constraint is 
always unbound.
</dd>
<dt><strong><code>+</code></strong></dt>
<dd class="defbody">
The corresponding argument of every occurrence of the constraint is 
always ground.
</dd>
<dt><strong><code>?</code></strong></dt>
<dd class="defbody">
The corresponding argument of every occurrence of the constraint can 
have any instantiation, which may change over time. This is the default 
value.
</dd>
</dl>

<p><b>Types</b> 

<p>A type can be a user-defined type or one of the built-in types. A 
type comprises a (possibly infinite) set of values. The type declaration 
for a constraint argument means that for every instance of that 
constraint the corresponding argument is only ever bound to values in 
that set. It does not state that the argument necessarily has to be 
bound to a value.

<p>The built-in types are:

<dl class="latex">
<dt><strong>int</strong></dt>
<dd class="defbody">
The corresponding argument of every occurrence of the constraint is an 
integer number.
</dd>
<dt><strong>dense_int</strong></dt>
<dd class="defbody">
The corresponding argument of every occurrence of the constraint is an 
integer that can be used as an array index. Note that if this argument 
takes values in <var>[0,n]</var>, the array takes
<var>O(n)</var> space.
</dd>
<dt><strong>float</strong></dt>
<dd class="defbody">
... a floating point number.
</dd>
<dt><strong>number</strong></dt>
<dd class="defbody">
... a number.
</dd>
<dt><strong>natural</strong></dt>
<dd class="defbody">
... a positive integer.
</dd>
<dt><strong>any</strong></dt>
<dd class="defbody">
The corresponding argument of every occurrence of the constraint can 
have any type. This is the default value.
</dd>
</dl>

<dl class="latex">
<dt class="pubdef"><a id="chr_type/1">:- <strong>chr_type</strong>(<var>+TypeDeclaration</var>)</a></dt>
<dd class="defbody">
User-defined types are algebraic data types, similar to those in Haskell 
or the discriminated unions in Mercury. An algebraic data type is 
defined using <a id="idx:chrtype1:1546"></a><a class="pred" href="practical.html#chr_type/1">chr_type/1</a>:

<pre class="code">
:- chr_type type ---&gt; body.
</pre>

<p>If the type term is a functor of arity zero (i.e. one having zero 
arguments), it names a monomorphic type. Otherwise, it names a 
polymorphic type; the arguments of the functor must be distinct type 
variables. The body term is defined as a sequence of constructor 
definitions separated by semi-colons.

<p>Each constructor definition must be a functor whose arguments (if 
any) are types. Discriminated union definitions must be transparent: all 
type variables occurring in the body must also occur in the type.

<p>Here are some examples of algebraic data type definitions:

<pre class="code">
:- chr_type color ---&gt; red ; blue ; yellow ; green.

:- chr_type tree ---&gt;  empty ; leaf(int) ; branch(tree, tree).

:- chr_type list(T) ---&gt; [] ; [T | list(T)].

:- chr_type pair(T1, T2) ---&gt; (T1 - T2).
</pre>

<p>Each algebraic data type definition introduces a distinct type. Two 
algebraic data types that have the same bodies are considered to be 
distinct types (name equivalence).

<p>Constructors may be overloaded among different types: there may be 
any number of constructors with a given name and arity, so long as they 
all have different types.

<p>Aliases can be defined using ==. For example, if your program uses 
lists of lists of integers, you can define an alias as follows:

<pre class="code">
:- chr_type lli == list(list(int)).
</pre>

<p></dd>
</dl>

<p><b>Type Checking</b> 

<p>Currently two complementary forms of type checking are performed:
<ol class="latex">
<li>Static type checking is always performed by the compiler. It is 
limited to CHR rule heads and CHR constraint calls in rule bodies.

<p>Two kinds of type error are detected. The first is where a variable 
has to belong to two types. For example, in the program:

<pre class="code">
:-chr_type foo ---&gt; foo.
:-chr_type bar ---&gt; bar.

:-chr_constraint abc(?foo).
:-chr_constraint def(?bar).

foobar @ abc(X) &lt;=&gt; def(X).
</pre>

<p>the variable <code>X</code> has to be of both type <code>foo</code> 
and <code>bar</code>. This is reported as a type clash error:

<pre class="code">
CHR compiler ERROR:
    `--&gt; Type clash for variable _ in rule foobar:
                expected type foo in body goal def(_, _)
                expected type bar in head def(_, _)
</pre>

<p>The second kind of error is where a functor is used that does not 
belong to the declared type. For example in:

<pre class="code">
:- chr_type foo ---&gt; foo.
:- chr_type bar ---&gt; bar.

:- chr_constraint abc(?foo).

foo @ abc(bar) &lt;=&gt; true.
</pre>

<p><code>bar</code> appears in the head of the rule where something of 
type <code>foo</code> is expected. This is reported as:

<pre class="code">
CHR compiler ERROR:
    `--&gt; Invalid functor in head abc(bar) of rule foo:
                found `bar',
                expected type `foo'!
</pre>

<p>No runtime overhead is incurred in static type checking.

<p>
<li>Dynamic type checking checks at runtime, during program execution, 
whether the arguments of CHR constraints respect their declared types. 
The <a class="pred" href="coroutining.html#when/2">when/2</a> 
co-routining library is used to delay dynamic type checks until 
variables are instantiated.

<p>The kind of error detected by dynamic type checking is where a 
functor is used that does not belong to the declared type. For example, 
for the program:

<pre class="code">
:-chr_type foo ---&gt; foo.

:-chr_constraint abc(?foo).
</pre>

<p>we get the following error in an erroneous query:

<pre class="code">
?- abc(bar).
ERROR: Type error: `foo' expected, found `bar'
       (CHR Runtime Type Error)
</pre>

<p>Dynamic type checking is weaker than static type checking in the 
sense that it only checks the particular program execution at hand 
rather than all possible executions. It is stronger in the sense that it 
tracks types throughout the whole program.

<p>Note that it is enabled only in debug mode, as it incurs some (minor) 
runtime overhead.
</ol>

<p><h3 id="sec:chr-compilation"><a id="sec:7.3.3"><span class="sec-nr">7.3.3</span> <span class="sec-title">Compilation</span></a></h3>

<a id="sec:chr-compilation"></a> The SWI-Prolog CHR compiler exploits <a id="idx:termexpansion2:1547"></a><a class="pred" href="consulting.html#term_expansion/2">term_expansion/2</a> 
rules to translate the constraint handling rules to plain Prolog. These 
rules are loaded from the library <code>library(chr)</code>. They are 
activated if the compiled file has the <code>.chr</code> extension or 
after finding a declaration in the following format:

<pre class="code">
:- chr_constraint ...
</pre>

<p>It is advised to define CHR rules in a module file, where the module 
declaration is immediately followed by including the library(chr) 
library as exemplified below:

<pre class="code">
:- module(zebra, [ zebra/0 ]).
:- use_module(library(chr)).

:- chr_constraint ...
</pre>

<p>Using this style, CHR rules can be defined in ordinary Prolog .pl 
files and the operator definitions required by CHR do not leak into 
modules where they might cause conflicts.

<p></body></html>
swi-prolog-nox 6.6.6-5 / usr / lib / swi-prolog / doc / Manual / practical.html
