/usr/lib/swi-prolog/doc/Manual/attvar.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 6.1</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="extvar.html">
<link rel="next" href="coroutining.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="extvar.html"><img src="prev.gif" alt="Previous"></a>
<a class="nav" href="coroutining.html"><img src="next.gif" alt="Next"></a>
</div>
<h2 id="sec:attvar"><a id="sec:6.1"><span class="sec-nr">6.1</span> <span class="sec-title">Attributed 
variables</span></a></h2>

<a id="sec:attvar"></a>

<p><em>Attributed variables</em> provide a technique for extending the 
Prolog unification algorithm <cite><a class="cite" href="Bibliography.html#holzbaur:1992">Holzbaur, 
1992</a></cite> by hooking the binding of attributed variables. There is 
no consensus in the Prolog community on the exact definition and 
interface to attributed variables. The SWI-Prolog interface is identical 
to the one realised by Bart Demoen for hProlog <cite><a class="cite" href="Bibliography.html#Demoen:CW350">Demoen, 
2002</a></cite>. This interface is simple and available on all Prolog 
systems that can run the Leuven CHR system (see <a class="sec" href="chr.html">chapter 
7</a> and the Leuven <a class="url" href="http://people.cs.kuleuven.be/~tom.schrijvers/CHR/">CHR 
page</a>).

<p>Binding an attributed variable schedules a goal to be executed at the 
first possible opportunity. In the current implementation the hooks are 
executed immediately after a successful unification of the clause-head 
or successful completion of a foreign language (built-in) predicate. 
Each attribute is associated to a module, and the hook (<a id="idx:attrunifyhook2:1493"></a><a class="pred" href="attvar.html#attr_unify_hook/2">attr_unify_hook/2</a>) 
is executed in this module. The example below realises a very simple and 
incomplete finite domain reasoner:

<pre class="code">
:- module(domain,
          [ domain/2                    % Var, ?Domain
          ]).
:- use_module(library(ordsets)).

domain(X, Dom) :-
        var(Dom), !,
        get_attr(X, domain, Dom).
domain(X, List) :-
        list_to_ord_set(List, Domain),
        put_attr(Y, domain, Domain),
        X = Y.

%       An attributed variable with attribute value Domain has been
%       assigned the value Y

attr_unify_hook(Domain, Y) :-
        (   get_attr(Y, domain, Dom2)
        -&gt;  ord_intersection(Domain, Dom2, NewDomain),
            (   NewDomain == []
            -&gt;  fail
            ;   NewDomain = [Value]
            -&gt;  Y = Value
            ;   put_attr(Y, domain, NewDomain)
            )
        ;   var(Y)
        -&gt;  put_attr( Y, domain, Domain )
        ;   ord_memberchk(Y, Domain)
        ).

%       Translate attributes from this module to residual goals

attribute_goals(X) --&gt;
        { get_attr(X, domain, List) },
        [domain(X, List)].
</pre>

<p>Before explaining the code we give some example queries:
<blockquote>
<table class="latex frame-void">
<tr><td><code>?- domain(X, [a,b]), X = c</code></td><td>fail </td></tr>
<tr><td><code>?- domain(X, [a,b]), domain(X, [a,c]).</code></td><td>X = 
a </td></tr>
<tr><td><code>?- domain(X, [a,b,c]), domain(X, [a,c]).</code></td><td>domain(X, 
[a, c]) </td></tr>
</table>
</blockquote>

<p>The predicate domain/2 fetches (first clause) or assigns (second 
clause) the variable a <em>domain</em>, a set of values the variable can 
be unified with. In the second clause, <a id="idx:domain2:1494"></a><span class="pred-ext">domain/2</span> 
first associates the domain with a fresh variable (Y) and then unifies X 
to this variable to deal with the possibility that X already has a 
domain. The predicate <a id="idx:attrunifyhook2:1495"></a><a class="pred" href="attvar.html#attr_unify_hook/2">attr_unify_hook/2</a> 
(see below) is a hook called after a variable with a domain is assigned 
a value. In the simple case where the variable is bound to a concrete 
value, we simply check whether this value is in the domain. Otherwise we 
take the intersection of the domains and either fail if the intersection 
is empty (first example), assign the value if there is only one value in 
the intersection (second example), or assign the intersection as the new 
domain of the variable (third example). The nonterminal
<a id="idx:attributegoals3:1496"></a><a class="pred" href="attvar.html#attribute_goals/3">attribute_goals/3</a> 
is used to translate remaining attributes to user-readable goals that, 
when executed, reinstate these attributes.

