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]
- 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,
signalcallsdefault-handler(condition). If a handler returns, all the values that it returned are returned fromsignal. Ifsignalreturns when condition's recovery protocol does not allow returning, some handler has violated protocol;signaldoes not check for this error. If condition is a restart, the caller ofsignalshould 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.
errorwill never return.- Description:
-
erroris similar tosignalbut never returns; if a handler returns,errorinvokes the debugger immediately.erroris 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]
- 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:
-
cerroris the same aserrorbut 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,
cerrorreturns#f; otherwise,cerrornever returns. Ifcerrorreturns, the program should take the corrective actions promised in the restart-description.cerroris the standard way to signal correctable errors when no special class of restart condition is required.
break [Function]
- 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
signalbut then invokes the debugger immediately without signaling first.breakestablishes a<simple-restart>so the debugger can continue execution. This is useful for breakpoints.breakalways 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.
abortwill never return.- Description:
-
Performs
error(make (<abort>)).This function is provided as a convenient shortcut. The call is to
error, rather than tosignal, to guarantee thatabortwill 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-handlercondition ⇒ false [G.F. Method]A predefined method on
<condition>simply returns#f.default-handlerserious-condition ⇒ {does not return} [G.F. Method]A predefined method on
<serious-condition>invokes an implementation-defined debugger.default-handlerwarning ⇒ false [G.F. Method]A predefined method on
<warning>prints the warning's message in an implementation-defined way and then returns#f.default-handlerrestart ⇒ {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-queryrestart ⇒ 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-queryshould not be called ifreturn-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
#tif the recovery protocol of condition allows returning values, or#fif 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
-
#for an instance of<string>or an instance of<restart>.
- Description:
-
If the recovery protocol of this condition allows returning values,
return-descriptionreturns a description of the meaning of returning values.This description can be a restart, a string, or
#f.return-descriptionshould not be called ifreturn-allowed?returns#f. If you define your own condition class whose recovery protocol allows returning values, you need to define a method forreturn-descriptionunless 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.