<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <title>SWI-Prolog 9.1.15 Reference Manual: Section B.1</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="hack.html"> <link rel="next" href="ancestral-cut.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="hack.html"><img src="prev.gif" alt="Previous"></a> <a class="nav" href="ancestral-cut.html"><img src="next.gif" alt="Next"></a> </div> <h2 id="sec:manipstack"><a id="sec:B.1"><span class="sec-nr">B.1</span> <span class="sec-title">Examining the Environment Stack</span></a></h2> <a id="sec:manipstack"></a> <dl class="latex"> <dt class="pubdef"><span class="pred-tag">[det]</span><a id="prolog_current_frame/1"><strong>prolog_current_frame</strong>(<var>-Frame</var>)</a></dt> <dd class="defbody"> Unify <var>Frame</var> with an integer providing a reference to the parent of the current local stack frame. A pointer to the current local frame cannot be provided as the predicate succeeds deterministically and therefore its frame is destroyed immediately after succeeding.</dd> <dt class="pubdef"><span class="pred-tag">[semidet]</span><a id="prolog_current_choice/1"><strong>prolog_current_choice</strong>(<var>-Choice</var>)</a></dt> <dd class="defbody"> Unify <var>Choice</var> with an integer provided a reference to the last choice point. Fails if the current environment has no choice points. See also <a id="idx:prologchoiceattribute3:2731"></a><a class="pred" href="manipstack.html#prolog_choice_attribute/3">prolog_choice_attribute/3</a>.</dd> <dt class="pubdef"><a id="prolog_frame_attribute/3"><strong>prolog_frame_attribute</strong>(<var>+Frame, +Key, :Value</var>)</a></dt> <dd class="defbody"> Obtain information about the local stack frame <var>Frame</var>. <var>Frame</var> is a frame reference as obtained through <a id="idx:prologcurrentframe1:2732"></a><a class="pred" href="manipstack.html#prolog_current_frame/1">prolog_current_frame/1</a>, <a id="idx:prologtraceinterception4:2733"></a><a class="pred" href="tracehook.html#prolog_trace_interception/4">prolog_trace_interception/4</a> or this predicate. The key values are described below. <dl class="latex"> <dt><strong>alternative</strong></dt> <dd class="defbody"> <var>Value</var> is unified with an integer reference to the local stack frame in which execution is resumed if the goal associated with <var>Frame</var> fails. Fails if the frame has no alternative frame.</dd> <dt><strong>has_alternatives</strong></dt> <dd class="defbody"> <var>Value</var> is unified with <code>true</code> if <var>Frame</var> still is a candidate for backtracking; <code>false</code> otherwise.</dd> <dt><strong>goal</strong></dt> <dd class="defbody"> <var>Value</var> is unified with the goal associated with <var>Frame</var>. If the definition module of the active predicate is not the calling context, the goal is represented as <code><<var>module</var>>:<<var>goal</var>></code>. Do not instantiate variables in this goal unless you <b>know</b> what you are doing! Note that the returned term may contain references to the frame and should be discarded before the frame terminates.<sup class="fn">243<span class="fn-text">The returned term is actually an illegal Prolog term that may hold references from the global to the local stack to preserve the variable names.</span></sup></dd> <dt><strong>parent_goal</strong></dt> <dt><strong>parent_goal</strong>(<var>-Parent</var>)</dt> <dd class="defbody"> If <var>Value</var> is instantiated to a callable term, find a frame executing the predicate described by <var>Value</var> and unify the arguments of <var>Value</var> to the goal arguments associated with the frame. This is intended to check the current execution context. The user must ensure the checked parent goal is not removed from the stack due to last-call optimisation and be aware of the slow operation on deeply nested calls. <p>The variant <code>parent_goal(-Parent)</code> unifies the frame reference of the parent of the found frame with <var>Parent</var>. That allows for finding frames higher up in the stack running the same goal.</dd> <dt><strong>predicate_indicator</strong></dt> <dd class="defbody"> Similar to <code>goal</code>, but only returning the [<<var>module</var>>:]<<var>name</var>>/<<var>arity</var>> term describing the term, not the actual arguments. It avoids creating an illegal term as <code>goal</code> and is used by the library <code>library(prolog_stack)</code>.</dd> <dt><strong>clause</strong></dt> <dd class="defbody"> <var>Value</var> is unified with a reference to the currently running clause. Fails if the current goal is associated with a foreign (C) defined predicate. See also <a id="idx:nthclause3:2734"></a><a class="pred" href="examineprog.html#nth_clause/3">nth_clause/3</a> and <a id="idx:clauseproperty2:2735"></a><a class="pred" href="examineprog.html#clause_property/2">clause_property/2</a>.</dd> <dt><strong>level</strong></dt> <dd class="defbody"> <var>Value</var> is unified with the recursion level of <var>Frame</var>. The top level frame is at level‘0'.</dd> <dt><strong>parent</strong></dt> <dd class="defbody"> <var>Value</var> is unified with an integer reference to the parent local stack frame of <var>Frame</var>. Fails if <var>Frame</var> is the top frame.</dd> <dt><strong>context_module</strong></dt> <dd class="defbody"> <var>Value</var> is unified with the name of the context module of the environment.</dd> <dt><strong>top</strong></dt> <dd class="defbody"> <var>Value</var> is unified with <code>true</code> if <var>Frame</var> is the top Prolog goal from a recursive call back from the foreign language; <code>false</code> otherwise.</dd> <dt><strong>hidden</strong></dt> <dd class="defbody"> <var>Value</var> is unified with <code>true</code> if the frame is hidden from the user, either because a parent has the hide-childs attribute (all system predicates), or the system has no trace-me attribute.</dd> <dt><strong>skipped</strong></dt> <dd class="defbody"> <var>Value</var> is <code>true</code> if this frame was skipped in the debugger.</dd> <dt><strong>pc</strong></dt> <dd class="defbody"> <var>Value</var> is unified with the program pointer saved on behalf of the parent goal if the parent goal is not owned by a foreign predicate or belongs to a compound meta-call (e.g., call((a,b))).</dd> <dt><strong>argument</strong>(<var>N</var>)</dt> <dd class="defbody"> <var>Value</var> is unified with the <var>N</var>-th slot of the frame. Argument 1 is the first argument of the goal. Arguments above the arity refer to local variables. Fails silently if <var>N</var> is out of range. </dd> </dl> </dd> <dt class="pubdef"><a id="prolog_choice_attribute/3"><strong>prolog_choice_attribute</strong>(<var>+ChoicePoint, +Key, -Value</var>)</a></dt> <dd class="defbody"> Extract attributes of a choice point. <var>ChoicePoint</var> is a reference to a choice point as passed to <a id="idx:prologtraceinterception4:2736"></a><a class="pred" href="tracehook.html#prolog_trace_interception/4">prolog_trace_interception/4</a> on the 3rd argument or obtained using <a id="idx:prologcurrentchoice1:2737"></a><a class="pred" href="manipstack.html#prolog_current_choice/1">prolog_current_choice/1</a>. <var>Key</var> specifies the requested information: <dl class="latex"> <dt><strong>parent</strong></dt> <dd class="defbody"> Requests a reference to the first older choice point. </dd> <dt><strong>frame</strong></dt> <dd class="defbody"> Requests a reference to the frame to which the choice point refers. </dd> <dt><strong>type</strong></dt> <dd class="defbody"> Requests the type. Defined values are <code>clause</code> (the goal has alternative clauses), <code>foreign</code> (non-deterministic foreign predicate), <code>jump</code> (clause internal choice point), <code>top</code> (first dummy choice point), <code>catch</code> (<a id="idx:catch3:2738"></a><a class="pred" href="exception.html#catch/3">catch/3</a> to allow for undo), <code>debug</code> (help the debugger), or <code>none</code> (has been deleted). </dd> <dt><strong>pc</strong></dt> <dd class="defbody"> Requests the program counter to which the choice point refers. Only applicable for in-clause choice points. </dd> <dt><strong>clause</strong></dt> <dd class="defbody"> Request the clause that will be tried if this choice point is activated. Only applicable for choice points of type <code>clause</code>. </dd> </dl> <p>This predicate is used for the graphical debugger to show the choice point stack.</dd> <dt class="pubdef"><a id="deterministic/1"><strong>deterministic</strong>(<var>-Boolean</var>)</a></dt> <dd class="defbody"> Unifies its argument with <code>true</code> if no choice point exists that is more recent than the entry of the clause in which it appears. There are few realistic situations for using this predicate. It is used by the <a id="idx:prolog0:2739"></a><a class="pred" href="toplevel.html#prolog/0">prolog/0</a> top level to check whether Prolog should prompt the user for alternatives. Similar results can be achieved in a more portable fashion using <a id="idx:callcleanup2:2740"></a><a class="pred" href="metacall.html#call_cleanup/2">call_cleanup/2</a>. </dd> </dl> <p></body></html>