9.3. Interfaces to Restarts [sec_9-1-4-2-2]

Macro RESTART-CASE. In (RESTART-CASE form {restart-clause}*), the argument list can also be specified after the keyword/value pairs instead of before them, i.e., each restart-clause can be either (restart-name EXT:*ARGS* {keyword-value-pair}* {form}*) or (restart-name {keyword-value-pair}* EXT:*ARGS* {form}*).

Macro EXT:WITH-RESTARTS. The macro EXT:WITH-RESTARTS is like RESTART-CASE, except that the forms are specified after the restart clauses instead of before them, and the restarts created are not implicitly associated with any CONDITION. (EXT:WITH-RESTARTS ({restart-clause}*) {form}*) is therefore equivalent to (RESTART-CASE (PROGN {form}*) {restart-clause}*).

Function COMPUTE-RESTARTSCOMPUTE-RESTARTS and FIND-RESTART behave as specified in [ANSI CL standard]: If the optional condition argument is non-NIL, only RESTARTs associated with that CONDITION and RESTARTs associated with no CONDITION at all are considered. Therefore the effect of associating a restart to a condition is not to activate it, but to hide it from other conditions. This makes the syntax-dependent implicit association performed by RESTART-CASE nearly obsolete.

Macro EXT:MUFFLE-CERRORS. The macro (EXT:MUFFLE-CERRORS {form}*) executes the forms; when a continuable ERROR occurs whose CONTINUE RESTART can be invoked non-interactively (this includes all continuable ERRORs signaled by the function CERROR), no message is printed, instead, the CONTINUE RESTART is invoked.

Macro EXT:APPEASE-CERRORS. The macro (EXT:APPEASE-CERRORS {form}*) executes the forms; when a continuable ERROR occurs whose CONTINUE RESTART can be invoked non-interactively (this includes all continuable ERRORs SIGNALed by the function CERROR), it is reported as a WARNING, and the CONTINUE RESTART is invoked.

Macro EXT:ABORT-ON-ERROR. The macro (EXT:ABORT-ON-ERROR {form}*) executes the forms; when an ERROR occurs, or when a Control+C interrupt occurs, the error message is printed and the ABORT RESTART is invoked.

Macro EXT:EXIT-ON-ERROR. The macro (EXT:EXIT-ON-ERROR {form}*) executes the forms; when an ERROR occurs, or when a Control+C interrupt occurs, the error message is printed and CLISP terminates with an error status.

Variable CUSTOM:*REPORT-ERROR-PRINT-BACKTRACE*. When this variable is non-NIL the error message printed by EXT:ABORT-ON-ERROR and EXT:EXIT-ON-ERROR includes the backtrace (stack).

Function EXT:SET-GLOBAL-HANDLER. The function (EXT:SET-GLOBAL-HANDLER condition handler) establishes a global handler for the condition. The handler should be FUNCALLable (a SYMBOL or a FUNCTION). If it returns, the next applicable handler is invoked, so if you do not want to land in the debugger, it should not return. E.g., the option -on-error abort and the macro EXT:ABORT-ON-ERROR are implemented by installing the following handler:

(defun sys::abortonerror (condition)
  (sys::report-error condition)
  (INVOKE-RESTART (FIND-RESTART 'ABORT condition)))

When handler is NIL, the handler for condition is removed and returned. When condition is also NIL, all global handlers are removed and returned as a LIST, which can then be passed to EXT:SET-GLOBAL-HANDLER as the first argument and the handlers re-established.

Macro EXT:WITHOUT-GLOBAL-HANDLERS. The macro (EXT:WITHOUT-GLOBAL-HANDLERS &BODY body) removes all global handlers by (EXT:SET-GLOBAL-HANDLER NIL NIL), executes body (where unhandled conditions now invoke the debugger), and then restores the handlers.


These notes document CLISP version 2.49Last modified: 2010-07-07