/usr/lib/swi-prolog/doc/Manual/metacall.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.8</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="control.html">
<LINK REL=next HREF="exception.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="control.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="exception.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>

<H2><A NAME="sec:4.8"><SPAN class="sec-nr">4.8</SPAN> <SPAN class="sec-title">Meta-Call 
Predicates</SPAN></A></H2>

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

<P>Meta-call predicates are used to call terms constructed at run time. 
The basic meta-call mechanism offered by SWI-Prolog is to use variables 
as a subclause (which should of course be bound to a valid goal at 
runtime). A meta-call is slower than a normal call as it involves 
actually searching the database at runtime for the predicate, while for 
normal calls this search is done at compile time.

<DL class="latex">
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="call/1"><STRONG>call</STRONG>(<VAR>:Goal</VAR>)</A></DT>
<DD class="defbody">
Invoke <VAR>Goal</VAR> as a goal. Note that clauses may have variables 
as subclauses, which is identical to <A NAME="idx:call1:525"></A><A class="pred" href="metacall.html#call/1">call/1</A>.</DD>
<DT class="pubdef"><A NAME="call/2"><STRONG>call</STRONG>(<VAR>:Goal, 
+ExtraArg1, ...</VAR>)</A></DT>
<DD class="defbody">
Append <VAR>ExtraArg1, ExtraArg2, ...</VAR> to the argument list of
<VAR>Goal</VAR> and call the result. For example, <CODE>call(plus(1), 2, 
X)</CODE> will call <CODE>plus(1, 2, X)</CODE>, binding <VAR>X</VAR> to 
3.

<P>The call/[2..] construct is handled by the compiler, which implies 
that redefinition as a predicate has no effect. The predicates <A NAME="idx:call26:526"></A><A class="pred" href="metacall.html#call/2">call/[2-6]</A> 
are defined as real predicates, so they can be handled by interpreted 
code.</DD>
<DT class="pubdef"><A NAME="apply/2"><STRONG>apply</STRONG>(<VAR>:Goal, 
+List</VAR>)</A></DT>
<DD class="defbody">
Append the members of <VAR>List</VAR> to the arguments of <VAR>Goal</VAR> 
and call the resulting term. For example: <CODE>apply(plus(1), [2, X])</CODE> 
will call <CODE>plus(1, 2, X)</CODE>. <A NAME="idx:apply2:527"></A><A class="pred" href="metacall.html#apply/2">apply/2</A> 
is incorporated in the virtual machine of SWI-Prolog. This implies that 
the overhead can be compared to the overhead of <A NAME="idx:call1:528"></A><A class="pred" href="metacall.html#call/1">call/1</A>. 
New code should use call/[2..] if the length of
<VAR>List</VAR> is fixed, which is more widely supported and faster 
because there is no need to build and examine the argument list.</DD>
<DT class="pubdef"><A NAME="not/1"><STRONG>not</STRONG>(<VAR>:Goal</VAR>)</A></DT>
<DD class="defbody">
True if <VAR>Goal</VAR> cannot be proven. Retained for compatibility 
only. New code should use <A class="pred" href="control.html#\+/1">\+/1</A>.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="once/1"><STRONG>once</STRONG>(<VAR>:Goal</VAR>)</A></DT>
<DD class="defbody">
Defined as:

<PRE class="code">
once(Goal) :-
        Goal, !.
</PRE>

<P><A NAME="idx:once1:529"></A><A class="pred" href="metacall.html#once/1">once/1</A> 
can in many cases be replaced with <A class="pred" href="control.html#send_arrow/2">-&gt;/2</A>. 
The only difference is how the cut behaves (see !/0). The following two 
clauses are identical:

<PRE class="code">
1) a :- once((b, c)), d.
2) a :- b, c -&gt; d.
</PRE>

</DD>
<DT class="pubdef"><A NAME="ignore/1"><STRONG>ignore</STRONG>(<VAR>:Goal</VAR>)</A></DT>
<DD class="defbody">
Calls <VAR>Goal</VAR> as <A NAME="idx:once1:530"></A><A class="pred" href="metacall.html#once/1">once/1</A>, 
but succeeds, regardless of whether
<VAR>Goal</VAR> succeeded or not. Defined as:

<PRE class="code">
ignore(Goal) :-
        Goal, !.
ignore(_).
</PRE>

