[Next] [Previous] [Up] [Top] [Contents] [Index]

12 The Built-In Functions

Operations on Conditions

Signaling Conditions

signal [Function]


Signals a condition.

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]


Signals a non-recoverable 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.

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 Þ 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} [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 Þ 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]


Called to query the user and return.

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]


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-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 which 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 which 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.


Dylan Reference Manual - 17 OCT 1995
[Next] [Previous] [Up] [Top] [Contents] [Index]

Generated with Harlequin WebMaker