Warning: This is the manual of the legacy Guile 2.2 series. You may want to read the manual of the current stable series instead.

6.26.3.3 Pre-Unwind Debugging

Instead of saving a stack away and waiting for the catch to return, you can handle errors directly, from within the pre-unwind handler.

For example, to show a backtrace when an error is thrown, you might want to use a procedure like this:

(define (with-backtrace thunk)
  (with-throw-handler #t
                      thunk
                      (lambda args (backtrace))))
(with-backtrace (lambda () (error "Not a vegetable: tomato")))

Since we used with-throw-handler here, we didn’t actually catch the error. See Throw Handlers, for more information. However, we did print out a context at the time of the error, using the built-in procedure, backtrace.

Scheme Procedure: backtrace [highlights]

C Function: scm_backtrace_with_highlights (highlights)

C Function: scm_backtrace ()

Display a backtrace of the current stack to the current output port. If highlights is given it should be a list; the elements of this list will be highlighted wherever they appear in the backtrace.

The Guile REPL code (in system/repl/repl.scm and related files) uses a catch with a pre-unwind handler to capture the stack when an error occurs in an expression that was typed into the REPL, and debug that stack interactively in the context of the error.

These procedures are available for use by user programs, in the (system repl error-handling) module.

(use-modules (system repl error-handling))

Scheme Procedure: call-with-error-handling thunk [#:on-error on-error='debug] [#:post-error post-error='catch] [#:pass-keys pass-keys='(quit)] [#:report-keys report-keys='(stack-overflow)] [#:trap-handler trap-handler='debug]

Call a thunk in a context in which errors are handled.

There are five keyword arguments:

on-error

Specifies what to do before the stack is unwound.

Valid options are debug (the default), which will enter a debugger; pass, in which case nothing is done, and the exception is rethrown; or a procedure, which will be the pre-unwind handler.

post-error

Specifies what to do after the stack is unwound.

Valid options are catch (the default), which will silently catch errors, returning the unspecified value; report, which prints out a description of the error (via display-error), and then returns the unspecified value; or a procedure, which will be the catch handler.

trap-handler

Specifies a trap handler: what to do when a breakpoint is hit.

Valid options are debug, which will enter the debugger; pass, which does nothing; or disabled, which disables traps entirely. See Traps, for more information.

pass-keys

A set of keys to ignore, as a list.

report-keys

A set of keys to always report even if the post-error handler is catch, as a list.