Did you know ... Search Documentation:
prolog_xref.pl -- Prolog cross-referencer data collection
PublicShow source

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.
Source 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.
Source 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
Source prolog:meta_goal(+Goal, -Pattern)[multifile]
Define meta-predicates. See the examples in this file for details.
Source prolog:hook(Goal)[multifile]
True if Goal is a hook that is called spontaneously (e.g., from foreign code).
Source hide_called(:Callable, +Src) is semidet[private]
True when the cross-referencer should not include Callable as being called. This is determined by the option register_called.
 built_in_predicate(+Callable)[private]
True if Callable is a built-in
Source xref_source(+Source) is det
Source xref_source(+Source, +Options) is det
Generate the cross-reference data for Source if not already done and the source is not modified. Checking for modifications is only done for files. Options processed:
silent(+Boolean)
If true (default false), emit warning messages.
module(+Module)
Define the initial context module to work in.
register_called(+Which)
Determines which calls are registerd. Which is one of all, non_iso or non_built_in.
comments(+CommentHandling)
How to handle comments. If store, comments are stored into the database as if the file was compiled. If collect, comments are entered to the xref database and made available through xref_mode/2 and xref_comment/4. If ignore, comments are simply ignored. Default is to collect comments.
process_include(+Boolean)
Process the content of included files (default is true).
Arguments:
Source- File specification or XPCE buffer
Source xref_cleanup(+State) is det[private]
Restore processing state according to the saved State.
Source set_initial_mode(+Stream, +Options) is det[private]
Set the initial mode for processing this file in the cross-referencer. If the file is loaded, we use information from the previous load context, setting the appropriate module and dialect.
Source xref_input_stream(-Stream) is det[private]
Current input stream for cross-referencer.
Source xref_push_op(Source, +Prec, +Type, :Name)[private]
Define operators into the default source module and register them to be undone by pop_operators/0.
Source xref_set_prolog_flag(+Flag, +Value, +Src, +Line)[private]
Called when a directive sets a Prolog flag.
Source xref_clean(+Source) is det
Reset the database for the given source.
Source xref_current_source(?Source)
Check what sources have been analysed.
Source xref_done(+Source, -Time) is det
Cross-reference executed at Time
Source xref_called(?Source, ?Called, ?By) is nondet
Source xref_called(?Source, ?Called, ?By, ?Cond) is nondet
Source xref_called(?Source, ?Called, ?By, ?Cond, ?Line) is nondet
True when By is called from Called in Source. Note that xref_called/3 and xref_called/4 use distinct/2 to return only distinct Called-By pairs. The xref_called/5 version may return duplicate Called-By if Called is called from multiple clauses in By, but at most one call per clause.
Arguments:
By- is a head term or one of the reserved terms '<directive>'(Line) or '<public>'(Line), indicating the call is from an (often initialization/1) directive or there is a public/1 directive that claims the predicate is called from in some untractable way.
Cond- is the (accumulated) condition as defined by :- if(Cond) under which the calling code is compiled.
Line- is the start line of the calling clause.
Source xref_defined(?Source, +Goal, ?How) is nondet
Test if Goal is accessible in Source. If this is the case, How specifies the reason why the predicate is accessible. Note that this predicate does not deal with built-in or global predicates, just locally defined and imported ones. How is one of of the terms below. Location is one of Line (an integer) or File:Line if the definition comes from an included (using :- include(File)) directive.
  • dynamic(Location)
  • thread_local(Location)
  • multifile(Location)
  • public(Location)
  • local(Location)
  • foreign(Location)
  • constraint(Location)
  • imported(From)
  • dcg
