/usr/share/doc/swi-prolog-doc/Manual/attvar.html is in swi-prolog-doc 5.6.59-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 | <!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)
-> ord_intersection(Domain, Dom2, NewDomain),
( NewDomain == []
-> fail
; NewDomain = [Value]
-> Y = Value
; put_attr(Y, domain, NewDomain)
)
; var(Y)
-> put_attr( Y, domain, Domain )
; ord_memberchk(Y, Domain)
).
% Translate attributes from this module to residual goals
attribute_goals(X) -->
{ 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>
|