/usr/share/doc/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.6.59 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=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;
}

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="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, 
1990</A></CITE> by hooking the binding of attributed variables. There is 
little 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>.

<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:1199"></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:

<P>
<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>

<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:1200"></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:1201"></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.

<DL>
<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:1202"></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:1203"></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:1204"></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>
<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:1205"></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:1206"></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.</DD>
<DT class="pubdef"><A NAME="attribute_goals/3"><STRONG>attribute_goals</STRONG>(<VAR>+Var, 
-Gs, +GsRest</VAR>)</A></DT>
<DD class="defbody">
This nonterminal, if it is defined in a module, is used by <A NAME="idx:copyterm3:1207"></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.1"><SPAN class="sec-nr">6.1.1</SPAN> <SPAN class="sec-title">Special 
purpose predicates for attributes</SPAN></A></H3>

<P>Normal user code should deal with <A NAME="idx:putattr3:1208"></A><A class="pred" href="attvar.html#put_attr/3">put_attr/3</A>, <A NAME="idx:getattr3:1209"></A><A class="pred" href="attvar.html#get_attr/3">get_attr/3</A> 
and <A NAME="idx:delattr2:1210"></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>
<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:1211"></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="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 when 
executed reinstate all attributes onto <VAR>Copy</VAR>. The nonterminal
<A NAME="idx:attributegoals1:1212"></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.</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:1213"></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>
</DL>

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