Source xref_definition_line(+How, -Line)
If the 3th argument of xref_defined contains line info, return this in Line.
Source xref_exported(?Source, ?Head) is nondet
True when Source exports Head.
Source xref_module(?Source, ?Module) is nondet
True if Module is defined in Source.
Source xref_uses_file(?Source, ?Spec, ?Path) is nondet
True when Source tries to load a file using Spec.
Arguments:
Spec- is a specification for absolute_file_name/3
Path- is either an absolute file name of the target file or the atom <not_found>.
Source xref_op(?Source, Op) is nondet
Give the operators active inside the module. This is intended to setup the environment for incremental parsing of a term from the source-file.
Arguments:
Op- Term of the form op(Priority, Type, Name)
Source xref_prolog_flag(?Source, ?Flag, ?Value, ?Line) is nondet
True when Flag is set to Value at Line in Source. This is intended to support incremental parsing of a term from the source-file.
Source collect(+Source, +File, +Stream, +Options)[private]
Process data from Source. If File \== Source, we are processing an included file. Stream is the stream from which we read the program.
Source update_condition(+Term) is det[private]
Update the condition under which the current code is compiled.
Source current_condition(-Condition) is det[private]
Condition is the current compilation condition as defined by the :- if/1 directive and friends.
Source process(+Expanded, +Comments, +Term, +TermPos, +Src, -EOF) is det[private]
Process a source term that has been subject to term expansion as well as its optional leading structured comments.
Arguments:
TermPos- is the term position that describes the start of the term. We need this to find leading comments.
EOF- is unified with a boolean to indicate whether or not processing was stopped because end_of_file was processed.
Source process(+Term, +Term0, +Src) is det[private]
Source process(+Term, +Src) is det[private]
Source xref_comments(+Comments, +FilePos, +Src) is det[private]
Source xref_comment(?Source, ?Title, ?Comment) is nondet
Is true when Source has a section comment with Title and Comment
Source xref_comment(?Source, ?Head, ?Summary, ?Comment) is nondet
Is true when Head in Source has the given PlDoc comment.
Source xref_mode(?Source, ?Mode, ?Det) is nondet
Is true when Source provides a predicate with Mode and determinism.
Source xref_option(?Source, ?Option) is nondet
True when Source was processed using Option. Options are defined with xref_source/2.
Source process_meta_predicate(+Decl, +Src)[private]
Create meta_goal/3 facts from the meta-goal declaration.
Source xref_meta(+Source, +Head, -Called) is semidet
True when Head calls Called in Source.
Arguments:
Called- is a list of called terms, terms of the form Term+Extra or terms of the form //(Term).
Source xref_meta(+Head, -Called) is semidet
Source xref_meta_src(+Head, -Called, +Src) is semidet
True when Called is a list of terms called from Head. Each element in Called can be of the form Term+Int, which means that Term must be extended with Int additional arguments. The variant xref_meta/3 first queries the local context.
deprecated
- New code should use xref_meta/3.
To be done
- Split predifined in several categories. E.g., the ISO predicates cannot be redefined.
- Rely on the meta_predicate property for many predicates.
Source head_of(+Rule, -Head)[private]
Get the head for a retract call.
Source xref_hook(?Callable)
Definition of known hooks. Hooks that can be called in any module are unqualified. Other hooks are qualified with the module where they are called.
Source arith_callable(+Spec, -Callable)[private]
Translate argument of arithmetic_function/1 into a callable term
Source process_body(+Body, +Origin, +Src) is det[private]
Process a callable body (body of a clause or directive). Origin describes the origin of the call. Partial evaluation may lead to non-determinism, which is why we backtrack over process_goal/3.

We limit the number of explored paths to 100 to avoid getting trapped in this analysis.

Source process_goal(+Goal, +Origin, +Src, ?Partial) is multi[private]
Xref Goal. The argument Partial is bound to true if there was a partial evalation inside Goal that has bound variables.
Source process_dcg_goal(+Grammar, +Origin, +Src, ?Partial) is det[private]
Process meta-arguments that are tagged with //, such as phrase/3.
Source variants(+SortedList, +Max, -Variants) is det[private]
Source partial_evaluate(+Goal, ?Parrial) is det[private]
Perform partial evaluation on Goal to trap cases such as below.
      T = hello(X),
      findall(T, T, List),
To be done
- Make this user extensible? What about non-deterministic bindings?
Source process_use_module(+Modules, +Src, +Rexport) is det[private]
Source process_use_module2(+File, +Import, +Src, +Reexport) is det[private]
Process use_module/2 and reexport/2.
Source load_module_if_needed(+File)[private]
Load a module explicitly if it is not suitable for autoloading. Typically this is the case if the module provides essential term and/or goal expansion rulses.
Source process_requires(+Import, +Src)[private]
Source xref_public_list(+Spec, +Source, +Options) is semidet
Find meta-information about File. This predicate reads all terms upto the first term that is not a directive. It uses the module and meta_predicate directives to assemble the information in Options. Options processed:
path(-Path)
Path is the full path name of the referenced file.
module(-Module)
Module is the module defines in Spec.
exports(-Exports)
Exports is a list of predicate indicators and operators collected from the module/2 term and reexport declarations.
public -Public
Public declarations of the file.
meta(-Meta)
Meta is a list of heads as they appear in meta_predicate/1 declarations.
silent(+Boolean)
Do not print any messages or raise exceptions on errors.

