next prev up top content index

11 The Built-In Classes

Conditions

Conditions are used to describe and signal exceptional situations.

Figure 11-6 shows the built-in condition classes and some of their characteristics.

Figure 11-6 The Condition Classes

Condition Class Hierarchy
S – Sealed P – Primary C – Concrete I – Instantiable
O – Open F – Free A – Abstract U – Uninstantiable

General Conditions

<condition> [Open Abstract Class]


The class of objects used by the condition system to connect a signaler with an appropriate handler.

Superclasses:

<object>

Init-keywords:

None.

Description:

The class of condition objects. A complete description of conditions is given in Chapter 7, "Conditions."

Operations:

The class <condition> provides the following operations:

Table 11-68 Functions on <condition>

Function

Description

Page

signal

Signals a condition.

357

error

Signals a nonrecoverable error.

358

cerror

Signals a correctable error.

359

break

Invokes the debugger.

359

Table 11-69 Generic functions on <condition>

Function

Description

Page

default-handler

Called if no dynamic handler handles a condition.

361

return-query

Queries the user for values to return.

362

return-allowed?

Returns true if a condition's recovery protocol allows returning values.

363

return-description

Returns a description of a condition's returned values.

363

Table 11-70 Methods on <condition>

Function

Description

Page

default-handler

Called if no dynamic handler handles a condition.

361

Serious Conditions

<serious-condition> [Open Abstract Class]


The class of conditions that cannot safely be ignored.

Superclasses:

<condition>

Init-keywords:

None.

Description:

The class of conditions that cannot safely be ignored.

Operations:

The following operation is defined on <serious-condition>:

Table 11-71 Methods on <serious-condition>

Function

Description

Page

default-handler

Called if no dynamic handler handles a condition.

361

Errors

<error> [Open Abstract Class]


The class of conditions that represent something invalid about the program.

Superclasses:

<serious-condition>

Init-keywords:

None.

Description:

The class of serious conditions that represent program errors.

<error> is distinct from <serious-condition> so one can establish a handler for errors that does not also trap unpredictable environmental exceptions such as network problems.

Operations:

None.

<simple-error> [Sealed Instantiable Class]


The class of error conditions that consist of just an error message constructed from a format string and arguments.

Superclasses:

<error>

Init-keywords:

format-string:
An instance of <string>. A format string describing the error.

format-arguments:
An instance of <sequence>. Format arguments to splice into the format string to describe the error.

Description:

The class of error conditions that consist of just an error message constructed from a format string and arguments.

The recovery protocol of <simple-error> is empty.

Operations:

The class <simple-error> provides the following operations:

Table 11-72 Functions on <simple-error>

Function

Description

Page

condition-format-string

Returns the format string of a simple condition.

364

condition-format-arguments

Returns the format arguments of a simple condition.

364

<type-error> [Sealed Instantiable Class]


The class of error conditions generated by type checks.

Superclasses:

<error>

Init-keywords:

value: An instance of <object>. The object whose type was checked.

type:

An instance of <type>. The type that was expected. The error was signaled because the object was not of this type.

Description:

The class of errors indicating that an object was not of the expected type.

The recovery protocol is empty.

Operations:

The class <type-error> provides the following operations:

Table 11-73 Functions on <type-error>

Function

Description

Page

type-error-value

Returns the value that was not of the expected type.

365

type-error-expected-type

Returns the expected type of the type check that led to the type error.

365

<sealed-object-error> [Sealed Class]


The class of errors that are generated by sealing violations.

Superclasses:

<error>

Init-keywords:

None.

Description:

The class of errors that indicate the violation of a sealing restriction.

Operations:

None.

Warnings

<warning> [Open Abstract Class]


The class of conditions that are interesting to users but can safely be ignored.

Superclasses:

<condition>

Init-keywords:

None.

Operations:

The following operation is defined on <warning>:

Table 11-74 Methods on <warning>

Function

Description

Page

default-handler

Called if no dynamic handler handles a condition.

361

Description:

The class of conditions that can be safely ignored.

There is a default handler for <warning> that displays the warning in a user-interface dependent way and then returns #f. The recovery protocol is that any value can be returned and will be ignored.

<simple-warning> [Sealed Instantiable Class]


A default class of warnings that are described by a warning string.

Superclasses:

<warning>

Init-keywords:

format-string:
An instance of <string>. A format string describing the warning.

format-arguments:
An instance of <sequence>. Format arguments to splice into the format string to describe the warning.

Description:

The class of warnings described by a format string and arguments.

The recovery protocol is that any value can be returned and will be ignored.

Operations:

The class <simple-warning> provides the following operations:

Table 11-75 Functions on <simple-warning>

Function

Description

Page

condition-format-string

Returns the format string of a simple condition.

364

condition-format-arguments

Returns the format arguments of a simple condition.

364

Restarts

<restart> [Open Abstract Class]


The class of conditions used for restarting a computation.

Superclasses:

<condition>

Init-keywords:

condition: #f or an instance of <condition>. This argument is accepted and ignored by <restart>; some subclasses save the value of this initialization argument and use it to associate a restart with a particular condition from which the restart can recover. No such subclasses are defined as part of the language. Other restarts do not care; they can recover from any condition.

Description:

The class of conditions used to correct an unusual situation.

There is a default handler for <restart> that signals an error reporting an attempt to use a restart for which no restart handler was established. The recovery protocol concept is not applicable to restarts.

Operations:

The class <restart> provides the following operations:

Table 11-76 Generic functions on <restart>

Function

Description

Page

restart-query

Called to query the user and restart.

361

Table 11-77 Methods on <restart>

Function

Description

Page

default-handler

Called if no dynamic handler handles a condition.

361

<simple-restart> [Sealed Instantiable Class]


A default class of restarts.

Superclasses:

<restart>

Init-keywords:

format-string:
An instance of <string>. A format string describing the restart.

format-arguments:
An instance of <sequence>. Format arguments to splice into the format string to describe the restart.

Description:

A default class of restarts.

Typical implementations will use the format string and format arguments to produce a description of the restart.

Operations:

The class <simple-restart> provides the following operations:

Table 11-78 Functions on <simple-restart>

Function

Description

Page

condition-format-string

Returns the format string of a simple condition.

364

condition-format-arguments

Returns the format arguments of a simple condition.

364

Aborts

<abort> [Sealed Instantiable Class]


The class of conditions used to terminate a computation.

Superclasses:

<restart>

Init-keywords:

None.

Description:

The class of conditions used to terminate a computation.

Handlers are expected to terminate execution of the current application command, or similar unit of execution, and return control to something like an application command loop. This is comparable to command-period on the Macintosh. The exact details of this feature depend on the particular environment, of course, but signaling an instance of <abort> is a uniform way to "get out."

Operations:

None.