/usr/lib/swi-prolog/doc/Manual/xref.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 3.7</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="navigator.html">
<link rel="next" href="idepreds.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="navigator.html"><img src="prev.gif" alt="Previous"></a>
<a class="nav" href="idepreds.html"><img src="next.gif" alt="Next"></a>
</div>
<h2 id="sec:xref"><a id="sec:3.7"><span class="sec-nr">3.7</span> <span class="sec-title">Cross-referencer</span></a></h2>

<a id="sec:xref"></a>

<p>A cross-referencer is a tool that examines the caller-callee relation 
between predicates, and, using this information to explicate dependency 
relations between source files, finds calls to non-existing predicates 
and predicates for which no callers can be found. Cross-referencing is 
useful during program development, reorganisation, clean-up, porting and 
other program maintenance tasks. The dynamic nature of Prolog makes the 
task non-trivial. Goals can be created dynamically using <a id="idx:call1:290"></a><a class="pred" href="metacall.html#call/1">call/1</a> 
after construction of a goal term. Abstract interpretation can find some 
of these calls, but they can also come from external communication, 
making it impossible to predict the callee. In other words, the 
cross-referencer has only partial understanding of the program, and its 
results are necessarily incomplete. Still, it provides valuable 
information to the developer.

<p>SWI-Prolog's cross-referencer is split into two parts. The standard 
Prolog library <code>library(prolog_xref)</code> is an extensible 
library for information gathering described in <a class="sec" href="prolog_xref.html">section 
A.22</a>, and the XPCE library <code>library(pce_xref)</code> provides a 
graphical front-end for the cross-referencer described here. We 
demonstrate the tool on CHAT80, a natural language question and answer 
system by Fernando C.N. Pereira and David H.D. Warren.

<dl class="latex">
<dt class="pubdef"><a id="gxref/0"><strong>gxref</strong></a></dt>
<dd class="defbody">
Run cross-referencer on all currently loaded files and present a 
graphical overview of the result. As the predicate operates on the 
currently loaded application it must be run after loading the 
application.
</dd>
</dl>

<p><a id="fig:xrefchatfile"></a><div style="text-align:center"><img src="xrefchatfile.gif"></div>
<div class="caption"><b>Figure 3 : </b>File info for <code>chattop.pl</code>, 
part of CHAT80</div>

<p>The <b>left window</b> (see <a class="fig" href="xref.html#fig:xrefchatfile">figure 
3</a>) provides browsers for loaded files and predicates. To avoid long 
file paths, the file hierarchy has three main branches. The first is the 
current directory holding the sources. The second is marked <code>alias</code>, 
and below it are the file-search-path aliases (see <a id="idx:filesearchpath2:291"></a><a class="pred" href="consulting.html#file_search_path/2">file_search_path/2</a> 
and
<a id="idx:absolutefilename3:292"></a><a class="pred" href="files.html#absolute_file_name/3">absolute_file_name/3</a>). 
Here you find files loaded from the system as well as modules of the 
program loaded from other locations using the file search path. All 
loaded files that fall outside these categories are below the last 
branch called <code><code>/</code></code>. Files where the system found 
suspicious dependencies are marked with an exclamation mark. This also 
holds for directories holding such files. Clicking on a file opens a
<em>File info</em> window in the right pane.

<p>The <b>File info</b> window shows a file, its main properties, its 
undefined and not-called predicates and its import and export relations 
to other files in the project. Both predicates and files can be opened 
by clicking on them. The number of callers in a file for a certain 
predicate is indicated with a blue underlined number. A left-click will 
open a list and allow editing the calling predicate.

<p>The <b>Dependencies</b> (see <a class="fig" href="xref.html#fig:xrefchatdep">figure 
4</a>) window displays a graphical overview of dependencies between 
files. Using the background menu a complete graph of the project can be 
created. It is also possible to drag files onto the graph window and use 
the menu on the nodes to incrementally expand the graph. The underlined 
blue text indicates the number of predicates used in the destination 
file. Left-clicking opens a menu to open the definition or select one of 
the callers.

<p><a id="fig:xrefchatdep"></a><div style="text-align:center"><img src="xrefchatdep.gif"></div>
<div class="caption"><b>Figure 4 : </b>Dependencies between source files 
of CHAT80</div>

<p><b>Module and non-module files</b> 

<p>The cross-referencer threads module and non-module project files 
differently. Module files have explicit import and export relations and 
the tool shows the usage and consistency of the relations. Using the
<b>Header</b> menu command, the tool creates a consistent import list 
for the module that can be included in the file. The tool computes the 
dependency relations between the non-module files. If the user wishes to 
convert the project into a module-based one, the <b>Header</b> command 
generates an appropriate module header and import list. Note that the 
cross-referencer may have missed dependencies and does not deal with 
meta-predicates defined in one module and called in another. Such 
problems must be resolved manually.

<p><b>Settings</b> 

<p>The following settings can be controlled from the <b>settings</b> 
menu:

<dl class="latex">
<dt><b>Warn autoload</b></dt>
<dd class="defbody">
By default disabled. If enabled, modules that require predicates to be 
autoloaded are flagged with a warning and the file info window of a 
module shows the required autoload predicates.</dd>
<dt><b>Warn not called</b></dt>
<dd class="defbody">
If enabled (default), the file overview shows an alert icon for files 
that have predicates that are not called.
</dd>
</dl>

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