The information collected by this predicate is cached. The cached data is considered valid as long as the modification time of the file does not change.

Arguments:
Source- is the file from which Spec is referenced.
Source xref_public_list(+File, -Path, -Export, +Src) is semidet
Source xref_public_list(+File, -Path, -Module, -Export, -Meta, +Src) is semidet
Source xref_public_list(+File, -Path, -Module, -Export, -Public, -Meta, +Src) is semidet
Find meta-information about File. This predicate reads all terms upto the first term that is not a directive. It uses the module and meta_predicate directives to assemble the information described below.

These predicates fail if File is not a module-file.

Arguments:
Path- is the canonical path to File
Module- is the module defined in Path
Export- is a list of predicate indicators.
Meta- is a list of heads as they appear in meta_predicate/1 declarations.
Src- is the place from which File is referenced.
deprecated
- New code should use xref_public_list/3, which unifies all variations using an option list.
Source public_list(+Path, -Module, -Meta, -Export, -Public, +Options)[private]
Read the public information for Path. Options supported are:
silent(+Boolean)
If true, ignore (syntax) errors. If not specified the default is inherited from xref_source/2.
Source reexport_files(+Files, +Src, -Meta, ?MetaTail, -Exports, ?ExportsTail, -Public, ?PublicTail)[private]
Source except(+Remove, +AllExports, -Exports)[private]
Source open_include_file(+Path, -In, -Refs)[private]
Opens an :- include(File) referenced file. Note that we cannot use prolog_open_source/2 because we should not safe/restore the lexical context.
Source process_foreign(+Spec, +Src)[private]
Process a load_foreign_library/1 call.
Source assert_called(+Src, +From, +Head, +Line) is det[private]
Assert the fact that Head is called by From in Src. We do not assert called system predicates.
Source expand_hide_called(:Callable) is semidet[private]
Goals that should not turn up as being called. Hack. Eventually we should deal with that using an XPCE plugin.
Source assert_import(+Src, +Import, +ExportList, +From, +Reexport) is det[private]
Asserts imports into Src. Import is the import specification, ExportList is the list of known exported predicates or unbound if this need not be checked and From is the file from which the public predicates come. If Reexport is true, re-export the imported predicates.
To be done
- Tighter type-checking on Import.
Source process_import(:Import, +Src)[private]
Process an import/1 directive
Source assert_xmodule_callable(PIs, Module, Src, From)[private]
We can call all exports and public predicates of an imported module using Module:Goal.
To be done
- Should we distinguish this from normal imported?
Source assert_op(+Src, +Op) is det[private]
Arguments:
Op- Ground term op(Priority, Type, Name).
Source assert_module(+Src, +Module)[private]
Assert we are loading code into Module. This is also used to exploit local term-expansion and other rules.
Source assert_module3(+Import, +Src)[private]
Handle 3th argument of module/3 declaration.
Source process_predicates(:Closure, +Predicates, +Src)[private]
Process areguments of dynamic, etc., using call(Closure, PI, Src). Handles both lists of specifications and (PI,...) specifications.
Source pi_to_head(+PI, -Head) is semidet[private]
Translate Name/Arity or Name//Arity to a callable term. Fails if PI is not a predicate indicator.
Source generalise(+Callable, -General)[private]
Generalise a callable term.
Source xref_source_file(+Spec, -File, +Src) is semidet
Source xref_source_file(+Spec, -File, +Src, +Options) is semidet
Find named source file from Spec, relative to Src.
Source canonical_source(?Source, ?Src) is det[private]
Src is the canonical version of Source if Source is given.
Source goal_name_arity(+Goal, -Name, -Arity)[private]
Generalized version of functor/3 that can deal with name() goals.

Re-exported predicates

The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.

