This module provides an interface for development tools to set and
delete break-points, giving a location in the source. Development tools
that want to track changes to breakpoints must use user:message_hook/3
to intercept these message terms:
breakpoint(set, Id)
breakpoint(delete, Id)
Note that the hook must fail after creating its side-effects to give
other hooks the opportunity to react.
- set_breakpoint(+File, +Line, +Char, -Id) is det
- set_breakpoint(+Owner, +File, +Line, +Char, -Id) is det
- Put a breakpoint at the indicated source-location. File is a current
sourcefile (as reported by source_file/1). Line is the 1-based line
in which Char is. Char is the position of the break.
First, '$clause_from_source'/4 uses the SWI-Prolog clause-source
information to find the last clause starting before Line.
'$break_pc' generates (on backtracking), a list of possible
breakpoints.
Note that in addition to setting the breakpoint, the system must be
in debug mode for the breakpoint to take effect. With threading
enabled, there are various different ways this may be done. See
debug/0, tdebug/0 and tdebug/1. Therefore, this predicate does not
enable debug mode.
- Arguments:
-
- delete_breakpoint(+Id) is det
- Delete breakpoint with given Id. If successful,
print_message(breakpoint(delete, Id))
is called. Message hooks
working on this message may still call breakpoint_property/2.
- Errors
- -
existence_error(breakpoint, Id)
.
- breakpoint_property(?Id, ?Property) is nondet
- True when Property is a property of the breakpoint Id. Defined
properties are:
- file(File)
- Provided if the breakpoint is in a clause associated to a
file. May not be known.
- line_count(Line)
- Line of the breakpoint. May not be known.
- character_range(Start, Len)
- One-based character offset of the break-point. May not be
known.
- clause(Reference)
- Reference of the clause in which the breakpoint resides.
- file_line(+File, +StartIndex, -Line) is det[private]
- True when Line is the 1-based line offset in which we find
character StartIndex.
- break_location(+ClauseRef, +PC, -File, -Pos) is det[private]
- True when File and Pos represent the file and subterm position term
for the goal called at PC in ClauseRef.
- Arguments:
-
Pos | - is a subterm position term (see subterm_positions option
of read_term/3, where positions are character positions in File. The
first two argument always hold the start and end of the term. |
- set_breakpoint_condition(+Id, +Cond) is det
- Set a condition for of the breakpoint with given Id. The condition
Cond is a string that represents a Prolog goal to be invoked
whenever the breakpoint is reached, if goal fails the breakpoint is
skipped and execution commences normally.
Variables in Cond that match by name to variables in the source
definition of the clause in which the breakpoint is located are
unified with the corresponding runtime value of the clause variables
in the current execution frame, before evaluating the condition
goal.
- Errors
- -
existence_error(breakpoint, Id)
.