5.6.1 Creating Breakpoints

Breakpoints can be created using the add_breakpoint/2 built-in predicate. Its first argument should contain the description of the breakpoint, the so called breakpoint spec. It will return the breakpoint identifier (BID) of the created breakpoint in its second argument. For example:

     | ?- add_breakpoint(pred(foo/2), BID).
     % Plain spypoint for user:foo/2 added, BID=1
     BID = 1

Here, we have a simple breakpoint spec, prescribing that the debugger should stop at all ports of all invocations of the predicate foo/2. Thus the above goal actually creates a plain spypoint, exactly as ?- spy foo/2. does.

A slightly more complicated example follows:

     | ?- add_breakpoint([pred(foo/2),line('/myhome/bar.pl',123)], _).
     % Conditional spypoint for user:foo/2 added, BID=1

This breakpoint will be activated only for those calls of foo/2 that occur in line 123 of the Prolog program file '/myhome/bar.pl'. Because of the additional condition, this is called a conditional spypoint.

The breakpoint identifier (BID) returned by add_breakpoint/2 is an integer, assigned in increasing order, i.e. more recent breakpoints receive higher identifier values. When looking for applicable breakpoints, the debugger tries the breakpoints in descending order of BIDs, i.e. the most recent applicable breakpoint is used. Breakpoint identifiers can be used for referring to breakpoints to be deleted, disabled or enabled (see later).

Generally, the breakpoint spec is a pair Tests-Actions. Here, the Tests part describes the conditions under which the breakpoint should be activated, while the Actions part contains instructions on what should be done at activation. The test part is built from tests, while the action part from actions and tests. Test, actions and composite constructs built from these are generally referred to as breakpoint conditions, or simply conditions.

The action part can be omitted, and then the breakpoint spec consists of tests only. For spypoints, the default action part is [show(print),command(ask)]. This instructs the debugger to print the goal in question and then ask the user what to do next, exactly as described in Debug Format. To illustrate other possibilities let us explain the effect of the [show(display),command(proceed)] action part: this will use display/1 for presenting the goal (just as the `d' debugger command does, see Debug Commands), and will then proceed with execution without stopping (i.e. the spypoint is unleashed).