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

<H2><A NAME="sec:4.14"><SPAN class="sec-nr">4.14</SPAN> <SPAN class="sec-title">Examining 
the program</SPAN></A></H2>

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

<DL class="latex">
<DT class="pubdef"><A NAME="current_atom/1"><STRONG>current_atom</STRONG>(<VAR>-Atom</VAR>)</A></DT>
<DD class="defbody">
Successively unifies <VAR>Atom</VAR> with all atoms known to the system. 
Note that <A NAME="idx:currentatom1:679"></A><A class="pred" href="examineprog.html#current_atom/1">current_atom/1</A> 
always succeeds if <VAR>Atom</VAR> is instantiated to an atom.</DD>
<DT class="pubdef"><A NAME="current_blob/2"><STRONG>current_blob</STRONG>(<VAR>?Blob, 
?Type</VAR>)</A></DT>
<DD class="defbody">
Examine the type or enumerate blobs of the given <VAR>Type</VAR>. Typed 
blobs are supported through the foreign language interface for storing 
arbitrary BLOBS (Binary Large Object) or handles to external entities. 
See <A class="sec" href="foreigninclude.html">section 9.4.7</A> for 
details.</DD>
<DT class="pubdef"><A NAME="current_functor/2"><STRONG>current_functor</STRONG>(<VAR>?Name, 
?Arity</VAR>)</A></DT>
<DD class="defbody">
Successively unifies <VAR>Name</VAR> with the name and <VAR>Arity</VAR> 
with the arity of functors known to the system.</DD>
<DT class="pubdef"><A NAME="current_flag/1"><STRONG>current_flag</STRONG>(<VAR>-FlagKey</VAR>)</A></DT>
<DD class="defbody">
Successively unifies <VAR>FlagKey</VAR> with all keys used for flags 
(see
<A NAME="idx:flag3:680"></A><A class="pred" href="db.html#flag/3">flag/3</A>).</DD>
<DT class="pubdef"><A NAME="current_key/1"><STRONG>current_key</STRONG>(<VAR>-Key</VAR>)</A></DT>
<DD class="defbody">
Successively unifies <VAR>Key</VAR> with all keys used for records (see
<A NAME="idx:recorda3:681"></A><A class="pred" href="db.html#recorda/3">recorda/3</A>, 
etc.).</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="current_predicate/1"><STRONG>current_predicate</STRONG>(<VAR>:PredicateIndicator</VAR>)</A></DT>
<DD class="defbody">
True if <VAR>PredicateIndicator</VAR> is a currently defined predicate. 
A predicate is considered defined if it exists in the specified module, 
is imported into the module or is defined in one of the modules from 
which the predicate will be imported if it is called (see
<A class="sec" href="importmodule.html">section 5.9</A>). Note that <A NAME="idx:currentpredicate1:682"></A><A class="pred" href="examineprog.html#current_predicate/1">current_predicate/1</A> 
does <EM>not</EM> succeed for predicates that can be <EM>autoloaded</EM>. 
See also
<A NAME="idx:currentpredicate2:683"></A><A class="pred" href="examineprog.html#current_predicate/2">current_predicate/2</A> 
and <A NAME="idx:predicateproperty2:684"></A><A class="pred" href="examineprog.html#predicate_property/2">predicate_property/2</A>.

<P>If <VAR>PredicateIndicator</VAR> is not fully specified, the 
predicate only generates values that are defined in or already imported 
into the target module. Generating all callable predicates therefore 
requires enumerating modules using <A NAME="idx:currentmodule1:685"></A><A class="pred" href="manipmodule.html#current_module/1">current_module/1</A>. 
Generating predicates callable in a given module requires enumerating 
the import modules using <A NAME="idx:importmodule2:686"></A><A class="pred" href="importmodule.html#import_module/2">import_module/2</A> 
and the auto-loadable predicates using the
<A NAME="idx:predicateproperty2:687"></A><A class="pred" href="examineprog.html#predicate_property/2">predicate_property/2</A> <CODE>autoload</CODE>.</DD>
<DT class="pubdef"><A NAME="current_predicate/2"><STRONG>current_predicate</STRONG>(<VAR>?Name, 
:Head</VAR>)</A></DT>
<DD class="defbody">
Classical pre-ISO implementation of <A NAME="idx:currentpredicate1:688"></A><A class="pred" href="examineprog.html#current_predicate/1">current_predicate/1</A>, 
where the predicate is represented by the head-term. The advantage is 
that this can be used for checking existence of a predicate before 
calling it without the need for <A NAME="idx:functor3:689"></A><A class="pred" href="manipterm.html#functor/3">functor/3</A>:

