check.pl -- Consistency checking

This library provides some consistency checks for the loaded Prolog program. The predicate make/0 runs list_undefined/0 to find undefined predicates in `user' modules.

See also: - gxref/0 provides a graphical cross referencer; - PceEmacs performs real time consistency checks while you edit; - library(prolog_xref) implements `offline' cross-referencing; - library(prolog_codewalk) implements `online' analysis

check is det

Run all consistency checks defined by checker/2. Checks enabled by default are:

list_undefined/0 reports undefined predicates
list_trivial_fails/0 reports calls for which there is no matching clause.
list_format_errors/0 reports mismatches in format/2,3 templates and the list of arguments.
list_redefined/0 reports predicates that have a local definition and a global definition. Note that these are not errors.
list_void_declarations/0 reports on predicates with defined properties, but no clauses.
list_autoload/0 lists predicates that will be defined at runtime using the autoloader.
check_predicate_options/0 tests for options passed to predicates such as open/4 that are unknown or are used with an invalid argument.

The checker can be expanded or restricted by modifying the dynamic multifile hook checker/2.

The checker may be used in batch, e.g., for CI workflows by calling SWI-Prolog as below. Note that by using -l to load the program, the program is not started if it used initialization/2 of type main to start the program.

swipl -q --on-warning=status --on-error=status \
      -g check -t halt -l myprogram.pl

list_undefined is det

list_undefined(+Options) is det

Report undefined predicates. This predicate finds undefined predicates by decompiling and analyzing the body of all clauses. Options:

module_class(+Classes): Process modules of the given Classes. The default for classes is [user]. For example, to include the libraries into the examination, use [user,library].

See also: - gxref/0 provides a graphical cross-referencer.; - make/0 calls list_undefined/0

not_always_present(+PI) is semidet[private]

True when some predicate is known to be part of the state but is not available in this version.

list_autoload is det

Report predicates that may be auto-loaded. These are predicates that are not defined, but will be loaded on demand if referenced.

See also: - autoload/0
To be done: - This predicate uses an older mechanism for finding undefined predicates. Should be synchronized with list undefined.

referenced(+Predicate, ?Module, -ClauseRef) is nondet[private]

True if clause ClauseRef references Predicate.

list_redefined

Lists predicates that are defined in the global module user as well as in a normal module; that is, predicates for which the local definition overrules the global default definition.

list_cross_module_calls is det

List calls from one module to another using Module:Goal where the callee is not defined exported, public or multifile, i.e., where the callee should be considered private.

list_void_declarations is det

List predicates that have declared attributes, but no clauses.

list_trivial_fails is det

list_trivial_fails(+Options) is det

List goals that trivially fail because there is no matching clause. Options:

module_class(+Classes): Process modules of the given Classes. The default for classes is [user]. For example, to include the libraries into the examination, use [user,library].

trivial_fail_goal(:Goal)[multifile]

Multifile hook that tells list_trivial_fails/0 to accept Goal as valid.

qualify_meta_goal(+Module, +MetaSpec, +Goal, -QualifiedGoal)[private]

Qualify a goal if the goal calls a meta predicate

list_strings is det

list_strings(+Options) is det

List strings that appear in clauses. This predicate is used to find portability issues for changing the Prolog flag double_quotes from codes to string, creating packed string objects. Warnings may be suppressed using the following multifile hooks:

string_predicate/1 to stop checking certain predicates
valid_string_goal/1 to tell the checker that a goal is safe.

See also: - Prolog flag double_quotes.

list_rationals is det

list_rationals(+Options) is det

List rational numbers that appear in clauses. This predicate is used to find portability issues for changing the Prolog flag rational_syntax to natural, creating rational numbers from <integer>/<nonneg>. Options:

module_class(+Classes): Determines the modules classes processed. By default only user code is processed. See prolog_program_clause/2.
arithmetic(+Bool): If true (default false) also warn on rationals appearing in arithmetic expressions.

See also: - Prolog flag rational_syntax and prefer_rationals.

list_format_errors is det

list_format_errors(+Options) is det

List argument errors for format/2,3.

goal_in_body(-G, +M, +Body) is nondet[private]

True when G is a goal called from Body.

message_context(+ClauseRef, +Term, +Clause, -Pos) is det[private]

Find an as accurate as possible location for Term in Clause.

string_predicate(:PredicateIndicator)[multifile]

Multifile hook to disable list_strings/0 on the given predicate. This is typically used for facts that store strings.

valid_string_goal(+Goal) is semidet[multifile]

Multifile hook that qualifies Goal as valid for list_strings/0. For example, format("Hello world~n") is considered proper use of string constants.

checker(:Goal, +Message:text) is nondet[multifile]

Register code validation routines. Each clause defines a Goal which performs a consistency check executed by check/0. Message is a short description of the check. For example, assuming the my_checks module defines a predicate list_format_mistakes/0:

:- multifile check:checker/2.
check:checker(my_checks:list_format_mistakes,
              "errors with format/2 arguments").

The predicate is dynamic, so you can disable checks with retract/1. For example, to stop reporting redefined predicates:

retract(check:checker(list_redefined,_)).

sort_reference_key(+Reference, -Key) is det[private]

Create a stable key for sorting references to predicates.

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.