/usr/lib/swi-prolog/doc/Manual/manipterm.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 4.20</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="termrw.html">
<link rel="next" href="manipatom.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="termrw.html"><img src="prev.gif" alt="Previous"></a>
<a class="nav" href="manipatom.html"><img src="next.gif" alt="Next"></a>
</div>
<h2 id="sec:manipterm"><a id="sec:4.20"><span class="sec-nr">4.20</span> <span class="sec-title">Analysing 
and Constructing Terms</span></a></h2>

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

<dl class="latex">
<dt class="pubdef"><span class="pred-tag">[ISO]</span><a id="functor/3"><strong>functor</strong>(<var>?Term, 
?Name, ?Arity</var>)</a></dt>
<dd class="defbody">
True when <var>Term</var> is a term with functor <var>Name</var>/<var>Arity</var>. 
If
<var>Term</var> is a variable it is unified with a new term whose 
arguments are all different variables (such a term is called a 
skeleton). If <var>Term</var> is atomic, <var>Arity</var> will be 
unified with the integer 0, and <var>Name</var> will be unified with <var>Term</var>. 
Raises <code>instantiation_error()</code> if <var>Term</var> is unbound 
and <var>Name</var>/<var>Arity</var> is insufficiently instantiated.</dd>
<dt class="pubdef"><span class="pred-tag">[ISO]</span><a id="arg/3"><strong>arg</strong>(<var>?Arg, 
+Term, ?Value</var>)</a></dt>
<dd class="defbody">
<var>Term</var> should be instantiated to a term, <var>Arg</var> to an 
integer between 1 and the arity of <var>Term</var>. <var>Value</var> is 
unified with the
<var>Arg</var>-th argument of <var>Term</var>. <var>Arg</var> may also 
be unbound. In this case <var>Value</var> will be unified with the 
successive arguments of the term. On successful unification, <var>Arg</var> 
is unified with the argument number. Backtracking yields alternative 
solutions.<sup class="fn">68<span class="fn-text">The instantiation 
pattern (-, +, ?) is an extension to `standard' Prolog. Some systems 
provide genarg/3 that covers this pattern.</span></sup> The predicate <a id="idx:arg3:1035"></a><a class="pred" href="manipterm.html#arg/3">arg/3</a> 
fails silently if <var><var>Arg</var> = 0</var> or
<var><var>Arg</var> &gt; <em>arity</em></var> and raises the exception
<code>domain_error(not_less_than_zero, <var>Arg</var>)</code> if <var><var>Arg</var> 
&lt; 0</var>.</dd>
<dt class="pubdef"><span class="pred-tag">[ISO]</span><a id="=../2"><var>?Term</var> <strong>=..</strong> <var>?List</var></a></dt>
<dd class="defbody">
<var>List</var> is a list whose head is the functor of <var>Term</var> 
and the remaining arguments are the arguments of the term. Either side 
of the predicate may be a variable, but not both. This predicate is 
called `Univ'. Examples:

<pre class="code">
?- foo(hello, X) =.. List.

List = [foo, hello, X]

?- Term =.. [baz, foo(1)]

Term = baz(foo(1))
</pre>

</dd>
<dt class="pubdef"><a id="numbervars/3"><strong>numbervars</strong>(<var>+Term, 
+Start, -End</var>)</a></dt>
<dd class="defbody">
Unify the free variables of <var>Term</var> with a term <code>$VAR(N)</code>, 
where <var>N</var> is the number of the variable. Counting starts at
<var>Start</var>. <var>End</var> is unified with the number that should 
be given to the next variable. Example:

<pre class="code">
?- numbervars(foo(A, B, A), 0, End).
A = '$VAR'(0),
B = '$VAR'(1),
End = 2.
</pre>