<PRE class="code">
call_if_exists(G) :-
        current_predicate(_, G),
        call(G).
</PRE>

<P>Because of this intended usage, <A NAME="idx:currentpredicate2:690"></A><A class="pred" href="examineprog.html#current_predicate/2">current_predicate/2</A> 
also succeeds if the predicate can be autoloaded. Unfortunately, 
checking the autoloader makes this predicate relatively slow; in 
particular because a failed lookup of the autoloader will cause the 
autoloader to verify that its index is up-to-date.</DD>
<DT class="pubdef"><A NAME="predicate_property/2"><STRONG>predicate_property</STRONG>(<VAR>:Head, 
?Property</VAR>)</A></DT>
<DD class="defbody">
True if <VAR>Head</VAR> refers to a predicate that has property
<VAR>Property</VAR>. With sufficiently instantiated <VAR>Head</VAR>,
<A NAME="idx:predicateproperty2:691"></A><A class="pred" href="examineprog.html#predicate_property/2">predicate_property/2</A> 
tries to resolve the predicate the same way as calling it would do: if 
the predicate is not defined it scans the auto-import modules and 
finally tries the autoloader. Unlike calling, failure to find the target 
predicate causes <A NAME="idx:predicateproperty2:692"></A><A class="pred" href="examineprog.html#predicate_property/2">predicate_property/2</A> 
to fail silently. If <VAR>Head</VAR> is not sufficiently bound, only 
currently locally defined and already imported predicates are 
enumerated. See
<A NAME="idx:currentpredicate1:693"></A><A class="pred" href="examineprog.html#current_predicate/1">current_predicate/1</A> 
for enumerating all predicates. A common issue concerns <EM>generating</EM> 
all built-in predicates. This can be achieved using the code below.

<PRE class="code">
generate_built_in(Name/Arity) :-
        predicate_property(system:Head, built_in),
        functor(Head, Name, Arity),
        \+ sub_atom(Name, 0, _, _, $).  % discard reserved names
</PRE>

<P><VAR>Property</VAR> is one of:

<DL class="latex">
<DT><STRONG>autoload</STRONG>(<VAR>File</VAR>)</DT>
<DD class="defbody">
Is true if the predicate can be autoloaded from the file <VAR>File</VAR>. 
Like <CODE>undefined</CODE>, this property is <EM>not</EM> generated.</DD>
<DT><STRONG>built_in</STRONG></DT>
<DD class="defbody">
Is true if the predicate is locked as a built-in predicate. This implies 
it cannot be redefined in its definition module and it can normally not 
be seen in the tracer.</DD>
<DT><STRONG>dynamic</STRONG></DT>
<DD class="defbody">
Is true if <A NAME="idx:assert1:694"></A><A class="pred" href="db.html#assert/1">assert/1</A> 
and <A NAME="idx:retract1:695"></A><A class="pred" href="db.html#retract/1">retract/1</A> 
may be used to modify the predicate. This property is set using <A NAME="idx:dynamic1:696"></A><A class="pred" href="dynamic.html#dynamic/1">dynamic/1</A>.</DD>
<DT><STRONG>exported</STRONG></DT>
<DD class="defbody">
Is true if the predicate is in the public list of the context module.
</DD>
<DT><STRONG>imported_from</STRONG>(<VAR>Module</VAR>)</DT>
<DD class="defbody">
Is true if the predicate is imported into the context module from module <VAR>Module</VAR>.</DD>
<DT><STRONG>file</STRONG>(<VAR>FileName</VAR>)</DT>
<DD class="defbody">
Unify <VAR>FileName</VAR> with the name of the source file in which the 
predicate is defined. See also <A NAME="idx:sourcefile2:697"></A><A class="pred" href="consulting.html#source_file/2">source_file/2</A>.</DD>
<DT><STRONG>foreign</STRONG></DT>
<DD class="defbody">
Is true if the predicate is defined in the C language.</DD>
<DT><STRONG>indexed</STRONG>(<VAR>Head</VAR>)</DT>
<DD class="defbody">
Predicate is indexed (see <A NAME="idx:index1:698"></A><A class="pred" href="dynamic.html#index/1">index/1</A>) 
according to <VAR>Head</VAR>. <VAR>Head</VAR> is a term whose name and 
arity are identical to the predicate. The arguments are unified with `1' 
for indexed arguments, `0' otherwise.</DD>
<DT><STRONG>interpreted</STRONG></DT>
<DD class="defbody">
Is true if the predicate is defined in Prolog. We return true on this 
because, although the code is actually compiled, it is completely 
transparent, just like interpreted code.</DD>
<DT><STRONG>iso</STRONG></DT>
<DD class="defbody">
Is true if the predicate is covered by the ISO standard (ISO/IEC 
13211-1).</DD>
<DT><STRONG>line_count</STRONG>(<VAR>LineNumber</VAR>)</DT>
<DD class="defbody">
Unify <VAR>LineNumber</VAR> with the line number of the first clause of 
the predicate. Fails if the predicate is not associated with a file. See 
also <A NAME="idx:sourcefile2:699"></A><A class="pred" href="consulting.html#source_file/2">source_file/2</A>.</DD>
<DT><STRONG>multifile</STRONG></DT>
<DD class="defbody">
Is true there may be multiple (or no) file providing clauses for the 
predicate. This property is set using <A NAME="idx:multifile1:700"></A><A class="pred" href="dynamic.html#multifile/1">multifile/1</A>.</DD>
<DT><STRONG>meta_predicate</STRONG>(<VAR>Head</VAR>)</DT>
<DD class="defbody">
If the predicate is declared as a meta-predicate using <A NAME="idx:metapredicate1:701"></A><A class="pred" href="metapred.html#meta_predicate/1">meta_predicate/1</A>, 
Unify <VAR>Head</VAR> with the head-pattern. The head-pattern is a 
compound term with the same name and arity as the predicate where each 
argument of the term is a meta predicate specifier. See <A NAME="idx:metapredicate1:702"></A><A class="pred" href="metapred.html#meta_predicate/1">meta_predicate/1</A> 
for details.</DD>
<DT><STRONG>nodebug</STRONG></DT>
<DD class="defbody">
Details of the predicate are not shown by the debugger. This is the 
default for built-in predicates. User predicates can be compiled this 
way using the Prolog flag <A class="flag" href="flags.html#flag:generate_debug_info">generate_debug_info</A>.</DD>
<DT><STRONG>notrace</STRONG></DT>
<DD class="defbody">
Do not show ports of this predicate in the debugger.</DD>
<DT><STRONG>number_of_clauses</STRONG>(<VAR>ClauseCount</VAR>)</DT>
<DD class="defbody">
Unify <VAR>ClauseCount</VAR> to the number of clauses associated with 
the predicate. Fails for foreign predicates.</DD>
<DT><STRONG>public</STRONG></DT>
<DD class="defbody">
Predicate is declared public using <A NAME="idx:public1:703"></A><A class="pred" href="dynamic.html#public/1">public/1</A>. 
Note that without further definition, public predicates are considered 
undefined and this property is <EM>not</EM> reported.</DD>
<DT><STRONG>thread_local</STRONG></DT>
<DD class="defbody">
If true (only possible on the multi-threaded version) each thread has 
its own clauses for the predicate. This property is set using
<A NAME="idx:threadlocal1:704"></A><A class="pred" href="threadcom.html#thread_local/1">thread_local/1</A>.</DD>
<DT><STRONG>transparent</STRONG></DT>
<DD class="defbody">
Is true if the predicate is declared transparent using the
<A NAME="idx:moduletransparent1:705"></A><A class="pred" href="ctxmodule.html#module_transparent/1">module_transparent/1</A> 
or <A NAME="idx:metapredicate1:706"></A><A class="pred" href="metapred.html#meta_predicate/1">meta_predicate/1</A> 
declaration. In the latter case the property <CODE>meta</CODE> is also 
provided. See
<A class="sec" href="modules.html">chapter 5</A> for details.</DD>
<DT><STRONG>undefined</STRONG></DT>
<DD class="defbody">
Is true if a procedure definition block for the predicate exists, but 
there are no clauses for it and it is not declared dynamic or multifile. 
This is true if the predicate occurs in the body of a loaded predicate, 
an attempt to call it has been made via one of the meta-call predicates 
or the predicate had a definition in the past. See the library package
<CODE>library(check)</CODE> for example usage.</DD>
<DT><STRONG>volatile</STRONG></DT>
<DD class="defbody">
If true, the clauses are not saved into a saved-state by <A NAME="idx:qsaveprogram12:707"></A><A class="pred" href="runtime.html#qsave_program/1">qsave_program/[1,2]</A>. 
This property is set using <A NAME="idx:volatile1:708"></A><A class="pred" href="runtime.html#volatile/1">volatile/1</A>.
</DD>
</DL>