Source xref_source(+Source) is det
Source xref_source(+Source, +Options) is det
Generate the cross-reference data for Source if not already done and the source is not modified. Checking for modifications is only done for files. Options processed:
silent(+Boolean)
If true (default false), emit warning messages.
module(+Module)
Define the initial context module to work in.
register_called(+Which)
Determines which calls are registerd. Which is one of all, non_iso or non_built_in.
comments(+CommentHandling)
How to handle comments. If store, comments are stored into the database as if the file was compiled. If collect, comments are entered to the xref database and made available through xref_mode/2 and xref_comment/4. If ignore, comments are simply ignored. Default is to collect comments.
process_include(+Boolean)
Process the content of included files (default is true).
Arguments:
Source- File specification or XPCE buffer
Source xref_called(?Source, ?Called, ?By) is nondet
Source xref_called(?Source, ?Called, ?By, ?Cond) is nondet
Source xref_called(?Source, ?Called, ?By, ?Cond, ?Line) is nondet
True when By is called from Called in Source. Note that xref_called/3 and xref_called/4 use distinct/2 to return only distinct Called-By pairs. The xref_called/5 version may return duplicate Called-By if Called is called from multiple clauses in By, but at most one call per clause.
Arguments:
By- is a head term or one of the reserved terms '<directive>'(Line) or '<public>'(Line), indicating the call is from an (often initialization/1) directive or there is a public/1 directive that claims the predicate is called from in some untractable way.
Cond- is the (accumulated) condition as defined by :- if(Cond) under which the calling code is compiled.
Line- is the start line of the calling clause.
Source xref_called(?Source, ?Called, ?By) is nondet
Source xref_called(?Source, ?Called, ?By, ?Cond) is nondet
Source xref_called(?Source, ?Called, ?By, ?Cond, ?Line) is nondet
True when By is called from Called in Source. Note that xref_called/3 and xref_called/4 use distinct/2 to return only distinct Called-By pairs. The xref_called/5 version may return duplicate Called-By if Called is called from multiple clauses in By, but at most one call per clause.
Arguments:
By- is a head term or one of the reserved terms '<directive>'(Line) or '<public>'(Line), indicating the call is from an (often initialization/1) directive or there is a public/1 directive that claims the predicate is called from in some untractable way.
Cond- is the (accumulated) condition as defined by :- if(Cond) under which the calling code is compiled.
Line- is the start line of the calling clause.
Source xref_public_list(+File, -Path, -Export, +Src) is semidet
Source xref_public_list(+File, -Path, -Module, -Export, -Meta, +Src) is semidet
Source xref_public_list(+File, -Path, -Module, -Export, -Public, -Meta, +Src) is semidet
Find meta-information about File. This predicate reads all terms upto the first term that is not a directive. It uses the module and meta_predicate directives to assemble the information described below.

These predicates fail if File is not a module-file.

Arguments:
Path- is the canonical path to File
Module- is the module defined in Path
Export- is a list of predicate indicators.
Meta- is a list of heads as they appear in meta_predicate/1 declarations.
Src- is the place from which File is referenced.
deprecated
- New code should use xref_public_list/3, which unifies all variations using an option list.
Source xref_public_list(+File, -Path, -Export, +Src) is semidet
Source xref_public_list(+File, -Path, -Module, -Export, -Meta, +Src) is semidet
Source xref_public_list(+File, -Path, -Module, -Export, -Public, -Meta, +Src) is semidet
Find meta-information about File. This predicate reads all terms upto the first term that is not a directive. It uses the module and meta_predicate directives to assemble the information described below.

These predicates fail if File is not a module-file.

Arguments:
Path- is the canonical path to File
Module- is the module defined in Path
Export- is a list of predicate indicators.
Meta- is a list of heads as they appear in meta_predicate/1 declarations.
Src- is the place from which File is referenced.
deprecated
- New code should use xref_public_list/3, which unifies all variations using an option list.
Source xref_source_file(+Spec, -File, +Src) is semidet
Source xref_source_file(+Spec, -File, +Src, +Options) is semidet
Find named source file from Spec, relative to Src.

Undocumented predicates

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

Source xref_built_in(Arg1)
Source xref_defined_class(Arg1, Arg2, Arg3)
Source xref_used_class(Arg1, Arg2)