</DD>
<DT class="pubdef"><A NAME="call_with_depth_limit/3"><STRONG>call_with_depth_limit</STRONG>(<VAR>:Goal, 
+Limit, -Result</VAR>)</A></DT>
<DD class="defbody">
If <VAR>Goal</VAR> can be proven without recursion deeper than <VAR>Limit</VAR> 
levels, <A NAME="idx:callwithdepthlimit3:531"></A><A class="pred" href="metacall.html#call_with_depth_limit/3">call_with_depth_limit/3</A> 
succeeds, binding <VAR>Result</VAR> to the deepest recursion level used 
during the proof. Otherwise, <VAR>Result</VAR> is unified with <CODE>depth_limit_exceeded</CODE> 
if the limit was exceeded during the proof, or the entire predicate 
fails if <VAR>Goal</VAR> fails without exceeding <VAR>Limit</VAR>.

<P>The depth-limit is guarded by the internal machinery. This may differ 
from the depth computed based on a theoretical model. For example,
<A NAME="idx:true0:532"></A><A class="pred" href="control.html#true/0">true/0</A> 
is translated into an inlined virtual machine instruction. Also,
<A NAME="idx:repeat0:533"></A><A class="pred" href="control.html#repeat/0">repeat/0</A> 
is not implemented as below, but as a non-deterministic foreign 
predicate.

<PRE class="code">
repeat.
repeat :-
        repeat.
</PRE>

<P>As a result, <A NAME="idx:callwithdepthlimit3:534"></A><A class="pred" href="metacall.html#call_with_depth_limit/3">call_with_depth_limit/3</A> 
may still loop infinitely on programs that should theoretically finish 
in finite time. This problem can be cured by using Prolog equivalents to 
such built-in predicates.

<P>This predicate may be used for theorem-provers to realise techniques 
like <EM>iterative deepening</EM>. It was implemented after discussion 
with Steve Moyle <A class="url" href="mailto:smoyle@ermine.ox.ac.uk">smoyle@ermine.ox.ac.uk</A>.</DD>
<DT class="pubdef"><A NAME="setup_call_cleanup/3"><STRONG>setup_call_cleanup</STRONG>(<VAR>:Setup, 
:Goal, :Cleanup</VAR>)</A></DT>
<DD class="defbody">
Calls <CODE>(once(Setup), Goal)</CODE>. If <VAR>Setup</VAR> succeeds, <VAR>Cleanup</VAR> 
will be called exactly once after <VAR>Goal</VAR> is finished: either on 
failure, deterministic success, commit, or an exception. The execution 
of
<VAR>Setup</VAR> is protected from asynchronous interrupts like
<A NAME="idx:callwithtimelimit2:535"></A><SPAN class="pred-ext">call_with_time_limit/2</SPAN> 
(package clib) or <A NAME="idx:threadsignal2:536"></A><A class="pred" href="threadcom.html#thread_signal/2">thread_signal/2</A>. 
In most uses,
<VAR>Setup</VAR> will perform temporary side-effects required by <VAR>Goal</VAR> 
that are finally undone by <VAR>Cleanup</VAR>.

<P>Success or failure of <VAR>Cleanup</VAR> is ignored and choice-points 
it created are destroyed (as <A NAME="idx:once1:537"></A><A class="pred" href="metacall.html#once/1">once/1</A>). 
If <VAR>Cleanup</VAR> throws an exception, this is executed as normal.<SUP class="fn">bug<SPAN class="fn-text">During 
the execution of <VAR>Cleanup</VAR>, garbage collection and stack-shifts 
are disabled.</SPAN></SUP>

<P>Typically, this predicate is used to cleanup permanent data storage 
required to execute <VAR>Goal</VAR>, close file-descriptors, etc. The 
example below provides a non-deterministic search for a term in a file, 
closing the stream as needed.

<PRE class="code">
term_in_file(Term, File) :-
        setup_call_cleanup(open(File, read, In),
                           term_in_stream(Term, In),
                           close(In) ).

term_in_stream(Term, In) :-
        repeat,
        read(In, T),
        (   T == end_of_file
        -&gt;  !, fail
        ;   T = Term
        ).
</PRE>

<P>Note that it is impossible to implement this predicate in Prolog. The 
closest approximation would be to read all terms into a list, close the 
file and call <A NAME="idx:member2:538"></A><A class="pred" href="lists.html#member/2">member/2</A>. 
Without <A NAME="idx:setupcallcleanup3:539"></A><A class="pred" href="metacall.html#setup_call_cleanup/3">setup_call_cleanup/3</A> 
there is no way to gain control if the choice-point left by repeat is 
removed by a cut or an exception.