</DD>
<DT class="pubdef"><A NAME="dwim_predicate/2"><STRONG>dwim_predicate</STRONG>(<VAR>+Term, 
-Dwim</VAR>)</A></DT>
<DD class="defbody">
`Do What I Mean' (`dwim') support predicate. <VAR>Term</VAR> is a term, 
which name and arity are used as a predicate specification. <VAR>Dwim</VAR> 
is instantiated with the most general term built from <VAR>Name</VAR> 
and the arity of a defined predicate that matches the predicate 
specified by
<VAR>Term</VAR> in the `Do What I Mean' sense. See <A NAME="idx:dwimmatch2:709"></A><A class="pred" href="miscpreds.html#dwim_match/2">dwim_match/2</A> 
for `Do What I Mean' string matching. Internal system predicates are not 
generated, unless <CODE>style_check(+dollar)</CODE> is active. 
Backtracking provides all alternative matches.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="clause/2"><STRONG>clause</STRONG>(<VAR>:Head, 
?Body</VAR>)</A></DT>
<DD class="defbody">
True if <VAR>Head</VAR> can be unified with a clause head and <VAR>Body</VAR> 
with the corresponding clause body. Gives alternative clauses on 
backtracking. For facts <VAR>Body</VAR> is unified with the atom <VAR>true</VAR>.</DD>
<DT class="pubdef"><A NAME="clause/3"><STRONG>clause</STRONG>(<VAR>:Head, 
?Body, ?Reference</VAR>)</A></DT>
<DD class="defbody">
Equivalent to <A NAME="idx:clause2:710"></A><A class="pred" href="examineprog.html#clause/2">clause/2</A>, 
but unifies <VAR>Reference</VAR> with a unique reference to the clause 
(see also <A NAME="idx:assert2:711"></A><A class="pred" href="db.html#assert/2">assert/2</A>, <A NAME="idx:erase1:712"></A><A class="pred" href="db.html#erase/1">erase/1</A>). 
If <VAR>Reference</VAR> is instantiated to a reference the clause's head 
and body will be unified with <VAR>Head</VAR> and <VAR>Body</VAR>.</DD>
<DT class="pubdef"><A NAME="nth_clause/3"><STRONG>nth_clause</STRONG>(<VAR>?Pred, 
?Index, ?Reference</VAR>)</A></DT>
<DD class="defbody">
Provides access to the clauses of a predicate using their index number. 
Counting starts at 1. If <VAR>Reference</VAR> is specified it unifies <VAR>Pred</VAR> 
with the most general term with the same name/arity as the predicate and
<VAR>Index</VAR> with the index-number of the clause. Otherwise the name 
and arity of <VAR>Pred</VAR> are used to determine the predicate. If <VAR>Index</VAR> 
is provided <VAR>Reference</VAR> will be unified with the clause 
reference. If <VAR>Index</VAR> is unbound, backtracking will yield both 
the indices and the references of all clauses of the predicate. The 
following example finds the 2nd clause of <A NAME="idx:member2:713"></A><A class="pred" href="lists.html#member/2">member/2</A>:

<PRE class="code">
?- nth_clause(member(_,_), 2, Ref), clause(Head, Body, Ref).

Ref = 160088
Head = system : member(G575, [G578|G579])
Body = member(G575, G579)
</PRE>

</DD>
<DT class="pubdef"><A NAME="clause_property/2"><STRONG>clause_property</STRONG>(<VAR>+ClauseRef, 
-Property</VAR>)</A></DT>
<DD class="defbody">
Queries properties of a clause. <VAR>ClauseRef</VAR> is a reference to a 
clause as produced by <A NAME="idx:clause3:714"></A><A class="pred" href="examineprog.html#clause/3">clause/3</A>, <A NAME="idx:nthclause3:715"></A><A class="pred" href="examineprog.html#nth_clause/3">nth_clause/3</A> 
or <A NAME="idx:prologframeattribute3:716"></A><A class="pred" href="manipstack.html#prolog_frame_attribute/3">prolog_frame_attribute/3</A>.
<VAR>Property</VAR> is one of the following:

<DL class="latex">
<DT><STRONG>file</STRONG>(<VAR>FileName</VAR>)</DT>
<DD class="defbody">
Unify <VAR>FileName</VAR> with the name of the source file in which the 
clause is defined. Fails if the clause is not associated to a file.
</DD>
<DT><STRONG>line_count</STRONG>(<VAR>LineNumber</VAR>)</DT>
<DD class="defbody">
Unify <VAR>LineNumber</VAR> with the line number of the clause. Fails if 
the clause is not associated to a file.
</DD>
<DT><STRONG>fact</STRONG></DT>
<DD class="defbody">
True if the clause has no body.
</DD>
<DT><STRONG>erased</STRONG></DT>
<DD class="defbody">
True if the clause has been erased, but not yet reclaimed because it is 
referenced.
</DD>
</DL>

</DD>
</DL>

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