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).
The base exception type. All exception objects are composed of
instances of subtypes of &exception
.
Return true if obj is an exception type.
Exception types exist in a hierarchy. New exception types can be
defined using make-exception-type
.
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.
Return an exception object composed of exceptions.
Return true if obj is an exception object.
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.
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
An exception type denoting warnings. These are usually raised using
#:continuable? #t
; see the raise-exception
documentation
for more.
Constructor and predicate for &warning
exception objects.
An exception type that provides a message to display to the user. Usually used as a component of a compound exception.
Constructor, predicate, and accessor for &message
exception
objects.
An exception type that provides a list of objects that were unexpected in some way. Usually used as a component of a compound exception.
Constructor, predicate, and accessor for &irritants
exception
objects.
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.
Constructor, predicate, and accessor for &origin
exception
objects.
An exception type denoting errors: situations that are not just exceptional, but wrong.
Constructor and predicate for &error
exception objects.
An exception type denoting errors that proceed from the interaction of the program with the world, for example a “file not found” error.
Constructor and predicate for &external-error
exception objects.
An exception type denoting errors that proceed from inside a program: type mismatches and so on.
Constructor and predicate for &programming-error
exception
objects.
An exception type denoting errors that proceed from inside a program: type mismatches and so on.
Constructor and predicate for &non-continuable
exception objects.
An exception type denoting lexical errors, for example unbalanced parentheses.
Constructor and predicate for &lexical
exception objects.
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.
Constructor, predicate, and accessors for &syntax
exception
objects.
An exception type denoting undefined variables.
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.
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.