prolog_breakpoints.pl -- Manage Prolog break-points
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.
- 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. - 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.
- 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.
Re-exported predicates
The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.
- 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.