Breakpoint Handling Predicates

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:

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. 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 first normalizes the Conditions, before adding the breakpoint. In both the test and action parts the outermost conjunctions are transformed into lists. The goal and pred conditions are then extracted from the outermost list of the test part and their consistency is checked. Subsequently, a goal condition is inserted as the first element of the tests list, encapsulating the possibly implicit module qualification, all extracted goal conditions, and those extracted pred conditions which can be transformed to a goal condition. Furthermore the debugger condition is removed, and the advice condition is moved to the second element of the tests list. Finally, a pred condition is inserted in front of the remaining tests, in the rare cases when it can not be made part of the preceding goal test. The rest of the test part and the action part is the same as supplied, with the extracted conditions removed.

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)

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)

There is a breakpoint with breakpoint spec Spec, identifier BID, status Status and kind Kind. Status is one of on or off, referring to enabled and disabled breakpoints. Kind is one of plain, conditional or generic. current_breakpoint/4 enumerates all breakpoints on backtracking.

The Spec as returned by current_breakpoint/4 may not be exactly the same as supplied at the creation of the breakpoint, because of the transformations done at creation, see the description of add_breakpoint/2 above.

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 built-in predicate arguments holding a breakpoint spec (Spec or Tests above) are subject to module name expansion. The first argument within simple tests goal(_), pred(_), ancestor(_,_), and true(_) will inherit the module name from the (module name expanded) breakpoint spec argument, in the absence of explicit module qualification within the simple condition.

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.