<p><h3 id="sec:attvar-predicates"><a id="sec:6.1.1"><span class="sec-nr">6.1.1</span> <span class="sec-title">Attribute 
manipulation predicates</span></a></h3>

<a id="sec:attvar-predicates"></a>

<dl class="latex">
<dt class="pubdef"><a id="attvar/1"><strong>attvar</strong>(<var>@Term</var>)</a></dt>
<dd class="defbody">
Succeeds if <var>Term</var> is an attributed variable. Note that <a id="idx:var1:1497"></a><a class="pred" href="typetest.html#var/1">var/1</a> 
also succeeds on attributed variables. Attributed variables are created 
with
<a id="idx:putattr3:1498"></a><a class="pred" href="attvar.html#put_attr/3">put_attr/3</a>.</dd>
<dt class="pubdef"><a id="put_attr/3"><strong>put_attr</strong>(<var>+Var, 
+Module, +Value</var>)</a></dt>
<dd class="defbody">
If <var>Var</var> is a variable or attributed variable, set the value 
for the attribute named <var>Module</var> to <var>Value</var>. If an 
attribute with this name is already associated with <var>Var</var>, the 
old value is replaced. Backtracking will restore the old value (i.e., an 
attribute is a mutable term; see also <a id="idx:setarg3:1499"></a><a class="pred" href="manipterm.html#setarg/3">setarg/3</a>). 
This predicate raises a representation error if
<var>Var</var> is not a variable and a type error if <var>Module</var> 
is not an atom.</dd>
<dt class="pubdef"><a id="get_attr/3"><strong>get_attr</strong>(<var>+Var, 
+Module, -Value</var>)</a></dt>
<dd class="defbody">
Request the current <var>value</var> for the attribute named <var>Module</var>. 
If
<var>Var</var> is not an attributed variable or the named attribute is 
not associated to <var>Var</var> this predicate fails silently. If <var>Module</var> 
is not an atom, a type error is raised.</dd>
<dt class="pubdef"><a id="del_attr/2"><strong>del_attr</strong>(<var>+Var, 
+Module</var>)</a></dt>
<dd class="defbody">
Delete the named attribute. If <var>Var</var> loses its last attribute 
it is transformed back into a traditional Prolog variable. If <var>Module</var> 
is not an atom, a type error is raised. In all other cases this 
predicate succeeds regardless of whether or not the named attribute is 
present.
</dd>
</dl>

<p><h3 id="sec:attvar-hooks"><a id="sec:6.1.2"><span class="sec-nr">6.1.2</span> <span class="sec-title">Attributed 
variable hooks</span></a></h3>

<a id="sec:attvar-hooks"></a>

<p>Attribute names are linked to modules. This means that certain 
operations on attributed variables cause <em>hooks</em> to be called in 
the module whose name matches the attribute name.

<dl class="latex">
<dt class="pubdef"><a id="attr_unify_hook/2"><strong>attr_unify_hook</strong>(<var>+AttValue, 
+VarValue</var>)</a></dt>
<dd class="defbody">
A hook that must be defined in the module to which an attributed 
variable refers. It is called <em>after</em> the attributed variable has 
been unified with a non-var term, possibly another attributed variable.
<var>AttValue</var> is the attribute that was associated to the variable 
in this module and <var>VarValue</var> is the new value of the variable. 
Normally this predicate fails to veto binding the variable to
<var>VarValue</var>, forcing backtracking to undo the binding. If
<var>VarValue</var> is another attributed variable the hook often 
combines the two attributes and associates the combined attribute with
<var>VarValue</var> using <a id="idx:putattr3:1500"></a><a class="pred" href="attvar.html#put_attr/3">put_attr/3</a>.</dd>
<dt class="pubdef"><a id="attr_portray_hook/2"><strong>attr_portray_hook</strong>(<var>+AttValue, 
+Var</var>)</a></dt>
<dd class="defbody">
Called by <a id="idx:writeterm2:1501"></a><a class="pred" href="termrw.html#write_term/2">write_term/2</a> 
and friends for each attribute if the option
<code>attributes(portray)</code> is in effect. If the hook succeeds the 
attribute is considered printed. Otherwise <code>Module = ...</code> is 
printed to indicate the existence of a variable. New infrastructure 
dealing with communicating attribute values must be based on
<a id="idx:copyterm3:1502"></a><a class="pred" href="attvar.html#copy_term/3">copy_term/3</a> 
and its hook <a id="idx:attributegoals1:1503"></a><a class="pred" href="attvar.html#attribute_goals/3">attribute_goals/3</a>.</dd>
<dt class="pubdef"><a id="attribute_goals/3"><strong>attribute_goals</strong>(<var>+Var</var>)</a><code>//</code></dt>
<dd class="defbody">
This nonterminal, if it is defined in a module, is used by <a id="idx:copyterm3:1504"></a><a class="pred" href="attvar.html#copy_term/3">copy_term/3</a> 
to project attributes of that module to residual goals. It is also used 
by the top level to obtain residual goals after executing a query.
</dd>
</dl>

