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.

Arguments:

Owner

- denotes the file that owns the clause. set_breakpoint/5 is used to set breakpoints in an included file in the context of the Owner main file. See source_file_property/2.

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

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

 set_breakpoint(Arg1, Arg2, Arg3, Arg4, Arg5)