This module defines high-level primitives for examining the Prolog
stack, primarily intended to support debugging. It provides the
This library may be enabled by default to improve interactive debugging,
for example by adding the lines below to your
decorate uncaught exceptions:
- - Use of this library may negatively impact performance of
applications that process (error-)exceptions frequently
as part of their normal processing.
- get_prolog_backtrace(+MaxDepth, -Backtrace) is det
- get_prolog_backtrace(+MaxDepth, -Backtrace, +Options) is det
- Obtain a backtrace from the current location. The backtrace is a
list of frames. Each frame is an opaque term that can be
inspected using the predicate prolog_stack_frame_property/2 can
be used to extract information from these frames. Most use
scenarios will pass the stack to print_prolog_backtrace/2. The
following options are provided:
- Start at Frame instead of the current frame.
- If Depth > 0, include a shallow copy of the goal arguments
into the stack. Default is set by the Prolog flag
backtrace_goal_depth, set to
2 initially, showing the
goal and toplevel of any argument.
- Do not show stack frames above Guard. See stack_guard/1.
- Report locations as
Clause+PC or as a location term that
does not use clause references, allowing the exception to
be printed safely in a different context.
|Frame||- is the frame to start from. See prolog_current_frame/1.|
|MaxDepth||- defines the maximum number of frames returned.|
- - get_prolog_backtrace/3 used to have the parameters
+Frame, +MaxDepth, -Backtrace. A call that matches this
signature is mapped to
- clause_where(+UseClauseRef, +Clause, +PC, -Where, +Options) is det[private]
- Get a description of the frame source location from Clause and the
PC inside clause. If UseClauseRef is
true, this is the a term
clause(Clause,PC), providing all abvailable information to the
caller at low time overhead. If however the exception need to be
printed in an environment where the clause references may differ,
for example because the program is not loaded, it is printed in a
different thread and contains references to dynamic predicates, etc,
it is better to use the information inside the clause here.
- copy_goal(+TermDepth, +Frame, -Goal) is det[private]
- Create a shallow copy of the frame's goal to help debugging. In
addition to shallow copying, high-arity terms are represented
as below. Currently the 16 first arguments are hardcoded.
name(A1, ..., A16, <skipped Skipped of Arity>, An)
- prolog_stack_frame_property(+Frame, ?Property) is nondet
- True when Property is a property of Frame. Frame is an element
of a stack-trace as produced by get_prolog_backtrace/2. Defined
- print_prolog_backtrace(+Stream, +Backtrace) is det
- print_prolog_backtrace(+Stream, +Backtrace, +Options) is det
- Print a stacktrace in human readable form to Stream.
Options is an option list that accepts:
true, print subgoal line numbers. The default depends
on the Prolog flag
|Backtrace||- is a list of |
- clause_predicate_name(+ClauseRef, -Predname) is det[private]
- Produce a name (typically Functor/Arity) for a predicate to
which Clause belongs.
- Get and print a stacktrace to the user_error stream.
- lineno(+File, +Char, -Line)[private]
- Translate a character location to a line-number. Note that this
calls try_open_source/2, but this is always loaded as
we would not have clause info without.
- prolog_stack:stack_guard(+PI) is semidet[multifile]
- Dynamic multifile hook that is normally not defined. The hook is
called with PI equal to
none if the exception is not caught
and with a fully qualified (e.g., Module:Name/Arity) predicate
indicator of the predicate that called catch/3 if the exception
The exception is of the form
error(Formal, ImplDef) and this
hook succeeds, ImplDef is unified to a term
context(prolog_stack(StackData), Message). This context
information is used by the message printing system to print a
human readable representation of the stack when the exception
For example, using a clause
stack_guard(none) prints contexts
for uncaught exceptions only. Using a clause
prints a full stack-trace for any error exception if the
exception is given to print_message/2. See also
library(http/http_error), which limits printing of exceptions to
exceptions in user-code called from the HTTP server library.
Details of the exception decoration is controlled by two Prolog
- Integer that controls the maximum number of frames
collected. Default is 20. If a guard is specified, callers
of the guard are removed from the stack-trace.
- Boolean that indicates whether the library tries to find
line numbers for the calls. Default is
- stack_guard(+Reason) is semidet[multifile]
- Dynamic multifile predicate. It is called with
the predicate indicator of the guard, the predicate calling
catch/3. The exception must be of compatible with the shape
error(Formal, context(Stack, Msg)). The default is to catch
none, uncaught exceptions.
'C' implies that the callback
from C will handle the exception.