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

<H2><A NAME="sec:6.1"><SPAN class="sec-nr">6.1</SPAN> <SPAN class="sec-title">Attributed 
variables</SPAN></A></H2>

<A NAME="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">section 
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 NAME="idx:attrunifyhook2:1298"></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 BORDER=0 FRAME=void RULES=groups>
<TR VALIGN=top><TD><TT>?- domain(X, [a,b]), X = c</TT></TD><TD>fail </TD></TR>
<TR VALIGN=top><TD><TT>?- domain(X, [a,b]), domain(X, [a,c]).</TT></TD><TD>X 
= a </TD></TR>
<TR VALIGN=top><TD><TT>?- domain(X, [a,b,c]), domain(X, [a,c]).</TT></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 it can be 
unified with. In the second clause first associates the domain with a 
fresh variable and then unifies X to this variable to deal with the 
possibility that X already has a domain. The predicate <A NAME="idx:attrunifyhook2:1299"></A><A class="pred" href="attvar.html#attr_unify_hook/2">attr_unify_hook/2</A> 
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), simply 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 NAME="idx:attributegoals3:1300"></A><SPAN class="pred-ext">attribute_goals/3</SPAN> 
is used to translate remaining attributes to user-readable goals that, 
when executed, reinstate these attributes.

<H3><A NAME="sec:6.1.1"><SPAN class="sec-nr">6.1.1</SPAN> <SPAN class="sec-title">Attribute 
manipulation predicates</SPAN></A></H3>

<DL class="latex">
<DT class="pubdef"><A NAME="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 NAME="idx:var1:1301"></A><A class="pred" href="typetest.html#var/1">var/1</A> 
also succeeds on attributed variables. Attributed variables are created 
with
<A NAME="idx:putattr3:1302"></A><A class="pred" href="attvar.html#put_attr/3">put_attr/3</A>.</DD>
<DT class="pubdef"><A NAME="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 NAME="idx:setarg3:1303"></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 NAME="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 NAME="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 whether or not the named attribute is 
present.
</DD>
</DL>

<H3><A NAME="sec:6.1.2"><SPAN class="sec-nr">6.1.2</SPAN> <SPAN class="sec-title">Attributed 
variable hooks</SPAN></A></H3>

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

<DL class="latex">
<DT class="pubdef"><A NAME="attr_unify_hook/2"><STRONG>attr_unify_hook</STRONG>(<VAR>+AttValue, 
+VarValue</VAR>)</A></DT>
<DD class="defbody">
Hook that must be defined in the module an attributed variable refers 
to. Is 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 attribute and associates the combined attribute with
<VAR>VarValue</VAR> using <A NAME="idx:putattr3:1304"></A><A class="pred" href="attvar.html#put_attr/3">put_attr/3</A>.</DD>
<DT class="pubdef"><A NAME="attr_portray_hook/2"><STRONG>attr_portray_hook</STRONG>(<VAR>+AttValue, 
+Var</VAR>)</A></DT>
<DD class="defbody">
Called by <A NAME="idx:writeterm2:1305"></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 NAME="idx:copyterm3:1306"></A><A class="pred" href="attvar.html#copy_term/3">copy_term/3</A> 
and its hook <A NAME="idx:attributegoals1:1307"></A><SPAN class="pred-ext">attribute_goals/3</SPAN>.</DD>
<DT class="pubdef"><A NAME="attribute_goals/1"><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 NAME="idx:copyterm3:1308"></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 toplevel to obtain residual goals after executing a query.
</DD>
</DL>

<H3><A NAME="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>

<DL class="latex">
<DT class="pubdef"><A NAME="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 NAME="idx:attributegoals1:1309"></A><SPAN class="pred-ext">attribute_goals/3</SPAN>, 
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 toplevel 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 NAME="copy_term_nat/2"><STRONG>copy_term_nat</STRONG>(<VAR>+Term, 
-Copy</VAR>)</A></DT>
<DD class="defbody">
As <A NAME="idx:copyterm2:1310"></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 NAME="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. I.e., <A NAME="idx:termattvars2:1311"></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. I.e., scanning the term is aborted after the 
first attributed variable is found.
</DD>
</DL>

<H3><A NAME="sec:6.1.4"><SPAN class="sec-nr">6.1.4</SPAN> <SPAN class="sec-title">Special 
purpose predicates for attributes</SPAN></A></H3>

<P>Normal user code should deal with <A NAME="idx:putattr3:1312"></A><A class="pred" href="attvar.html#put_attr/3">put_attr/3</A>, <A NAME="idx:getattr3:1313"></A><A class="pred" href="attvar.html#get_attr/3">get_attr/3</A> 
and <A NAME="idx:delattr2:1314"></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 
variables. Use of these predicates is anticipated to be restricted to 
printing and other special purpose operations.

<DL class="latex">
<DT class="pubdef"><A NAME="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 NAME="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 NAME="idx:getattrs2:1315"></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 NAME="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 5.10.4-3ubuntu1 / usr / lib / swi-prolog / doc / Manual / attvar.html
