12 The Built-In Functions

Operations on Conditions

Signaling Conditions

signal [Function]

Signatures:

signal condition Þ values
signal string #rest arguments Þ values

Arguments (1):

condition An instance of <condition>.

Arguments (2):

string An instance of <string>.

arguments

Instances of <object>.

Values:

values Instance 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]

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]

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]

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.

check-type [Function]

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]

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]

Signature:

default-handler condition Þ 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]

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

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

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

restart-query [Open Generic Function]

Signature:

restart-query restart Þ 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. There is a default method for <restart> which does nothing.

return-query [Open Generic Function]

Signature:

return-query condition Þ 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 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.

Introspection on Conditions

do-handlers [Function]

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]

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-description [Open Generic Function]

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]

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]

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]

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 which was not of the expected type, and thereby led to the type error.

type-error-expected-type [Function]

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.

Generated with Harlequin WebMaker