7.6.2.12 rnrs exceptions

The (rnrs exceptions (6)) library provides functionality related to signaling and handling exceptional situations. This functionality is similar to the exception handling systems provided by Guile’s core library See section Exceptions, and by the SRFI-18 and SRFI-34 modules—See section SRFI-18 Exceptions, and SRFI-34 - Exception handling for programs, respectively—but there are some key differences in concepts and behavior.

A raised exception may be continuable or non-continuable. When an exception is raised non-continuably, another exception, with the condition type &non-continuable, will be raised when the exception handler returns locally. Raising an exception continuably captures the current continuation and invokes it after a local return from the exception handler.

Like SRFI-18 and SRFI-34, R6RS exceptions are implemented on top of Guile’s native throw and catch forms, and use custom “throw keys” to identify their exception types. As a consequence, Guile’s catch form can handle exceptions thrown by these APIs, but the reverse is not true: Handlers registered by the with-exception-handler procedure described below will only be called on exceptions thrown by the corresponding raise procedure.

Scheme Procedure: with-exception-handler handler thunk

Installs handler, which must be a procedure taking one argument, as the current exception handler during the invocation of thunk, a procedure taking zero arguments. The handler in place at the time with-exception-handler is called is made current again once either thunk returns or handler is invoked after an exception is thrown from within thunk.

This procedure is similar to the with-throw-handler procedure provided by Guile’s code library; (see section Throw Handlers).

Scheme Syntax: guard (variable clause1 clause2 ...) body

Evaluates the expression given by body, first creating an ad hoc exception handler that binds a raised exception to variable and then evaluates the specified clauses as if they were part of a cond expression, with the value of the first matching clause becoming the value of the guard expression (see section Simple Conditional Evaluation). If none of the clause’s test expressions evaluates to #t, the exception is re-raised, with the exception handler that was current before the evaluation of the guard form.

For example, the expression

(guard (ex ((eq? ex 'foo) 'bar) ((eq? ex 'bar) 'baz)) 
  (raise 'bar))

evaluates to baz.

Scheme Procedure: raise obj

Raises a non-continuable exception by invoking the currently-installed exception handler on obj. If the handler returns, a &non-continuable exception will be raised in the dynamic context in which the handler was installed.

Scheme Procedure: raise-continuable obj

Raises a continuable exception by invoking currently-installed exception handler on obj.

This document was generated on April 20, 2013 using texi2html 5.0.