<p><h3 id="sec:terms-with-attvars"><a id="sec:6.1.3"><span class="sec-nr">6.1.3</span> <span class="sec-title">Operations 
on terms with attributed variables</span></a></h3>

<a id="sec:terms-with-attvars"></a>

<dl class="latex">
<dt class="pubdef"><a id="copy_term/3"><strong>copy_term</strong>(<var>+Term, 
-Copy, -Gs</var>)</a></dt>
<dd class="defbody">
Create a regular term <var>Copy</var> as a copy of <var>Term</var> 
(without any attributes), and a list <var>Gs</var> of goals that 
represents the attributes. The goal maplist(call,<var>Gs</var>) 
recreates the attributes for <var>Copy</var>. The nonterminal <a id="idx:attributegoals1:1505"></a><a class="pred" href="attvar.html#attribute_goals/3">attribute_goals/3</a>, 
as defined in the modules the attributes stem from, is used to convert 
attributes to lists of goals.

<p>This building block is used by the top level to report pending 
attributes in a portable and understandable fashion. This predicate is 
the preferred way to reason about and communicate terms with 
constraints.</dd>
<dt class="pubdef"><a id="copy_term_nat/2"><strong>copy_term_nat</strong>(<var>+Term, 
-Copy</var>)</a></dt>
<dd class="defbody">
As <a id="idx:copyterm2:1506"></a><a class="pred" href="manipterm.html#copy_term/2">copy_term/2</a>. 
Attributes, however, are <em>not</em> copied but replaced by fresh 
variables.</dd>
<dt class="pubdef"><a id="term_attvars/2"><strong>term_attvars</strong>(<var>+Term, 
-AttVars</var>)</a></dt>
<dd class="defbody">
<var>AttVars</var> is a list of all attributed variables in <var>Term</var> 
and its attributes. That is, <a id="idx:termattvars2:1507"></a><a class="pred" href="attvar.html#term_attvars/2">term_attvars/2</a> 
works recursively through attributes. This predicate is cycle-safe. The 
goal
<code>term_attvars(Term,[])</code> in an efficient test that <var>Term</var> 
has
<em>no</em> attributes; scanning the term is aborted after the first 
attributed variable is found.
</dd>
</dl>

<p><h3 id="sec:attvar-low-level-preds"><a id="sec:6.1.4"><span class="sec-nr">6.1.4</span> <span class="sec-title">Special 
purpose predicates for attributes</span></a></h3>

<a id="sec:attvar-low-level-preds"></a>

<p>Normal user code should deal with <a id="idx:putattr3:1508"></a><a class="pred" href="attvar.html#put_attr/3">put_attr/3</a>, <a id="idx:getattr3:1509"></a><a class="pred" href="attvar.html#get_attr/3">get_attr/3</a> 
and <a id="idx:delattr2:1510"></a><a class="pred" href="attvar.html#del_attr/2">del_attr/2</a>. 
The routines in this section fetch or set the entire attribute list of a 
variable. Use of these predicates is anticipated to be restricted to 
printing and other special purpose operations.

<dl class="latex">
<dt class="pubdef"><a id="get_attrs/2"><strong>get_attrs</strong>(<var>+Var, 
-Attributes</var>)</a></dt>
<dd class="defbody">
Get all attributes of <var>Var</var>. <var>Attributes</var> is a term of 
the form
<code>att(Module, Value, MoreAttributes)</code>, where <var>MoreAttributes</var> 
is
<code>[]</code> for the last attribute.</dd>
<dt class="pubdef"><a id="put_attrs/2"><strong>put_attrs</strong>(<var>+Var, 
-Attributes</var>)</a></dt>
<dd class="defbody">
Set all attributes of <var>Var</var>. See <a id="idx:getattrs2:1511"></a><a class="pred" href="attvar.html#get_attrs/2">get_attrs/2</a> 
for a description of
<var>Attributes</var>.</dd>
<dt class="pubdef"><a id="del_attrs/1"><strong>del_attrs</strong>(<var>+Var</var>)</a></dt>
<dd class="defbody">
If <var>Var</var> is an attributed variable, delete <em>all</em> its 
attributes. In all other cases, this predicate succeeds without 
side-effects.
</dd>
</dl>

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