<p>See also the <code>numbervars</code> option to <a id="idx:writeterm3:1036"></a><a class="pred" href="termrw.html#write_term/3">write_term/3</a> 
and <a id="idx:numbervars4:1037"></a><a class="pred" href="manipterm.html#numbervars/4">numbervars/4</a>.</dd>
<dt class="pubdef"><a id="numbervars/4"><strong>numbervars</strong>(<var>+Term, 
+Start, -End, +Options</var>)</a></dt>
<dd class="defbody">
As <a id="idx:numbervars3:1038"></a><a class="pred" href="manipterm.html#numbervars/3">numbervars/3</a>, 
but providing the following options:

<dl class="latex">
<dt><strong>functor_name</strong>(<var>+Atom</var>)</dt>
<dd class="defbody">
Name of the functor to use instead of <code>$VAR</code>.</dd>
<dt><strong>attvar</strong>(<var>+Action</var>)</dt>
<dd class="defbody">
What to do if an attributed variable is encountered. Options are
<code>skip</code>, which causes <a id="idx:numbervars3:1039"></a><a class="pred" href="manipterm.html#numbervars/3">numbervars/3</a> 
to ignore the attributed variable, <code>bind</code> which causes it to 
thread it as a normal variable and assign the next <code>'$VAR'</code>(N) 
term to it, or (default)
<code>error</code> which raises a <code>type_error</code> exception.<sup class="fn">69<span class="fn-text">This 
behaviour was decided after a long discussion between David Reitter, 
Richard O'Keefe, Bart Demoen and Tom Schrijvers.</span></sup></dd>
<dt><strong>singletons</strong>(<var>+Bool</var>)</dt>
<dd class="defbody">
If <code>true</code> (default <code>false</code>), <a id="idx:numbervars4:1040"></a><a class="pred" href="manipterm.html#numbervars/4">numbervars/4</a> 
does singleton detection. Singleton variables are unified with <code>'$VAR'('_')</code>, 
causing them to be printed as <code>_</code> by <a id="idx:writeterm2:1041"></a><a class="pred" href="termrw.html#write_term/2">write_term/2</a> 
using the numbervars option. This option is exploited by <a id="idx:portrayclause2:1042"></a><a class="pred" href="listing.html#portray_clause/2">portray_clause/2</a> 
and <a id="idx:writecanonical2:1043"></a><a class="pred" href="termrw.html#write_canonical/2">write_canonical/2</a>.<sup class="fn">bug<span class="fn-text">Currently 
this option is ignored for cyclic terms.</span></sup>
</dd>
</dl>

</dd>
<dt class="pubdef"><a id="var_number/2"><strong>var_number</strong>(<var>@Term, 
-VarNumber</var>)</a></dt>
<dd class="defbody">
True if <var>Term</var> is numbered by <a id="idx:numbervars3:1044"></a><a class="pred" href="manipterm.html#numbervars/3">numbervars/3</a> 
and <var>VarNumber</var> is the number given to this variable. This 
predicate avoids the need for unification with <code>'$VAR'(X)</code> 
and opens the path for replacing this valid Prolog term by an internal 
representation that has no textual equivalent.</dd>
<dt class="pubdef"><span class="pred-tag">[ISO]</span><a id="term_variables/2"><strong>term_variables</strong>(<var>+Term, 
-List</var>)</a></dt>
<dd class="defbody">
Unify <var>List</var> with a list of variables, each sharing with a 
unique variable of <var>Term</var>.<sup class="fn">70<span class="fn-text">This 
predicate used to be called free_variables/2 . The name <a id="idx:termvariables2:1045"></a><a class="pred" href="manipterm.html#term_variables/2">term_variables/2</a> 
is more widely used. The old predicate is still available from the 
library <code>library(backcomp)</code>.</span></sup> The variables in <var>List</var> 
are ordered in order of appearance traversing <var>Term</var> 
depth-first and left-to-right. See also
<a id="idx:termvariables3:1046"></a><a class="pred" href="manipterm.html#term_variables/3">term_variables/3</a>. 
For example:

<pre class="code">
?- term_variables(a(X, b(Y, X), Z), L).
L = [X, Y, Z].
</pre>

