6.11.8.1 Exception Objects

When Guile encounters an exceptional situation, it raises an exception, where the exception is an object that describes the exceptional situation. Exception objects are structured data, built on the record facility (see Records).

Exception Type: &exception

The base exception type. All exception objects are composed of instances of subtypes of &exception.

Scheme Procedure: exception-type? obj

Return true if obj is an exception type.

Exception types exist in a hierarchy. New exception types can be defined using make-exception-type.

Scheme Procedure: make-exception-type id parent field-names

Return a new exception type named id, inheriting from parent, and with the fields whose names are listed in field-names. field-names must be a list of symbols and must not contain names already used by parent or one of its supertypes.

Exception type objects are record type objects, and as such, one can use record-constructor on an exception type to get its constructor. The constructor will take as many arguments as the exception has fields (including supertypes). See Records.

However, record-predicate and record-accessor aren’t usually what you want to use as exception type predicates and field accessors. The reason is, instances of exception types can be composed into compound exceptions. Exception accessors should pick out the specific component of a compound exception, and then access the field on that specific component.

Scheme Procedure: make-exception exceptions …

Return an exception object composed of exceptions.

Scheme Procedure: exception? obj

Return true if obj is an exception object.

Scheme Procedure: exception-predicate type

Return a procedure that will return true if its argument is a simple exception that is an instance of type, or a compound exception composed of such an instance.

Scheme Procedure: exception-accessor rtd proc

Return a procedure that will tail-call proc on an instance of the exception type rtd, or on the component of a compound exception that is an instance of rtd.

Compound exceptions are useful to separately express the different aspects of a situation. For example, compound exceptions allow a programmer to say that “this situation is a programming error, and also here’s a useful message to show to the user, and here are some relevant objects that can give more information about the error”. This error could be composed of instances of the &programming-error, &message, and &irritants exception types.

The subtyping relationship in exceptions is useful to let different-but-similar situations to be treated the same; for example there are many varieties of programming errors (for example, divide-by-zero or type mismatches), but perhaps there are common ways that the user would like to handle them all, and that common way might be different than how one might handle an error originating outside the program (for example, a file-not-found error).

The standard exception hierarchy in Guile takes its cues from R6RS, though the names of some of the types are different. See rnrs exceptions, for more details.

To have access to Guile’s exception type hierarchy, import the (ice-9 exceptions) module:

(use-modules (ice-9 exceptions))

The following diagram gives an overview of the standard exception type hierarchy.

&exception
|- &warning
|- &message
|- &irritants
|- &origin
\- &error
   |- &external-error
   \- &programming-error
      |- &assertion-failure
      |- &non-continuable
      |- &implementation-restriction
      |- &lexical
      |- &syntax
      \- &undefined-variable
Exception Type: &warning

An exception type denoting warnings. These are usually raised using #:continuable? #t; see the raise-exception documentation for more.

Scheme Procedure: make-warning
Scheme Procedure: warning? obj

Constructor and predicate for &warning exception objects.

Exception Type: &message message

An exception type that provides a message to display to the user. Usually used as a component of a compound exception.

Scheme Procedure: make-exception-with-message message
Scheme Procedure: exception-with-message? obj
Scheme Procedure: exception-message exn

Constructor, predicate, and accessor for &message exception objects.

Exception Type: &irritants irritants

An exception type that provides a list of objects that were unexpected in some way. Usually used as a component of a compound exception.

Scheme Procedure: make-exception-with-irritants irritants
Scheme Procedure: exception-with-irritants? obj
Scheme Procedure: exception-irritants exn

Constructor, predicate, and accessor for &irritants exception objects.

Exception Type: &origin origin

An exception type that indicates the origin of an exception, typically expressed as a procedure name, as a symbol. Usually used as a component of a compound exception.

Scheme Procedure: make-exception-with-origin origin
Scheme Procedure: exception-with-origin? obj
Scheme Procedure: exception-origin exn

Constructor, predicate, and accessor for &origin exception objects.

Exception Type: &error

An exception type denoting errors: situations that are not just exceptional, but wrong.

Scheme Procedure: make-error
Scheme Procedure: error? obj

Constructor and predicate for &error exception objects.

Exception Type: &external-error

An exception type denoting errors that proceed from the interaction of the program with the world, for example a “file not found” error.

Scheme Procedure: make-external-error
Scheme Procedure: external-error? obj

Constructor and predicate for &external-error exception objects.

Exception Type: &programming-error

An exception type denoting errors that proceed from inside a program: type mismatches and so on.

Scheme Procedure: make-programming-error
Scheme Procedure: programming-error? obj

Constructor and predicate for &programming-error exception objects.

Exception Type: &non-continuable

An exception type denoting errors that proceed from inside a program: type mismatches and so on.

Scheme Procedure: make-non-continuable-error
Scheme Procedure: non-continuable-error? obj

Constructor and predicate for &non-continuable exception objects.

Exception Type: &lexical

An exception type denoting lexical errors, for example unbalanced parentheses.

Scheme Procedure: make-lexical-error
Scheme Procedure: lexical-error? obj

Constructor and predicate for &lexical exception objects.

Exception Type: &syntax form subform

An exception type denoting syntax errors, for example a cond expression with invalid syntax. The form field indicates the form containing the error, and subform indicates the unexpected subcomponent, or #f if unavailable.

Scheme Procedure: make-syntax-error form subform
Scheme Procedure: syntax-error? obj
Scheme Procedure: syntax-error-form exn
Scheme Procedure: syntax-error-subform exn

Constructor, predicate, and accessors for &syntax exception objects.

Exception Type: &undefined-variable

An exception type denoting undefined variables.

Scheme Procedure: make-undefine-variable-error
Scheme Procedure: undefined-variable-error? obj

Constructor and predicate for &undefined-variable exception objects.

Incidentally, the (ice-9 exceptions) module also includes a define-exception-type macro that can be used to conveniently add new exception types to the hierarchy.

Syntax: define-exception-type name parent constructor predicate (field accessor) …

Define name to be a new exception type, inheriting from parent. Define constructor and predicate to be the exception constructor and predicate, respectively, and define an accessor for each field.