This file is indexed.

/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)
        -&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>