% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(check): Consistency checking}

\label{sec:check}

\begin{tags}
\mtag{See also}- \predref{gxref}{0} provides a graphical cross referencer \\- PceEmacs performs real time consistency checks while you edit \\- \file{library(prolog_xref)} implements `offline' cross-referencing \\- \file{library(prolog_codewalk)} implements `online' analysis
\end{tags}

This library provides some consistency checks for the loaded Prolog
program. The predicate \predref{make}{0} runs \predref{list_undefined}{0} to find undefined
predicates in `user' modules.\vspace{0.7cm}

\begin{description}
    \predicate[det]{check}{0}{}
Run all consistency checks defined by \predref{checker}{2}. Checks enabled by
default are:

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

The checker can be expanded or restricted by modifying the dynamic
multifile hook \predref{checker}{2}.

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

\begin{code}
swipl -q --on-warning=status --on-error=status \
      -g check -t halt -l myprogram.pl
\end{code}

    \predicate[det]{list_undefined}{0}{}
\nodescription
    \predicate[det]{list_undefined}{1}{+Options}
Report undefined predicates. This predicate finds undefined
predicates by decompiling and analyzing the body of all clauses.
\arg{Options}:

\begin{description}
    \termitem{module_class}{+Classes}
Process modules of the given \arg{Classes}. The default for
classes is \verb$[user]$. For example, to include the
libraries into the examination, use \verb$[user,library]$.
\end{description}

\begin{tags}
\mtag{See also}- \predref{gxref}{0} provides a graphical cross-referencer. \\- \predref{make}{0} calls \predref{list_undefined}{0}
\end{tags}

    \predicate[det]{list_autoload}{0}{}
Report predicates that may be auto-loaded. These are predicates
that are not defined, but will be loaded on demand if
referenced.

\begin{tags}
    \tag{See also}
\predref{autoload}{0}
    \tag{To be done}
This predicate uses an older mechanism for finding
undefined predicates. Should be synchronized with
list undefined.
\end{tags}

    \predicate{list_redefined}{0}{}
Lists predicates that are defined in the global module \const{user} as
well as in a normal module; that is, predicates for which the
local definition overrules the global default definition.

    \predicate[det]{list_cross_module_calls}{0}{}
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 \textit{private}.

    \predicate[det]{list_void_declarations}{0}{}
List predicates that have declared attributes, but no clauses.

    \predicate[det]{list_trivial_fails}{0}{}
\nodescription
    \predicate[det]{list_trivial_fails}{1}{+Options}
List goals that trivially fail because there is no matching
clause. \arg{Options}:

\begin{description}
    \termitem{module_class}{+Classes}
Process modules of the given \arg{Classes}. The default for
classes is \verb$[user]$. For example, to include the
libraries into the examination, use \verb$[user,library]$.
\end{description}

    \predicate[multifile]{trivial_fail_goal}{1}{:Goal}
Multifile hook that tells \predref{list_trivial_fails}{0} to accept \arg{Goal} as
valid.

    \predicate[det]{list_strings}{0}{}
\nodescription
    \predicate[det]{list_strings}{1}{+Options}
List strings that appear in clauses. This predicate is used to
find portability issues for changing the Prolog flag
\verb$double_quotes$ from \const{codes} to \const{string}, creating packed string
objects. Warnings may be suppressed using the following
multifile hooks:

\begin{itemize}
    \item \predref{string_predicate}{1} to stop checking certain predicates
    \item \predref{valid_string_goal}{1} to tell the checker that a goal is
safe.
\end{itemize}

\begin{tags}
    \tag{See also}
Prolog flag \verb$double_quotes$.
\end{tags}

    \predicate[det]{list_rationals}{0}{}
\nodescription
    \predicate[det]{list_rationals}{1}{+Options}
List rational numbers that appear in clauses. This predicate is used
to find portability issues for changing the Prolog flag
\verb$rational_syntax$ to \const{natural}, creating rational numbers from
$<$integer$>$/$<$nonneg$>$. \arg{Options}:

\begin{description}
    \termitem{module_class}{+Classes}
Determines the modules classes processed. By default only
user code is processed. See \predref{prolog_program_clause}{2}.
    \termitem{arithmetic}{+Bool}
If \const{true} (default \const{false}) also warn on rationals appearing
in arithmetic expressions.
\end{description}

\begin{tags}
    \tag{See also}
Prolog flag \prologflag{rational_syntax} and \verb$prefer_rationals$.
\end{tags}

    \predicate[det]{list_format_errors}{0}{}
\nodescription
    \predicate[det]{list_format_errors}{1}{+Options}
List argument errors for \predref{format}{2},3.

    \predicate[multifile]{string_predicate}{1}{:PredicateIndicator}
Multifile hook to disable \predref{list_strings}{0} on the given predicate.
This is typically used for facts that store strings.

    \predicate[semidet,multifile]{valid_string_goal}{1}{+Goal}
Multifile hook that qualifies \arg{Goal} as valid for \predref{list_strings}{0}.
For example, \verb$format("Hello world~n")$ is considered proper use of
string constants.

    \predicate[nondet,multifile]{checker}{2}{:Goal, +Message:text}
Register code validation routines. Each clause defines a \arg{Goal} which
performs a consistency check executed by \predref{check}{0}. \arg{Message} is a short
description of the check. For example, assuming the \verb$my_checks$
module defines a predicate \predref{list_format_mistakes}{0}:

\begin{code}
:- multifile check:checker/2.
check:checker(my_checks:list_format_mistakes,
              "errors with format/2 arguments").
\end{code}

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

\begin{code}
retract(check:checker(list_redefined,_)).
\end{code}

\end{description}