/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 7.1.10 Reference Manual: Section 4.9</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, 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="control.html"><img src="prev.gif" alt="Previous"></a>
<a class="nav" href="exception.html"><img src="next.gif" alt="Next"></a>
</div>
<h2 id="sec:metacall"><a id="sec:4.9"><span class="sec-nr">4.9</span> <span class="sec-title">Meta-Call 
Predicates</span></a></h2>

<a id="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 id="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 id="idx:call1:587"></a><a class="pred" href="metacall.html#call/1">call/1</a>.</dd>
<dt class="pubdef"><span class="pred-tag">[ISO]</span><a id="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. The predicates
<a id="idx:call28:588"></a><span class="pred-ext">call/[2-8]</span> are 
defined as real (meta-)predicates and are available to inspection 
through <a id="idx:currentpredicate1:589"></a><a class="pred" href="examineprog.html#current_predicate/1">current_predicate/1</a>, <a id="idx:predicateproperty2:590"></a><a class="pred" href="examineprog.html#predicate_property/2">predicate_property/2</a>, 
etc.<sup class="fn">48<span class="fn-text">Arities 2..8 are demanded by 
ISO/IEC 13211-1:1995/Cor.2:2012.</span></sup> Higher arities are handled 
by the compiler and runtime system, but the predicates are not 
accessible for inspection.<sup class="fn">49<span class="fn-text">Future 
versions of the reflective predicate may fake the presence of call/9.. . 
Full logical behaviour, generating all these pseudo predicates, is 
probably undesirable and will become impossible if <em>max_arity</em> is 
removed.</span></sup></dd>
<dt class="pubdef"><a id="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> 
calls
<code>plus(1, 2, X)</code>. New code should use call/[2..] if the length 
of
<var>List</var> is fixed.</dd>
<dt class="pubdef"><a id="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 id="once/1"><strong>once</strong>(<var>:Goal</var>)</a></dt>
<dd class="defbody">
Defined as:

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

<p><a id="idx:once1:591"></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 id="ignore/1"><strong>ignore</strong>(<var>:Goal</var>)</a></dt>
<dd class="defbody">
Calls <var>Goal</var> as <a id="idx:once1:592"></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 id="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 id="idx:callwithdepthlimit3:593"></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 id="idx:true0:594"></a><a class="pred" href="control.html#true/0">true/0</a> 
is translated into an inline virtual machine instruction. Also,
<a id="idx:repeat0:595"></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 id="idx:callwithdepthlimit3:596"></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 id="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 id="idx:callwithtimelimit2:597"></a><span class="pred-ext">call_with_time_limit/2</span> 
(package clib) or <a id="idx:threadsignal2:598"></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 id="idx:once1:599"></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 id="idx:member2:600"></a><a class="pred" href="lists.html#member/2">member/2</a>. 
Without <a id="idx:setupcallcleanup3:601"></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 <a id="idx:repeat0:602"></a><a class="pred" href="control.html#repeat/0">repeat/0</a> 
is removed by a cut or an exception.

<p><a id="idx:setupcallcleanup3:603"></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 id="idx:deterministic1:604"></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 id="idx:callcleanup2:605"></a><a class="pred" href="metacall.html#call_cleanup/2">call_cleanup/2</a>.</dd>
<dt class="pubdef"><a id="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 for 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 id="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 id="idx:callcleanup2:606"></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 id="idx:setupcallcleanup3:607"></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 id="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 id="idx:callcleanup2:608"></a><a class="pred" href="metacall.html#call_cleanup/2">call_cleanup/2</a> 
applies.
</dd>
</dl>

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