prolog_xref.pl -- Prolog cross-referencer data collection

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.

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

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). Input handling is done by the library(prolog_source), which may be hooked to process any source 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 by Source.

See also

- Where this library analyses source text, library(prolog_codewalk) may be used to analyse loaded code. The library(check) exploits library(prolog_codewalk) to report on e.g., undefined predicates.

bug

- meta_predicate/1 declarations take the module into consideration. Predicates that are both available as meta-predicate and normal (in different modules) are handled as meta-predicate in all places.

 prolog:called_by(+Goal, +Module, +Context, -Called) is semidet[multifile]

True when Called is a list of callable terms called from Goal, handled by the predicate Module:Goal and executed in the context of the module Context. Elements of Called may be qualified. If not, they are called in the context of the module Context.

 prolog:called_by(+Goal, -ListOfCalled)[multifile]

If this succeeds, the cross-referencer assumes Goal may call any of the goals in ListOfCalled. If this call fails, default meta-goal analysis is used to determine additional called goals.

deprecated

- New code should use prolog:called_by/4

 prolog:meta_goal(+Goal, -Pattern)[multifile]

Define meta-predicates. See the examples in this file for details.

 prolog:hook(Goal)[multifile]

True if Goal is a hook that is called spontaneously (e.g., from foreign code).

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

 xref_comment(Arg1, Arg2, Arg3)

 xref_uses_file(Arg1, Arg2, Arg3)

 xref_defined(Arg1, Arg2, Arg3)

 xref_definition_line(Arg1, Arg2)

 xref_called(Arg1, Arg2, Arg3, Arg4)

 xref_called(Arg1, Arg2, Arg3, Arg4, Arg5)

 xref_op(Arg1, Arg2)

 xref_source(Arg1, Arg2)

 xref_called(Arg1, Arg2, Arg3)

 xref_module(Arg1, Arg2)

 xref_public_list(Arg1, Arg2, Arg3, Arg4, Arg5, Arg6, Arg7)

 xref_source(Arg1)

 xref_used_class(Arg1, Arg2)

 xref_meta(Arg1, Arg2)

 xref_defined_class(Arg1, Arg2, Arg3)

 xref_meta(Arg1, Arg2, Arg3)

 xref_hook(Arg1)

 xref_exported(Arg1, Arg2)

 xref_public_list(Arg1, Arg2, Arg3)

 xref_public_list(Arg1, Arg2, Arg3, Arg4, Arg5, Arg6)

 xref_source_file(Arg1, Arg2, Arg3)

 xref_built_in(Arg1)

 xref_public_list(Arg1, Arg2, Arg3, Arg4)

 xref_done(Arg1, Arg2)

 xref_current_source(Arg1)

 xref_option(Arg1, Arg2)

 xref_prolog_flag(Arg1, Arg2, Arg3, Arg4)

 xref_clean(Arg1)

 xref_comment(Arg1, Arg2, Arg3, Arg4)

 xref_source_file(Arg1, Arg2, Arg3, Arg4)

 xref_mode(Arg1, Arg2, Arg3)