prolog_xref.pl -- Prolog cross-referencer data collection

This module implements to data-collection part of the cross-referencer. This code is used in two places:

• gxref/0 (part of XPCE) provides a graphical front-end for this module
• PceEmacs (also part of XPCE) uses the cross-referencer to color goals and predicates depending on their references.

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).

 xref_source(+Source) is det

 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

 xref_clean(+Source) is det

Reset the database for the given source.

 xref_current_source(?Source)

Check what sources have been analysed.

 xref_done(+Source, -Time) is det

Cross-reference executed at Time

 xref_called(?Source, ?Called, ?By) is nondet

 xref_called(?Source, ?Called, ?By, ?Cond) is nondet

Enumerate the predicate-call relations. Predicate called by directives have a By '<directive>'.

 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)

 xref_definition_line(+How, -Line)

If the 3th argument of xref_defined contains line info, return this in Line.

 xref_exported(?Source, ?Head) is nondet

True when Source exports Head.

 xref_module(?Source, ?Module) is nondet

True if Module is defined in 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>.

 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)

 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.

 xref_comment(?Source, ?Title, ?Comment) is nondet

Is true when Source has a section comment with Title and Comment

 xref_comment(?Source, ?Head, ?Summary, ?Comment) is nondet

Is true when Head in Source has the given PlDoc comment.

 xref_mode(?Source, ?Mode, ?Det) is nondet

Is true when Source provides a predicate with Mode and determinism.

 xref_option(?Source, ?Option) is nondet

True when Source was processed using Option. Options are defined with xref_source/2.

 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).

 xref_meta(+Head, -Called) is semidet

 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.

 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.

 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.

 xref_public_list(+File, -Path, -Export, +Src) is semidet

 xref_public_list(+File, -Path, -Module, -Export, -Meta, +Src) is semidet

 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.

 xref_source_file(+Spec, -File, +Src) is semidet

 xref_source_file(+Spec, -File, +Src, +Options) is semidet

Find named source file from Spec, relative to Src.

 xref_source(+Source) is det

 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

 xref_called(?Source, ?Called, ?By) is nondet

 xref_called(?Source, ?Called, ?By, ?Cond) is nondet

Enumerate the predicate-call relations. Predicate called by directives have a By '<directive>'.

 xref_public_list(+File, -Path, -Export, +Src) is semidet

 xref_public_list(+File, -Path, -Module, -Export, -Meta, +Src) is semidet

 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.

 xref_public_list(+File, -Path, -Export, +Src) is semidet

 xref_public_list(+File, -Path, -Module, -Export, -Meta, +Src) is semidet

 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.

 xref_source_file(+Spec, -File, +Src) is semidet

 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.

 xref_used_class(Arg1, Arg2)

 xref_defined_class(Arg1, Arg2, Arg3)

 xref_built_in(Arg1)