7.7 Breakpoint Handling Predicates

This section describes the advanced built-in predicates for creating and removing breakpoints.

add_breakpoint(:Spec, ?BID) development

Adds a breakpoint with a spec Spec, the breakpoint identifier assigned is unified with BID. Spec is one of the following:

Tests-Actions

Tests

standing for Tests-[]

-Actions

standing for []-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:

1. the old spypoint is deleted and a new added as the most recent breakpoint, if this change affects the breakpoint selection mechanism.
2. otherwise, the old spypoint is kept and enabled if needed.

spy(:PredSpec, :Spec) development

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) development

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) development

disable_breakpoints(+BIDs) development

enable_breakpoints(+BIDs) development

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) development

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) development

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,development

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 code-list 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.