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



\section{library(prolog_debug): User level debugging tools}

\label{sec:prologdebug}

This library provides tools to control the Prolog debuggers.
Traditionally this code was built-in. Because these tools are only
required in (interactive) debugging sessions they have been moved into
the library.\vspace{0.7cm}

\begin{description}
\qpredicate[multifile]{prolog}{debug_control_hook}{1}{+Action}Allow user-hooks in the Prolog debugger interaction. See the calls
below for the provided hooks. We use a single predicate with action
argument to avoid an uncontrolled poliferation of hooks.

    \predicate[det]{spy}{1}{:Spec}
\nodescription
    \predicate[det]{nospy}{1}{:Spec}
\nodescription
    \predicate[det]{nospyall}{0}{}
Set/clear spy-points. A successfully set or cleared spy-point is
reported using \predref{print_message}{2}, level \const{informational}, with one of
the following terms, where \arg{Spec} is of the form M:Head.

\begin{shortlist}
    \item \verb$spy(Spec)$
    \item \verb$nospy(Spec)$
\end{shortlist}

\begin{tags}
    \tag{See also}
\predref{spy}{1} and \predref{nospy}{1} call the hook \qpredref{prolog}{debug_control_hook}{1}
to allow for alternative specifications of the thing to
debug.
\end{tags}

    \predicate[det]{debugging}{0}{}
Report current status of the debugger.

    \predicate[multifile]{debugging_hook}{0}{}
Multifile hook that is called as \verb$forall(debugging_hook, true)$ and
that may be used to extend the information printed from other
debugging libraries.

    \predicate[det]{trap}{1}{+Formal}
\nodescription
    \predicate[det]{notrap}{1}{+Formal}
Install a trap on \verb$error(Formal, Context)$ exceptions that unify. The
tracer is started when a matching exception is raised. This
predicate enables \textit{debug mode} using \predref{debug}{0} to get more context
about the exception. Even with debug mode disabled exceptions are
still trapped and thus one may call \predref{nodebug}{0} to run in normal mode
after installing a trap. Exceptions are trapped in any thread. Debug
mode is only enabled in the calling thread. To enable debug mode in
all threads use \predref{tdebug}{0}.

Calling \predref{debugging}{0} lists the enabled traps. The predicate \predref{notrap}{1}
removes matching (unifying) traps.

In many cases debugging an exception that is caught is as simple as
below (assuming \predref{run}{0} starts your program).

\begin{code}
?- trap(_).
?- run.
\end{code}

The multifile hook \predref{trap_alias}{2} allow for defining short hands for
commonly used traps. Currently this defines

\begin{description}
    \termitem{det}{}
Trap determinism exceptions raised as a result of the \predref{det}{1}
directive.
    \termitem{\Sssu}{}
Trap rule existence error exceptions.
\end{description}

\begin{tags}
\mtag{See also}- \predref{gtrap}{1} to trap using the graphical debugger. \\- \textit{Edit exceptions} menu in PceEmacs and the graphical debugger
that provide a graphical frontend to trap exceptions.
\end{tags}

    \predicate[multifile]{trap_alias}{2}{+Alias, -Error}
Define short hands for commonly used exceptions.
\end{description}