<P><A NAME="idx:setupcallcleanup3:540"></A><A class="pred" href="metacall.html#setup_call_cleanup/3">setup_call_cleanup/3</A> 
can also be used to test determinism of a goal, providing a portable 
alternative to <A NAME="idx:deterministic1:541"></A><A class="pred" href="manipstack.html#deterministic/1">deterministic/1</A>:

<PRE class="code">
?- setup_call_cleanup(true,(X=1;X=2), Det=yes).

X = 1 ;

X = 2,
Det = yes ;
</PRE>

<P>This predicate is under consideration for inclusion into the ISO 
standard. For compatibility with other Prolog implementations see <A NAME="idx:callcleanup2:542"></A><A class="pred" href="metacall.html#call_cleanup/2">call_cleanup/2</A>.</DD>
<DT class="pubdef"><A NAME="setup_call_catcher_cleanup/4"><STRONG>setup_call_catcher_cleanup</STRONG>(<VAR>:Setup, 
:Goal, +Catcher, :Cleanup</VAR>)</A></DT>
<DD class="defbody">
Similar to <CODE>setup_call_cleanup(Setup, Goal, Cleanup)</CODE> with 
additional information on the reason of calling <VAR>Cleanup</VAR>. 
Prior to calling <VAR>Cleanup</VAR>, <VAR>Catcher</VAR> unifies with the 
termination code (see below). If this unification fails, <VAR>Cleanup</VAR> 
is
<EM>not</EM> called.

<DL class="latex">
<DT><STRONG>exit</STRONG></DT>
<DD class="defbody">
<VAR>Goal</VAR> succeeded without leaving any choice-points.</DD>
<DT><STRONG>fail</STRONG></DT>
<DD class="defbody">
<VAR>Goal</VAR> failed.</DD>
<DT><STRONG><CODE>!</CODE></STRONG></DT>
<DD class="defbody">
<VAR>Goal</VAR> succeeded with choice-points and these are now discarded 
by the execution of a cut (or other pruning of the search tree such as 
if-then-else).</DD>
<DT><STRONG>exception</STRONG>(<VAR>Exception</VAR>)</DT>
<DD class="defbody">
<VAR>Goal</VAR> raised the given <VAR>Exception</VAR>.</DD>
<DT><STRONG>external_exception</STRONG>(<VAR>Exception</VAR>)</DT>
<DD class="defbody">
<VAR>Goal</VAR> succeeded with choice-points and these are now discarded 
due to an exception. For example:

<PRE class="code">
?- setup_call_catcher_cleanup(true, (X=1;X=2),
                              Catcher, writeln(Catcher)),
   throw(ball).
external_exception(ball)
ERROR: Unhandled exception: Unknown message: ball
</PRE>

<P></DD>
</DL>

</DD>
<DT class="pubdef"><A NAME="call_cleanup/2"><STRONG>call_cleanup</STRONG>(<VAR>:Goal, 
:Cleanup</VAR>)</A></DT>
<DD class="defbody">
Same as <CODE>setup_call_cleanup(true, Goal, Cleanup)</CODE>. This is 
provided for compatibility with a number of other Prolog implementations 
only. Do not use <A NAME="idx:callcleanup2:543"></A><A class="pred" href="metacall.html#call_cleanup/2">call_cleanup/2</A>, 
if you perform side-effects prior to calling, that will be undone by <VAR>Cleanup</VAR>. 
Instead, use
<A NAME="idx:setupcallcleanup3:544"></A><A class="pred" href="metacall.html#setup_call_cleanup/3">setup_call_cleanup/3</A> 
with an appropriate first argument to perform those side-effects.</DD>
<DT class="pubdef"><A NAME="call_cleanup/3"><STRONG>call_cleanup</STRONG>(<VAR>:Goal, 
+Catcher, :Cleanup</VAR>)</A></DT>
<DD class="defbody">
Same as <CODE>setup_call_catcher_cleanup(true, Goal, Catcher, Cleanup)</CODE>. 
The same warning as for <A NAME="idx:callcleanup2:545"></A><A class="pred" href="metacall.html#call_cleanup/2">call_cleanup/2</A> 
applies.
</DD>
</DL>

<P></BODY></HTML>
swi-prolog-nox 5.10.4-3ubuntu1 / usr / lib / swi-prolog / doc / Manual / metacall.html
