/usr/share/doc/swi-prolog-doc/Manual/manipstack.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<HTML>
<HEAD>
<TITLE>SWI-Prolog 5.6.59 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=previous HREF="hack.html">
<LINK REL=next HREF="tracehook.html">
<STYLE type="text/css">
/* Style sheet for SWI-Prolog latex2html
*/

dd.defbody
{ margin-bottom: 1em;
}

dt.pubdef
{ background-color: #c5e1ff;
}

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;
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="hack.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="tracehook.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>

<H2><A NAME="sec:B.1"><SPAN class="sec-nr">B.1</SPAN> <SPAN class="sec-title">Examining 
the Environment Stack</SPAN></A></H2>

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

<DL>
<DT class="pubdef"><A NAME="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"><A NAME="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 NAME="idx:prologcurrentframe1:1537"></A><A class="pred" href="manipstack.html#prolog_current_frame/1">prolog_current_frame/1</A>,
<A NAME="idx:prologtraceinterception4:1538"></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>
<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 <CODE>user</CODE> 
the goal is represented as <TT>&lt;<VAR>module</VAR>&gt;:&lt;<VAR>goal</VAR>&gt;</TT>. 
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">88<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>
<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.</DD>
<DT><STRONG>predicate_indicator</STRONG></DT>
<DD class="defbody">
Similar to <CODE>goal</CODE>, but only returning the [&lt;<VAR>module</VAR>&gt;:]&lt;<VAR>name</VAR>&gt;/&lt;<VAR>arity</VAR>&gt; 
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 NAME="idx:nthclause3:1539"></A><A class="pred" href="examineprog.html#nth_clause/3">nth_clause/3</A> 
and <A NAME="idx:clauseproperty2:1540"></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>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.</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 NAME="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 NAME="idx:prologtraceinterception4:1541"></A><A class="pred" href="tracehook.html#prolog_trace_interception/4">prolog_trace_interception/4</A> 
on the 3-th argument. <VAR>Key</VAR> specifies the requested 
information:

<DL>
<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 NAME="idx:catch3:1542"></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>
</DL>

<P>This predicate is used for the graphical debugger to show the 
choice-point stack.</DD>
<DT class="pubdef"><A NAME="deterministic/1"><STRONG>deterministic</STRONG>(<VAR>-Boolean</VAR>)</A></DT>
<DD class="defbody">
Unifies its argument with <CODE>true</CODE> if no choicepoint exists 
that is more recent than the entry of the clause in which is appears. 
There are few realistic situations for using this predicate. It is used 
by the
<A NAME="idx:prolog0:1543"></A><A class="pred" href="toplevel.html#prolog/0">prolog/0</A> 
toplevel to check whether Prolog should prompt the user for 
alternatives. Similar results can be achieved in a more portable fashion 
using <A NAME="idx:callcleanup2:1544"></A><A class="pred" href="metacall.html#call_cleanup/2">call_cleanup/2</A>.
</DD>
</DL>

<P></BODY></HTML>
swi-prolog-doc 5.6.59-1 / usr / share / doc / swi-prolog-doc / Manual / manipstack.html
