protocol

# `debuggerp`

Debugger protocol.

Availability:
`logtalk_load(debugger(loader))`
Author: Paulo Moura
Version: 3:3:0
Date: 2024-06-19
Compilation flags:
`static`
Dependencies:
(none)
Remarks:

> - Debugger help: Type the character `h` (condensed help) or the character `?` (extended help) at a leashed port.

> - Predicate breakpoint: Specified as a ground term `Functor/Arity`.

> - Non-terminal breakpoint: Specified as a ground term `Functor//Arity`.

> - Clause breakpoint: Specified as an `Entity-Line` term with both `Entity` and `Line` bound. `Line` must be the first source file line of an entity clause.

> - Conditional breakpoint: Specified as an `Entity-Line` term with both `Entity` and `Line` bound and a condition. `Line` must be the first source file line of an entity clause.

> - Hit count breakpoint: Specified as an `Entity-Line` term with both `Entity` and `Line` bound and an unification count expression as a condition. `Line` must be the first source file line of an entity clause.

> - Triggered breakpoint: Specified as an `Entity-Line` term with both `Entity` and `Line` bound and another breakpoint as a condition. `Line` must be the first source file line of an entity clause.

> - Context breakpoint: Specified as a `(Sender, This, Self, Goal)` tuple.

> - Log point: Specified as an `(Entity, Line, Message)` tuple.

> - Leash port shorthands: `none` - `[]`, `loose` - `[fact,rule,call]`, `half` - `[fact,rule,call,redo]`, `tight` - `[fact,rule,call,redo,fail,exception]`, and `full` - `[fact,rule,call,exit,redo,fail,exception]`.

Inherited public predicates:
(none)

## Public predicates

### `reset/0`

Resets all debugging settings (including breakpoints, log points, and leashed ports) and turns off debugging.

Compilation flags:
`static`
Mode and number of proofs:
`reset` - `one`
See also:
nospyall/0

### `debug/0`

Starts debugging for all defined breakpoints.

Compilation flags:
`static`
Mode and number of proofs:
`debug` - `one`

### `nodebug/0`

Stops debugging for all defined breakpoints. Also turns off tracing. Does not remove defined breakpoints.

Compilation flags:
`static`
Mode and number of proofs:
`nodebug` - `one`
See also:
reset/0

### `debugging/0`

Reports current debugging settings, including breakpoints and log points.

Compilation flags:
`static`
Mode and number of proofs:
`debugging` - `one`

### `debugging/1`

Enumerates, by backtracking, all entities compiled in debug mode.

Compilation flags:
`static`
Template:
`debugging(Entity)`
Mode and number of proofs:
`debugging(?entity_identifier)` - `zero_or_more`

### `trace/0`

Starts tracing all calls compiled in debug mode.

Compilation flags:
`static`
Mode and number of proofs:
`trace` - `one`

### `notrace/0`

Stops tracing of calls compiled in debug mode. Debugger will still stop at defined breakpoints.

Compilation flags:
`static`
Mode and number of proofs:
`notrace` - `one`

### `leash/1`

Sets the debugger leash ports using an abbreviation (`none`, `loose`, `half`, `tight`, or `full`) or a list of ports (valid ports are `fact`, `rule`, `call`, `exit`, `redo`, `fail`, and `exception`).

Compilation flags:
`static`
Template:
`leash(Ports)`
Mode and number of proofs:
`leash(+atom)` - `one`
`leash(+list(atom))` - `one`

### `leashing/1`

Enumerates, by backtracking, all leashed ports (valid ports are `fact`, `rule`, `call`, `exit`, `redo`, `fail`, and `exception`).

Compilation flags:
`static`
Template:
`leashing(Port)`
Mode and number of proofs:
`leashing(?atom)` - `zero_or_more`

### `spy/1`

