A.27 library(prolog_xref): Cross-reference data collection library

This library collects information on defined and used objects in Prolog source files. 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.

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. Please do not consider this interface rock-solid.

The library is exploited by two graphical tools in the SWI-Prolog environment: the XPCE front-end started by gxref/0 and described in section 3.7, and PceEmacs (section 3.4), which exploits this library for its syntax colouring.

For all predicates described below, Source is the source that is processed. This is normally a filename in any notation acceptable to the file loading predicates (see load_files/2). Using the hooks defined in section A.27.1 it can be anything else that can be translated into a Prolog stream holding Prolog source text. Callable is a callable term (see callable/1). Callables do not carry a module qualifier unless the referred predicate is not in the module defined Source.

xref_source(+Source)

Gather information on Source. If Source 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.

xref_current_source(?Source)

Source has been processed.

xref_clean(+Source)

Remove the information gathered for Source

xref_defined(?Source, ?Callable, -How)

Callable is defined in Source. How is one of

dynamic(Line)	Declared dynamic at Line
thread_local(Line)	Declared thread local at Line
multifile(Line)	Declared multifile at Line
local(Line)	First clause at Line
foreign(Line)	Foreign library loaded at Line
constraint(Line)	CHR Constraint at Line
imported(File)	Imported from File

xref_called(?Source, ?Callable, ?By)

Callable is called in Source by By.

xref_exported(?Source, ?Callable)

Callable is public (exported from the module).

xref_module(?Source, ?Module)

Source is a module file defining the given module.

xref_built_in(?Callable)

True if Callable is a built-in predicate. Currently this is assumed for all predicates defined in the system module and having the property built_in. Built-in predicates are not registered as `called'.

A.27.1 Extending the library

The library provides hooks for extending the rules it uses for finding predicates called by some programming construct.

prolog:called_by(+Goal, -Called)

Goal is a non-var subgoal appearing in the called object (typically a clause body). If it succeeds it must return a list of goals called by Goal. As a special construct, if a term Callable+N is returned, N variable arguments are added to Callable before further processing. For simple meta-calls a single fact suffices. Complex rules as used in the library(html_write) library provided by the HTTP package examine the arguments and create a list of called objects.

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