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' generated (on backtracking), a list of possible break-points.

Note that in addition to setting the break-point, 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, -AZ) is det[private]

True when File and AZ represent the location of the goal called at PC in ClauseRef.

Arguments:

AZ	- is a term A-Z, where A and Z are character positions in File.

Undocumented predicates

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

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