REF CONDITIONS John Williams, Mar 1995 COPYRIGHT University of Sussex 1995. All Rights Reserved. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< CONDITIONS >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< This file briefly describes the functions, macros and variables documented in Chapter 29 of the standard Common Lisp guide, which is: Common Lisp: The Language, 2nd Edition (Guy L. Steele, Digital Press, 1990). --------------------------------------------- 1 Listing of Variables, Functions and Macros --------------------------------------------- *break-on-signals* [variable] When a condition is signaled with signal, the debugger is entered if (typep condition *break-on-signals*) is true. The initial value of *break-on-signals* is nil. *debugger-hook* [variable] Whenever the Lisp debugger is invoked by invoke-debugger, it first checks the value of *debugger-hook*. This variable should hold either nil or a function of two arguments, a condition and the value of *debugger-hook*. This function may either handle the condition (transfer control) or return normally (allowing the debugger to run). Note that, to minimize recursive errors while debugging, *debugger-hook* is bound to nil when calling this function. (abort &optional condition) [function] Invokes the most recently established restart named abort (and associated with condition, if supplied). Returns nil if no such restart exists. (arithmetic-error-operands condition) [function] (arithmetic-error-operation condition) [function] These functions access the operands and operator slots of condition (which should be of type arithmetic-error). (assert test-form [({place}*) [datum {argument}*]]) [macro] assert signals an error if the value of test-form is nil. Continuing from this error allows the user to alter the values of the generalized variables listed in {places}*, and assert will then start over, evaluating test-form again. The forms datum and {argument}* are used to construct the condition to be signaled if test-form evaluates to nil. If these arguments are not supplied, a condition of type simple-error is used. (break &optional format-string &rest format-arguments) [function] Invokes the Lisp debugger on a simple-condition created from format-string and format-arguments (which default to "" and nil respectively). A restart named continue is associated with this condition, which when invoked exits the debugger and returns from break with nil. (ccase keyplace {({({key}*) | key} {form}*)}*) [macro] Like case, except that a continuable error (of type simple-type-error) is signaled if keyplace is not eq to any of the specified key's. (cell-error-name condition) [function] Given a condition of type cell-error, returns the name of the offending cell. (cerror continue-format-string datum &rest arguments) [function] Like error, except that when the debugger is entered, a restart named continue is available which if invoked returns from the call of cerror with the value nil. continue-format-string is by the debugger to display the effect of invoking the continue restart. (check-type place type [string]) [macro] check-type signals an error (of type simple-type-error) if place does not conform to the type specification type. On continuing from this error with the continue restart, the user can specify a new value to be stored in place which is again checked for type conformity. string should be an English description of type. If string is not supplied it is computed automatically from type. check-type returns nil. (compute-restarts &optional condition) [function] If condition is supplied, returns a list of restarts currently associated with that condition. Otherwise returns a list of all currently active restarts. (continue &optional condition) [function] Invokes the most recently established restart named continue (and associated with condition, if supplied). Returns nil if no such restart exists. (ctypecase keyplace {(type {form}*)}*) [macro] Like typecase, except that a continuable error (of type simple-type-error) is signaled if the type of keyplace is not one of the specified type's. (define-condition name ({parent-type}*) [macro] [({slot-specifier}*) {(keyword value)}*]) For defining new sub-types of condition. The syntax of the lists {parent-type}* and {slot-specifier}* is the same as that of defclass. The possible keyword's are :documentation and :report. See Steele 1990 p899 for details of these. (ecase keyform {({({key}*) | key} {form}*)}*) [macro] Like case, except that a fatal error (of type simple-type-error) is signaled if keyform is not eq to any of the specified key's. (error datum &rest arguments) [function] Uses signal to signal an error, the precise condition type being determined by the values of datum and arguments. Unless the condition is handled specially, error's default behavior is to print a message describing the error condition on *error-output*, and then enter the debugger. (etypecase keyform {(type {form}*)}*) [macro] Like typecase, except that a fatal error (of type simple-type-error) is signaled if the type of keyform is not one of the specified type's. (file-error-pathname condition) [function] Returns the offending pathname from a condition of type file-error. (find-restart restart-identifier &optional condition) [function] Returns for the most recently established restart whose name is restart-identifier and that is associated with condition, if that argument is supplied. restart-identifier may be a restart object, in which case it is returned if it is a currently active restart. find-restart returns nil if it cannot locate an appropriate restart. (handler-bind ({(condition-type handler)}*) {form}*) [macro] Creates a table binding each condition-type to its handler function, and then executes {form}*. These bindings will be visible to calls of signal that occur during the execution of {form}*. (handler-case expression [macro] {(condition-type ([var]) {form}*)}* [:no-error (arglist) . body]) Syntactic sugar for handler-bind. First, for each condition-type, a handler function is created which if invoked will set var to the condition being signaled and then return the result(s) of executing {form}* from the handler-case form. Then, expression is executed. If a :no-error case is present, the results of executing expression are passed to the body of the :no-error form, as if by: (multiple-value-call #'(lambda (arglist) . body) expression) Assuming, of course, that none of the handler functions has been invoked and passed control out of the handler-case form. (ignore-errors {form}*) [macro] Executes {form}*. During execution, conditions of type error are handled by a function which exits from the ignore-errors form with two return values: nil and the error condition. Uses handler-bind. (invoke-debugger condition) [function] Invokes the Lisp debugger. (invoke-restart restart-identifier &rest arguments) [function] Invokes the restart identified by restart-identifier with arguments as arguments. Uses find-restart to locate the restart identified by restart-identifier. (invoke-restart-interactively restart-identifier) [function] Similar to invoke-restart, except that the :interactive function associated with restart-identifier is executed (if present). (make-condition type &rest slot-initializations) [function] Returns a condition object of the specified type, with the slots initialised from the given slot-initializations. (muffle-warning &optional condition) [function] Invokes the most recently established restart named muffle-warning (and associated with condition, if supplied). Returns nil if no such restart exists. (package-error-package condition) [function] Returns the offending package (or package name) involved in a condition of type package-error. (restart-bind ({(name function {keyword value}*)}*) [macro] {form}*) Creates a series of restart bindings, and then executes {form}*. Each restart has name name and when invoked by invoke-restart will execute function. The possible keyword's are :test-function, :interactive-function, and :report-function. See Steele 1990 p909-10 for details of these. (restart-case expression [macro] {(case-name arglist {keyword value}* {form}*)}*) Syntactic sugar for restart-bind. First, for each case-name a restart is created whose effect, if invoked, is to exit the restart-case form and return the result(s) of evaulating {form}*. Then, expression is executed. The variables in arglist are bound to the values passed to the restart by invoke-restart. The possible keyword's are: :test, :interactive and :report. See Steele 1990 p905-6 for details of these. (restart-name restart) [function] Returns the name of restart. (signal datum &rest arguments) [function] Constructs a condition object from datum and arguments, and then `signals' it, i.e. examines the handler bindings created by handler-bind and executes any handler functions associated with this condition. signal returns nil (unless a handler transfers control elsewhere). Note that if the condition is a member of the type denoted by *break-on-signals*, the debugger will be entered prior to beginning the process of signaling The condition to be signaled is constructed as follows: If datum is a condition, then that condition is used directly. If datum is a condition type (a class or class name), the condition used is: (apply #'make-condition datum arguments) Finally, if datum is a string, then the condition used is: (make-condition 'simple-error :format-string datum :format-arguments arguments) (simple-condition-format-arguments condition) [function] (simple-condition-format-string condition) [function] These functions access the format-arguments and format-string slots of condition (which should be of type simple-condition). (store-value value &optional condition) [function] Invokes the most recently established restart named store-value (and associated with condition, if supplied), with value as argument. Returns nil if no such restart exists. (stream-error-stream condition) [function] Returns the offending stream from a condition of type stream-error. (type-error-datum condition) [function] (type-error-expected-type condition) [function] These functions access the datum and expected-type slots of condition (which should be of type type-error). (use-value value &optional condition) [function] Invokes the most recently established restart named use-value (and associated with condition, if supplied), with value as argument. Returns nil if no such restart exists. (warn datum &rest arguments) [function] Uses signal to signal a warning, the precise condition type being determined by the values of datum and arguments. Unless the condition is handled specially, warn's default behavior is to print a message describing the condition on *error-output*, and then enter the debugger. (with-condition-restarts condition-form restarts-form [macro] {declaration}* {form}*) The value of condition-form should be a condition C and the value of restarts-form should be a list of restarts (R1 R2 ...). The forms of the body are evaluated as an implicit progn. While in the dynamic context of the body, an attempt to find a restart associated with a particular condition C' will consider the restarts R1, R2, ... if C' is eq to C. (with-simple-restart (name format-string {format-argument}*) [macro] {form}*) Creates a restart named name, and then executes {form}*. If, during execution, the restart named by name is invoked, execution of {form}* is terminated and the two values nil and t are returned from the with-simple-restart form. format-string and {format-argument}* are used to construct the :report function for the restart. --- C.all/lisp/ref/conditions --- Copyright University of Sussex 1995. All rights reserved.