</dd>
<dt class="pubdef"><a id="term_variables/3"><strong>term_variables</strong>(<var>+Term, 
-List, ?Tail</var>)</a></dt>
<dd class="defbody">
Difference list version of <a id="idx:termvariables2:1047"></a><a class="pred" href="manipterm.html#term_variables/2">term_variables/2</a>. 
That is, <var>Tail</var> is the tail of the variable list <var>List</var>.</dd>
<dt class="pubdef"><span class="pred-tag">[ISO]</span><a id="copy_term/2"><strong>copy_term</strong>(<var>+In, 
-Out</var>)</a></dt>
<dd class="defbody">
Create a version of <var>In</var> with renamed (fresh) variables and 
unify it to <var>Out</var>. Attributed variables (see <a class="sec" href="attvar.html">section 
6.1</a>) have their attributes copied. The implementation of <a id="idx:copyterm2:1048"></a><a class="pred" href="manipterm.html#copy_term/2">copy_term/2</a> 
can deal with infinite trees (cyclic terms). As pure Prolog cannot 
distinguish a ground term from another ground term with exactly the same 
structure, ground sub-terms are <em>shared</em> between <var>In</var> 
and <var>Out</var>. Sharing ground terms does affect <a id="idx:setarg3:1049"></a><a class="pred" href="manipterm.html#setarg/3">setarg/3</a>. 
SWI-Prolog provides
<a id="idx:duplicateterm2:1050"></a><a class="pred" href="manipterm.html#duplicate_term/2">duplicate_term/2</a> 
to create a true copy of a term.
</dd>
</dl>

<p><h3 id="sec:setarg"><a id="sec:4.20.1"><span class="sec-nr">4.20.1</span> <span class="sec-title">Non-logical 
operations on terms</span></a></h3>

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

<p>Prolog is not able to <em>modify</em> instantiated parts of a term. 
Lacking that capability makes the language much safer, but unfortunately 
there are problems that suffer severely in terms of time and/or memory 
usage. Always try hard to avoid the use of these primitives, but they 
can be a good alternative to using dynamic predicates. See also <a class="sec" href="gvar.html">section 
6.3</a>, discussing the use of global variables.

<dl class="latex">
<dt class="pubdef"><a id="setarg/3"><strong>setarg</strong>(<var>+Arg, 
+Term, +Value</var>)</a></dt>
<dd class="defbody">
Extra-logical predicate. Assigns the <var>Arg</var>-th argument of the 
compound term <var>Term</var> with the given <var>Value</var>. The 
assignment is undone if backtracking brings the state back into a 
position before the <a id="idx:setarg3:1051"></a><a class="pred" href="manipterm.html#setarg/3">setarg/3</a> 
call. See also <a id="idx:nbsetarg3:1052"></a><a class="pred" href="manipterm.html#nb_setarg/3">nb_setarg/3</a>.

<p>This predicate may be used for destructive assignment to terms, using 
them as an extra-logical storage bin. Always try hard to avoid the use 
of <a id="idx:setarg3:1053"></a><a class="pred" href="manipterm.html#setarg/3">setarg/3</a> 
as it is not supported by many Prolog systems and one has to be very 
careful about unexpected copying as well as unexpected noncopying of 
terms. A good practice to improve somewhat on this situation is to make 
sure that terms whose arguments are subject to <a id="idx:setarg3:1054"></a><a class="pred" href="manipterm.html#setarg/3">setarg/3</a> 
have one unused and unshared variable in addition to the used arguments. 
This variable avoids unwanted sharing in, e.g., <a id="idx:copyterm2:1055"></a><a class="pred" href="manipterm.html#copy_term/2">copy_term/2</a>, 
and causes the term to be considered as non-ground.</dd>
<dt class="pubdef"><a id="nb_setarg/3"><strong>nb_setarg</strong>(<var>+Arg, 
+Term, +Value</var>)</a></dt>
<dd class="defbody">
Assigns the <var>Arg</var>-th argument of the compound term <var>Term</var> 
with the given <var>Value</var> as <a id="idx:setarg3:1056"></a><a class="pred" href="manipterm.html#setarg/3">setarg/3</a>, 
but on backtracking the assignment is <em>not</em> reversed. If <var>Value</var> 
is not atomic, it is duplicated using <a id="idx:duplicateterm2:1057"></a><a class="pred" href="manipterm.html#duplicate_term/2">duplicate_term/2</a>. 
This predicate uses the same technique as
<a id="idx:nbsetval2:1058"></a><a class="pred" href="gvar.html#nb_setval/2">nb_setval/2</a>. 
We therefore refer to the description of <a id="idx:nbsetval2:1059"></a><a class="pred" href="gvar.html#nb_setval/2">nb_setval/2</a> 
for details on non-backtrackable assignment of terms. This predicate is 
compatible with GNU-Prolog <code>setarg(A,T,V,false)</code>, removing 
the type restriction on <var>Value</var>. See also <a id="idx:nblinkarg3:1060"></a><a class="pred" href="manipterm.html#nb_linkarg/3">nb_linkarg/3</a>. 
Below is an example for counting the number of solutions of a goal. Note 
that this implementation is thread-safe, reentrant and capable of 
handling exceptions. Realising these features with a traditional 
implementation based on assert/retract or <a id="idx:flag3:1061"></a><a class="pred" href="db.html#flag/3">flag/3</a> 
is much more complicated.

