This section describes the advanced built-in predicates for creating and removing breakpoints.
add_breakpoint(
:Spec,
?BID)
Adds a breakpoint with a spec Spec, the breakpoint identifier assigned is unified with BID. Spec is one of the following:
-
Actions
-[]
-
Actions
[]-
Actions
Here, both Tests and Actions are either a simple
Condition, see Breakpoint Conditions, or a composite
Condition. Conditions can be composed by forming lists, or by using the
,
, ;
, ->
, and \+
operators, with the usual
meaning of conjunction, disjunction, if-then-else, and negation,
respectively. A list of conditions is equivalent to a conjunction of the
same conditions ([
A|
B]
is treated as
(
A,
B)
).
The add_breakpoint/2
predicate performs some transformations and
checks before adding the breakpoint. All condition macros invoked are
expanded into their bodies, and this process is repeated for the newly
introduced bodies. The goal
and pred
conditions are then
extracted from the outermost conjunctions of the test part and
moved to the beginning of the conjunction. If these are inconsistent, a
consistency error is signalled. Module name expansion is performed for
certain tests, as described below.
Both the original and the transformed breakpoint spec is recorded by the
debugger. The original is returned in current_breakpoint/5
, while
the transformed spec is used in determining the applicability of
breakpoints.
There can only be a single plain spypoint for each predicate. If a plain spypoint is added, and there is already a plain spypoint for the given predicate, then:
spy(
:PredSpec,
:Spec)
Adds a conditional spypoint with a breakpoint spec formed by adding
pred(
Pred)
to the test part of Spec, for each predicate
Pred designated by the generalized predicate spec
PredSpec.
current_breakpoint(
:Spec,
?BID,
?Status,
?Kind,
?Type)
There is a breakpoint with breakpoint spec Spec, identifier
BID, status Status, kind Kind, and type Type.
Status is one of on
or off
, referring to enabled and
disabled breakpoints. Kind is one of plain(
MFunc)
,
conditional(
MFunc)
or generic
, where MFunc is
the module qualified functor of the specific breakpoint. Type is
the breakpoint type: debugger
or advice
.
current_breakpoint/5
enumerates all breakpoints on backtracking.
The Spec as returned by current_breakpoint/5
is
exactly the same as supplied at the creation of the breakpoint,
remove_breakpoints(
+BIDs)
disable_breakpoints(
+BIDs)
enable_breakpoints(
+BIDs)
Removes, disables or enables the breakpoints with identifiers specified by
BIDs. BIDs can be a number, a list of numbers or one of the
atoms: all
, debugger
, advice
. The atoms specify all
breakpoints, debugger type breakpoints and advice type breakpoints,
respectively.
execution_state(
:Tests)
Tests are satisfied in the current state of the execution.
Arbitrary tests can be used in this predicate, if it is called from
inside the debugger, i.e. from within a true
condition. Otherwise only those tests can be used, which query the data
stored in the backtrace. An exception is raised if the latter condition
is violated, i.e. a non-backtraced test (see Breakpoint Conditions)
occurs in a call of
execution_state/1
from outside the debugger.
execution_state(
+FocusConditions,
:Tests)
Tests are satisfied in the state of the execution pointed to by FocusConditions (see Past States). An exception is raised if there is a non-backtraced test among Tests.
Note that the predicate arguments holding a breakpoint spec (Spec
or Tests above) are subject to module name expansion. The first
argument within simple tests goal(_)
, pred(_)
,
parent_pred(_)
, parent_pred(_,_)
, ancestor(_,_)
,
and true(_)
will inherit the module name from the (module name
expanded) breakpoint spec/tests predicate argument, if there is no
explicit module qualification within the simple test. Within the
proceed(
Old,
New)
and flit(
Old,
New)
command value settings, Old will get the module name from the
goal
or pred
condition by default, while New from the whole
breakpoint spec argument.
The following hook predicate can be used to customize the behavior of the interactive debugger.
debugger_command_hook(
+DCommand,
?Actions)
[Hook]
user:debugger_command_hook(
+DCommand,
?Actions)
This predicate is called for each debugger command SICStus Prolog reads in. The first argument is the abstract format of the debugger command DCommand, as returned by the query facility (see Query Processing). If it succeeds, Actions is taken as the list of actions (see Action Conditions) to be done for the given debugger command. If it fails, the debugger command is interpreted in the standard way.
Note that if a line typed in in response to the debugger prompt can not
be parsed as a debugger command, debugger_command_hook/2
is
called with the term unknown(Line,Warning)
. Here, Line
is
the list of character codes typed in, with any leading layout removed,
and Warning
is a warning message. This allows the user to define
new debugger commands, see Hooks Related to Breakpoints for an example.