/usr/lib/swi-prolog/doc/Manual/prologxref.html

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

<HTML>
<HEAD>
<TITLE>SWI-Prolog 5.10.2 Reference Manual: Section A.19</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="pio.html">
<LINK REL=next HREF="readutil.html">
<STYLE type="text/css">
/* Style sheet for SWI-Prolog latex2html
*/

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

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

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

<H2><A NAME="sec:A.19"><SPAN class="sec-nr">A.19</SPAN> <SPAN class="sec-title">library( 
prologxref ): Cross-reference data collection library</SPAN></A></H2>

<A NAME="prologxref"></A>
<A NAME="sec:lib:prologxref"></A>

<P>This library collects information on defined and used objects in 
Prolog sourcefiles. Typically these are predicates, but we expect the 
library to deal with other types of objects in the future. The library 
is a building block for tools doing dependency tracking in applications. 
Dependency tracking is useful to reveal the structure of an unknown 
program or detect missing components at compile-time, but also for 
program transformation or minimising a program saved-state by only 
saving the reachable objects.

<P>This section gives a partial description of the library API, 
providing some insight in how you can use it for analysing your program. 
The library should be further modularized, moving its knowledge about 
-for example- XPCE into a different file and allowing for adding 
knowledge about other libraries such as Logtalk. <B>Please do not 
consider this interface rock-solid.</B>

<P>The library is exploited by two graphical tools in the SWI-Prolog 
environment. The XPCE frontend started by <A NAME="idx:gxref0:1588"></A><A class="pred" href="xref.html#gxref/0">gxref/0</A> 
and described in
<A class="sec" href="xref.html">section 3.7</A> and PceEmacs (<A class="sec" href="pceemacs.html">section 
3.4</A>) which exploits this library for its syntax colouring.

<P>For all predicates described below, <VAR>Source</VAR> is the source 
that is processed. This is normally a filename in any notation 
acceptable to the file loading predicates (see <A NAME="idx:loadfiles2:1589"></A><A class="pred" href="consulting.html#load_files/2">load_files/2</A>). 
Using the hooks defined in <A class="sec" href="prologxref.html">section 
A.19.1</A> it can be anything else that can be translated into a Prolog 
stream holding Prolog source text. <VAR>Callable</VAR> is a callable 
term (see <A NAME="idx:callable1:1590"></A><A class="pred" href="typetest.html#callable/1">callable/1</A>). 
Callables do not carry a module qualifier unless the referred predicate 
is not in the module defined
<VAR>Source</VAR>.

<DL>
<DT class="pubdef"><A NAME="xref_source/1"><STRONG>xref_source</STRONG>(<VAR>+Source</VAR>)</A></DT>
<DD class="defbody">
Gather information on <VAR>Source</VAR>. If <VAR>Source</VAR> has 
already been processed and is still up-to-date according to the file 
timestamp, no action is taken. This predicate must be called on a file 
before information can be gathered.</DD>
<DT class="pubdef"><A NAME="xref_current_source/1"><STRONG>xref_current_source</STRONG>(<VAR>?Source</VAR>)</A></DT>
<DD class="defbody">
<VAR>Source</VAR> has been processed.</DD>
<DT class="pubdef"><A NAME="xref_clean/1"><STRONG>xref_clean</STRONG>(<VAR>+Source</VAR>)</A></DT>
<DD class="defbody">
Remove the information gathered for <VAR>Source</VAR></DD>
<DT class="pubdef"><A NAME="xref_defined/3"><STRONG>xref_defined</STRONG>(<VAR>?Source, 
?Callable, -How</VAR>)</A></DT>
<DD class="defbody">
<VAR>Callable</VAR> is defined in <VAR>Source</VAR>. <VAR>How</VAR> is 
one of
<CENTER>
<TABLE BORDER=0 FRAME=void RULES=groups>
<TR VALIGN=top><TD><CODE>dynamic(Line)</CODE> </TD><TD>Declared dynamic 
at <VAR>Line</VAR> </TD></TR>
<TR VALIGN=top><TD><CODE>thread_local(Line)</CODE> </TD><TD>Declared 
thread local at <VAR>Line</VAR> </TD></TR>
<TR VALIGN=top><TD><CODE>multifile(Line)</CODE> </TD><TD>Declared 
multifile at <VAR>Line</VAR> </TD></TR>
<TR VALIGN=top><TD><CODE>local(Line)</CODE> </TD><TD>First clause at <VAR>Line</VAR> </TD></TR>
<TR VALIGN=top><TD><CODE>foreign(Line)</CODE> </TD><TD>Foreign library 
loaded at <VAR>Line</VAR> </TD></TR>
<TR VALIGN=top><TD><CODE>constraint(Line)</CODE> </TD><TD>CHR Constraint 
at <VAR>Line</VAR> </TD></TR>
<TR VALIGN=top><TD><CODE>imported(File)</CODE> </TD><TD>Imported from <VAR>File</VAR> </TD></TR>
</TABLE>

</CENTER>
</DD>
<DT class="pubdef"><A NAME="xref_called/3"><STRONG>xref_called</STRONG>(<VAR>?Source, 
?Callable, ?By</VAR>)</A></DT>
<DD class="defbody">
<VAR>Callable</VAR> is called in <VAR>Source</VAR> by <VAR>By</VAR>.</DD>
<DT class="pubdef"><A NAME="xref_exported/2"><STRONG>xref_exported</STRONG>(<VAR>?Source, 
?Callable</VAR>)</A></DT>
<DD class="defbody">
<VAR>Callable</VAR> is public (exported from the module).</DD>
<DT class="pubdef"><A NAME="xref_module/2"><STRONG>xref_module</STRONG>(<VAR>?Source, 
?Module</VAR>)</A></DT>
<DD class="defbody">
<VAR>Source</VAR> is a module-file defining the given module.</DD>
<DT class="pubdef"><A NAME="xref_built_in/1"><STRONG>xref_built_in</STRONG>(<VAR>?Callable</VAR>)</A></DT>
<DD class="defbody">
True if <VAR>Callable</VAR> is a built-in predicate. Currently this is 
assumed for all predicates defined in the <CODE>system</CODE> module and 
having the property <CODE>built_in</CODE>. Built-in predicates are not 
registered as `called'.
</DD>
</DL>

<H3><A NAME="sec:A.19.1"><SPAN class="sec-nr">A.19.1</SPAN> <SPAN class="sec-title">Extending 
the library</SPAN></A></H3>

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

<P>The library provides hooks for extending its rules it uses for 
finding predicates called by some programming construct.

<DL>
<DT class="pubdef"><A NAME="prolog:called_by/2"><STRONG>prolog:called_by</STRONG>(<VAR>+Goal, 
-Called</VAR>)</A></DT>
<DD class="defbody">
Where <VAR>Goal</VAR> is a non-var subgoal appearing in called object 
(typically a clause-body). If it succeeds it must return a list of goals 
called by <VAR>Goal</VAR>. As a special construct, if a term <VAR>Callable+N</VAR> 
is returned, <VAR>N</VAR> variable arguments are added to <VAR>Callable</VAR> 
before further processing. For simple meta-calls a single fact suffices. 
Complex rules as used in the <CODE>library(html_write)</CODE> library 
provided by the HTTP package examine the arguments and create a list of 
called objects.

<P>The current system cannot deal with the same name/arity in different 
modules that behave differently with respect to called arguments.
</DD>
</DL>

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