<pre class="code">
:- meta_predicate
        succeeds_n_times(0, -).

succeeds_n_times(Goal, Times) :-
        Counter = counter(0),
        (   Goal,
            arg(1, Counter, N0),
            N is N0 + 1,
            nb_setarg(1, Counter, N),
            fail
        ;   arg(1, Counter, Times)
        ).
</pre>

</dd>
<dt class="pubdef"><a id="nb_linkarg/3"><strong>nb_linkarg</strong>(<var>+Arg, 
+Term, +Value</var>)</a></dt>
<dd class="defbody">
As <a id="idx:nbsetarg3:1062"></a><a class="pred" href="manipterm.html#nb_setarg/3">nb_setarg/3</a>, 
but like <a id="idx:nblinkval2:1063"></a><a class="pred" href="gvar.html#nb_linkval/2">nb_linkval/2</a> 
it does <em>not</em> duplicate
<var>Value</var>. Use with extreme care and consult the documentation of <a id="idx:nblinkval2:1064"></a><a class="pred" href="gvar.html#nb_linkval/2">nb_linkval/2</a> 
before use.</dd>
<dt class="pubdef"><a id="duplicate_term/2"><strong>duplicate_term</strong>(<var>+In, 
-Out</var>)</a></dt>
<dd class="defbody">
Version of <a id="idx:copyterm2:1065"></a><a class="pred" href="manipterm.html#copy_term/2">copy_term/2</a> 
that also copies ground terms and therefore ensures that destructive 
modification using <a id="idx:setarg3:1066"></a><a class="pred" href="manipterm.html#setarg/3">setarg/3</a> 
does not affect the copy. See also <a id="idx:nbsetval2:1067"></a><a class="pred" href="gvar.html#nb_setval/2">nb_setval/2</a>, <a id="idx:nblinkval2:1068"></a><a class="pred" href="gvar.html#nb_linkval/2">nb_linkval/2</a>, <a id="idx:nbsetarg3:1069"></a><a class="pred" href="manipterm.html#nb_setarg/3">nb_setarg/3</a> 
and <a id="idx:nblinkarg3:1070"></a><a class="pred" href="manipterm.html#nb_linkarg/3">nb_linkarg/3</a>.</dd>
<dt class="pubdef"><span class="pred-tag">[semidet]</span><a id="same_term/2"><strong>same_term</strong>(<var>@T1, 
@T2</var>)</a></dt>
<dd class="defbody">
True if <var>T1</var> and <var>T2</var> are equivalent and will remain 
equivalent, even if <a id="idx:setarg3:1071"></a><a class="pred" href="manipterm.html#setarg/3">setarg/3</a> 
is used on either of them. This means
<var>T1</var> and <var>T2</var> are the same variable, equivalent atomic 
data or a compound term allocated at the same address.
</dd>
</dl>

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