Chapter 12

The Built-In Functions


Operations on Conditions

The following functions are used to create, signal, handle, and examine conditions.

Signaling Conditions

signal [Function]


Signals a condition.

Signatures:

signal condition #rest values
signal string #rest arguments #rest values

Arguments (1):
condition

An instance of <condition>.

Arguments (2):
string

An instance of <string>.

arguments

Instances of <object>.

Values:
values

Instances of <object>.

Description:

Signals the condition, trying each active dynamic handler, the most recent first. If all dynamic handlers decline, signal calls default-handler(condition). If a handler returns, all the values that it returned are returned from signal. If signal returns when condition's recovery protocol does not allow returning, some handler has violated protocol; signal does not check for this error. If condition is a restart, the caller of signal should always assume that it might return.

The second form signals a condition of type <simple-warning>.

error [Function]


Signals a nonrecoverable error.

Signatures:

error condition {will never return}
error string #rest arguments {will never return}

Arguments (1):
condition

An instance of <condition>.

Arguments (2):
string

An instance of <string>.

arguments

Instances of <object>.

Values:

None. error will never return.

Description:

error is similar to signal but never returns; if a handler returns, error invokes the debugger immediately. error is used to make it clear that a program does not expect to receive control again after signaling a condition and might enable the compiler to generate slightly more compact code.

The second form signals a condition of type <simple-error>.

cerror [Function]


Signals a correctable error.

Signatures:

cerror restart-description condition false
cerror restart-description string #rest arguments false

Arguments (1):
restart-description

An instance of <string>, interpreted as a format string.

condition

An instance of <condition>.

Arguments (2):
restart-description

An instance of <string>, interpreted as a format string.

string

An instance of <string>.

arguments

Instances of <object>.

Values:
false

#f.

Description:

cerror is the same as error but first establishes a handler for <simple-restart>, with a format string of restart-description and format arguments of a sequence containing the arguments.

If the restart handler is invoked, cerror returns #f; otherwise, cerror never returns. If cerror returns, the program should take the corrective actions promised in the restart-description. cerror is the standard way to signal correctable errors when no special class of restart condition is required.

break [Function]


Invokes the debugger.

Signatures:

break condition false
break string #rest arguments false
break false

Arguments (1):
condition

An instance of <condition>.

Arguments (2):
string

An instance of <string>, interpreted as a format string.

arguments

Instances of <object>, interpreted as format arguments.

Arguments (3):

None.

Values:
false

#f.

Description:

Obtains a condition in the same way as signal but then invokes the debugger immediately without signaling first. break establishes a <simple-restart> so the debugger can continue execution. This is useful for breakpoints. break always returns #f. With no arguments, a default message string is used.

The behavior of the debugger is implementation-defined.

check-type [Function]


Checks an object to ensure that it is an instance of a specified type.

Signature:

check-type value type value

Arguments:
value

An instance of <object>.

type

An instance of <type>.

Values:
value

An instance of <object>.

Description:

Checks value to ensure that it is an instance of type, and signal an error of type <type-error> if it is not.

abort [Function]


Aborts and never returns.

Signature:

abort

Arguments:

None.

Values:

None. abort will never return.

Description:

Performs error(make (<abort>)).

This function is provided as a convenient shortcut. The call is to error, rather than to signal, to guarantee that abort will never return.

Handling Conditions

default-handler [Open Generic Function]


Called if no dynamic handler handles a condition.

Signature:

default-handler condition #rest values

Arguments:
condition

An instance of <condition>.

Values:
values

Instances of <object>.

Description:

Called if no dynamic handler handles a condition.

default-handler condition ⇒ false [G.F. Method]

A predefined method on <condition> simply returns #f.

default-handler serious-condition{does not return} [G.F. Method]

A predefined method on <serious-condition> invokes an implementation-defined debugger.

default-handler warning ⇒ false [G.F. Method]

A predefined method on <warning> prints the warning's message in an implementation-defined way and then returns #f.

default-handler restart{does not return} [Sealed G.F. Method]

A predefined method on <restart> signals an error.

restart-query [Open Generic Function]


Called to query the user and restart.

Signature:

restart-query restart #rest values

Arguments:
restart

An instance of <restart>.

Values:
values

Instances of <object>.

Description:

Engages the interactive user in a dialog and stores the results in slots of restart.

This function is designed to be called from a handler, after making a restart and before signaling it. The debugger uses restart-query, for example.

restart-query restart ⇒ object [G.F. Method]

There is a default method for <restart> that does nothing.

return-query [Open Generic Function]


Queries the user for values to return.

Signature:

return-query condition #rest values

Arguments:
condition

An instance of <condition>.

Values:
values

Instances of <object>.

Description:

If the recovery protocol of condition allows returning values, this engages the program user in a dialog and returns the results as any number of values, which the handler should return.

return-query should not be called if return-allowed? returns #f. Programs that define condition classes whose recovery protocol allows returning values should ensure that there is an appropriate method for this function defined on or inherited by the condition class.

Introspection on Conditions

do-handlers [Function]


Applies a function to all dynamically active handlers.

Signature:

do-handlers function false

Arguments:
function

An instance of <function>.

Values:
false

#f.

Description:

Applies function to all dynamically active handlers, the most recently established first. function receives four arguments: type, test, function, and init-arguments. The arguments describe a dynamically active handler. All arguments have dynamic extent and must not be modified. test defaults to a function that always returns #t. init-arguments will be an empty sequence if it was not supplied by the handler.

return-allowed? [Open Generic Function]


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

Signature:

return-allowed? condition boolean

Arguments:
condition

An instance of <condition>.

Values:
boolean

An instance of <boolean>.

Description:

Returns #t if the recovery protocol of condition allows returning values, or #f if it does not.

There is a default method for <condition> that returns #f. Programs which define condition classes whose recovery protocol allows returning values should ensure that there is an appropriate method for this function defined on or inherited by the condition class.

return-allowed? condition ⇒ false [G.F. Method]

There is a default method for <condition> that returns #f.

return-description [Open Generic Function]


Returns a description of a condition's returned values.

Signature:

return-description condition description

Arguments:
condition

An instance of <condition>.

Values:
description

#f or an instance of <string> or an instance of <restart>.

Description:

If the recovery protocol of this condition allows returning values, return-description returns a description of the meaning of returning values.

This description can be a restart, a string, or #f. return-description should not be called if return-allowed? returns #f. If you define your own condition class whose recovery protocol allows returning values, you need to define a method for return-description unless the inherited method is suitable.

condition-format-string [Function]


Returns the format string of a simple condition.

Signature:

condition-format-string simple-condition format-string

Arguments:
simple-condition

An instance of <simple-error>, <simple-warning>, or <simple-restart>.

Values:
format-string

An instance of <string>.

Description:

Returns the format string that was supplied as an initialization argument when the simple-condition was created.

condition-format-arguments [Function]


Returns the format arguments of a simple condition.

Signature:

condition-format-arguments simple-condition format-args

Arguments:
simple-condition

An instance of <simple-error>, <simple-warning>, or <simple-restart>.

Values:
format-args

An instance of <sequence>.

Description:

Returns the sequence of format arguments that was supplied as an initialization argument when the simple-condition was created.

type-error-value [Function]


Returns the value that was not of the expected type.

Signature:

type-error-value type-error object

Arguments:
type-error

An instance of <type-error>.

Values:
object

An instance of <object>.

Description:

Returns the value that was not of the expected type, and thereby led to the type error.

type-error-expected-type [Function]


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

Signature:

type-error-expected-type type-error type

Arguments:
type-error

An instance of <type-error>.

Values:
type

An instance of <type>.

Description:

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