/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 5.11.18 Reference Manual: Section 4.19</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
{ 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="termrw.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="manipatom.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>

<H2><A NAME="sec:4.19"><SPAN class="sec-nr">4.19</SPAN> <SPAN class="sec-title">Analysing 
and Constructing Terms</SPAN></A></H2>

<A NAME="sec:manipterm"></A>

<DL class="latex">
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="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 Term is a variable it is unified with a new term whose arguments are 
all different variables (such a term is called a skeleton). If Term is 
atomic, Arity will be unified with the integer 0, and Name will be 
unified with Term. Raises <CODE>instantiation_error()</CODE> if term is 
unbound and <VAR>Name</VAR>/<VAR>Arity</VAR> is insufficiently 
instantiated.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="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">50<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 NAME="idx:arg3:899"></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_then_zero, <VAR>Arg</VAR>)</CODE> if <VAR><VAR>Arg</VAR> 
&lt; 0</VAR>.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="=../2"><VAR>?Term</VAR> <STRONG>=..</STRONG> <VAR>?List</VAR></A></DT>
<DD class="defbody">
<VAR>List</VAR> is a list which head is the functor of <VAR>Term</VAR> 
and the remaining arguments are the arguments of the term. Each of the 
arguments 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 NAME="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 NAME="idx:writeterm3:900"></A><A class="pred" href="termrw.html#write_term/3">write_term/3</A> 
and <A NAME="idx:numbervars4:901"></A><A class="pred" href="manipterm.html#numbervars/4">numbervars/4</A>.</DD>
<DT class="pubdef"><A NAME="numbervars/4"><STRONG>numbervars</STRONG>(<VAR>+Term, 
+Start, -End, +Options</VAR>)</A></DT>
<DD class="defbody">
As <A NAME="idx:numbervars3:902"></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 NAME="idx:numbervars3:903"></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 the a <CODE>type_error</CODE> exception.<SUP class="fn">51<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 NAME="idx:numbervars4:904"></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 NAME="idx:writeterm2:905"></A><A class="pred" href="termrw.html#write_term/2">write_term/2</A> 
using the numbervars option. This option is exploited by <A NAME="idx:portrayclause2:906"></A><A class="pred" href="listing.html#portray_clause/2">portray_clause/2</A> 
and <A NAME="idx:writecanonical2:907"></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 NAME="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">52<SPAN class="fn-text">This 
predicate used to be called free_variables/2 . The name <A NAME="idx:termvariables2:908"></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 NAME="idx:termvariables3:909"></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 = [G367, G366, G371]
X = G367
Y = G366
Z = G371
</PRE>

</DD>
<DT class="pubdef"><A NAME="term_variables/3"><STRONG>term_variables</STRONG>(<VAR>+Term, 
-List, ?Tail</VAR>)</A></DT>
<DD class="defbody">
Difference list version of <A NAME="idx:termvariables2:910"></A><A class="pred" href="manipterm.html#term_variables/2">term_variables/2</A>. 
I.e. <VAR>Tail</VAR> is the tail of the variable-list <VAR>List</VAR>.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="copy_term/2"><STRONG>copy_term</STRONG>(<VAR>+In, 
-Out</VAR>)</A></DT>
<DD class="defbody">
Create a version if <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 attributed copied. The implementation of <A NAME="idx:copyterm2:911"></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 NAME="idx:setarg3:912"></A><A class="pred" href="manipterm.html#setarg/3">setarg/3</A>. 
SWI-Prolog provides
<A NAME="idx:duplicateterm2:913"></A><A class="pred" href="manipterm.html#duplicate_term/2">duplicate_term/2</A> 
to create a true copy of a term.
</DD>
</DL>

<H3><A NAME="sec:4.19.1"><SPAN class="sec-nr">4.19.1</SPAN> <SPAN class="sec-title">Non-logical 
operations on terms</SPAN></A></H3>

<A NAME="sec:setarg"></A>

<P>Prolog is not capable to <EM>modify</EM> instantiated parts of a 
term. Lacking that capability makes that 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 NAME="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 NAME="idx:setarg3:914"></A><A class="pred" href="manipterm.html#setarg/3">setarg/3</A> 
call. See also <A NAME="idx:nbsetarg3:915"></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 NAME="idx:setarg3:916"></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 not copying of 
terms. A good practice to improve somewhat on this situation is to make 
sure that terms whose arguments are subject to <A NAME="idx:setarg3:917"></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 NAME="idx:copyterm2:918"></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 NAME="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 NAME="idx:setarg3:919"></A><A class="pred" href="manipterm.html#setarg/3">setarg/3</A>, 
but on backtracking the assignment is <EM>not</EM> reversed. If <VAR>Term</VAR> 
is not atomic, it is duplicated using <A NAME="idx:duplicateterm2:920"></A><A class="pred" href="manipterm.html#duplicate_term/2">duplicate_term/2</A>. 
This predicate uses the same technique as
<A NAME="idx:nbsetval2:921"></A><A class="pred" href="gvar.html#nb_setval/2">nb_setval/2</A>. 
We therefore refer to the description of <A NAME="idx:nbsetval2:922"></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 NAME="idx:nblinkarg3:923"></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 NAME="idx:flag3:924"></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 NAME="nb_linkarg/3"><STRONG>nb_linkarg</STRONG>(<VAR>+Arg, 
+Term, +Value</VAR>)</A></DT>
<DD class="defbody">
As <A NAME="idx:nbsetarg3:925"></A><A class="pred" href="manipterm.html#nb_setarg/3">nb_setarg/3</A>, 
but like <A NAME="idx:nblinkval2:926"></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 NAME="idx:nblinkval2:927"></A><A class="pred" href="gvar.html#nb_linkval/2">nb_linkval/2</A> 
before use.</DD>
<DT class="pubdef"><A NAME="duplicate_term/2"><STRONG>duplicate_term</STRONG>(<VAR>+In, 
-Out</VAR>)</A></DT>
<DD class="defbody">
Version of <A NAME="idx:copyterm2:928"></A><A class="pred" href="manipterm.html#copy_term/2">copy_term/2</A> 
that also copies ground terms and therefore ensures destructive 
modification using <A NAME="idx:setarg3:929"></A><A class="pred" href="manipterm.html#setarg/3">setarg/3</A> 
does not affect the copy. See also <A NAME="idx:nbsetval2:930"></A><A class="pred" href="gvar.html#nb_setval/2">nb_setval/2</A>, <A NAME="idx:nblinkval2:931"></A><A class="pred" href="gvar.html#nb_linkval/2">nb_linkval/2</A>, <A NAME="idx:nbsetarg3:932"></A><A class="pred" href="manipterm.html#nb_setarg/3">nb_setarg/3</A> 
and <A NAME="idx:nblinkarg3:933"></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 NAME="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 the equivalent and will 
remain the equivalent, even if <A NAME="idx:setarg3:934"></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 5.10.4-3ubuntu1 / usr / lib / swi-prolog / doc / Manual / manipterm.html