Sets a predicate or clause breakpoint (removing any existing log point or breakpoint defined for the same location, or a list of breakpoints. Fails if a breakpoint is invalid.

Compilation flags:
`static`
Template:
`spy(Breakpoint)`
Mode and number of proofs:
`spy(@spy_point)` - `zero_or_one`
`spy(@list(spy_point))` - `zero_or_one`

### `spying/1`

Enumerates, by backtracking, all defined predicate and clause breakpoints.

Compilation flags:
`static`
Template:
`spying(Breakpoint)`
Mode and number of proofs:
`spying(?spy_point)` - `zero_or_more`

### `nospy/1`

Removes all matching predicate and clause breakpoints.

Compilation flags:
`static`
Template:
`nospy(Breakpoint)`
Mode and number of proofs:
`nospy(@var)` - `one`
`nospy(@spy_point)` - `one`
`nospy(@list(spy_point))` - `one`

### `spy/3`

Sets a conditional or triggered breakpoint (removing any existing log point or breakpoint defined for the same location). The condition can be a unification count expression, a lambda expression, or another breakpoint. Fails if the breakpoint is invalid.

Compilation flags:
`static`
Template:
`spy(Entity,Line,Condition)`
Mode and number of proofs:
`spy(+atom,+integer,@callable)` - `zero_or_one`
Remarks:

> - Unification count expression conditions: `>(Count)`, `>=(Count)`, `=:=(Count)`, `=<(Count)`, `<(Count)`, `mod(M)`, and `Count`.

> - Lambda expression conditions: `[Count,N,Goal]>>Condition` and `[Goal]>>Condition` where `Count` is the unification count, `N` is the invocation number, and `Goal` is the goal that unified with the clause head; `Condition` is called in the context of `user`.

> - Triggered breakpoint conditions: `Entity-Line`.

### `spying/3`

Enumerates, by backtracking, all conditional and triggered breakpoints.

Compilation flags:
`static`
Template:
`spying(Entity,Line,Condition)`
Mode and number of proofs:
`spying(?atom,?integer,?callable)` - `zero_or_more`

### `nospy/3`

Removes all matching conditional and triggered breakpoints.

Compilation flags:
`static`
Template:
`nospy(Entity,Line,Condition)`
Mode and number of proofs:
`nospy(@term,@term,@term)` - `one`

### `spy/4`

Sets a context breakpoint.

Compilation flags:
`static`
Template:
`spy(Sender,This,Self,Goal)`
Mode and number of proofs:
`spy(@term,@term,@term,@term)` - `one`

### `spying/4`

Enumerates, by backtracking, all defined context breakpoints.

Compilation flags:
`static`
Template:
`spying(Sender,This,Self,Goal)`
Mode and number of proofs:
`spying(?term,?term,?term,?term)` - `zero_or_more`

### `nospy/4`

Removes all matching context breakpoints.

Compilation flags:
`static`
Template:
`nospy(Sender,This,Self,Goal)`
Mode and number of proofs:
`nospy(@term,@term,@term,@term)` - `one`

### `nospyall/0`

Removes all breakpoints and log points.

Compilation flags:
`static`
Mode and number of proofs:
`nospyall` - `one`
See also:
reset/0

### `log/3`

Sets a log point (removing any existing breakpoint defined for the same location). Fails if the log point is invalid.

Compilation flags:
`static`
Template:
`log(Entity,Line,Message)`
Mode and number of proofs:
`log(@object_identifier,+integer,+atom)` - `zero_or_one`
`log(@category_identifier,+integer,+atom)` - `zero_or_one`
`log(?object_identifier,?integer,?atom)` - `zero_or_more`
`log(?category_identifier,?integer,?atom)` - `zero_or_more`
`log(@var_or(object_identifier),@var_or(integer),@var_or(atom))` - `one`
`log(@var_or(category_identifier),@var_or(integer),@var_or(atom))` - `one`

### `logging/3`

Enumerates, by backtracking, all defined log points.

Compilation flags:
`static`
Template:
`logging(Entity,Line,Message)`

### `nolog/3`

Removes all matching log points.

Compilation flags:
`static`
Template:
`nolog(Entity,Line,Message)`

### `nologall/0`

Removes all log points.

Compilation flags:
`static`
Mode and number of proofs:
`nologall` - `one`
See also:
reset/0

## Protected predicates

(none)

## Private predicates

(none)

## Operators

(none)

See also

debugger