This library provides tools to control the Prolog debuggers. Traditionally this code was built-in. Because these tools are only required in (interactive) debugging sessions they have been moved into the library.

 prolog:debug_control_hook(+Action)[multifile]

Allow user-hooks in the Prolog debugger interaction. See the calls below for the provided hooks. We use a single predicate with action argument to avoid an uncontrolled poliferation of hooks.

 spy :Spec is det

 nospy :Spec is det

 nospyall is det

Set/clear spy-points. A successfully set or cleared spy-point is reported using print_message/2, level informational, with one of the following terms, where Spec is of the form M:Head.

• spy(Spec)
• nospy(Spec)

See also

- spy/1 and nospy/1 call the hook prolog:debug_control_hook/1 to allow for alternative specifications of the thing to debug.

 debugging is det

Report current status of the debugger.

 debugging_hook(+DebugMode)[multifile]

Multifile hook that is called as forall(debugging_hook(DebugMode), true) and that may be used to extend the information printed from other debugging libraries.

 trap(+Formal) is det

 notrap(+Formal) is det

Install a trap on error(Formal, Context) exceptions that unify. The tracer is started when a matching exception is raised. This predicate enables debug mode using debug/0 to get more context about the exception. Even with debug mode disabled exceptions are still trapped and thus one may call nodebug/0 to run in normal mode after installing a trap. Exceptions are trapped in any thread. Debug mode is only enabled in the calling thread. To enable debug mode in all threads use tdebug/0.

Calling debugging/0 lists the enabled traps. The predicate notrap/1 removes matching (unifying) traps.

In many cases debugging an exception that is caught is as simple as below (assuming run/0 starts your program).

?- trap(_).
?- run.

The multifile hook trap_alias/2 allow for defining short hands for commonly used traps. Currently this defines

det

Trap determinism exceptions raised as a result of the det/1 directive.

=>

Trap rule existence error exceptions.

See also

- gtrap/1 to trap using the graphical debugger.

- Edit exceptions menu in PceEmacs and the graphical debugger that provide a graphical frontend to trap exceptions.

 trap_alias(+Alias, -Error)[multifile]

Define short hands for commonly used exceptions.

 exception_hook(+ExIn, -ExOut, +Frame, +Catcher, +DebugMode) is failure

Trap exceptions and consider whether or not to start the tracer.

 direct_catch(+Frame) is semidet[private]

True if we are dealing with a catch(SytemPred, _, _), i.e., a catch directly wrapped around a call to a built-in. In that case it is highly unlikely that we want the debugger to step in.

 install_exception_hook[private]

Make sure our handler is the first of the hook predicate.

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.

 spy :Spec is det

 nospy :Spec is det

 nospyall is det

Set/clear spy-points. A successfully set or cleared spy-point is reported using print_message/2, level informational, with one of the following terms, where Spec is of the form M:Head.

• spy(Spec)
• nospy(Spec)

See also

- spy/1 and nospy/1 call the hook prolog:debug_control_hook/1 to allow for alternative specifications of the thing to debug.

 spy :Spec is det

 nospy :Spec is det

 nospyall is det

Set/clear spy-points. A successfully set or cleared spy-point is reported using print_message/2, level informational, with one of the following terms, where Spec is of the form M:Head.

• spy(Spec)
• nospy(Spec)

See also

- spy/1 and nospy/1 call the hook prolog:debug_control_hook/1 to allow for alternative specifications of the thing to debug.

 trap(+Formal) is det

 notrap(+Formal) is det

Install a trap on error(Formal, Context) exceptions that unify. The tracer is started when a matching exception is raised. This predicate enables debug mode using debug/0 to get more context about the exception. Even with debug mode disabled exceptions are still trapped and thus one may call nodebug/0 to run in normal mode after installing a trap. Exceptions are trapped in any thread. Debug mode is only enabled in the calling thread. To enable debug mode in all threads use tdebug/0.

Calling debugging/0 lists the enabled traps. The predicate notrap/1 removes matching (unifying) traps.

In many cases debugging an exception that is caught is as simple as below (assuming run/0 starts your program).

?- trap(_).
?- run.

The multifile hook trap_alias/2 allow for defining short hands for commonly used traps. Currently this defines

det

Trap determinism exceptions raised as a result of the det/1 directive.

=>

Trap rule existence error exceptions.

See also

- gtrap/1 to trap using the graphical debugger.

- Edit exceptions menu in PceEmacs and the graphical debugger that provide a graphical frontend to trap exceptions.