24.1. General Error-Signaling Functions

The functions in this section provide various mechanisms for signaling warnings, breaks, continuable errors, and fatal errors.

In each case, the caller specifies an error message (a string) that may be processed (and perhaps displayed to the user) by the error-handling mechanism. All messages are constructed by applying the function format to the quantities nil, format-string, and all the args to produce a string.

An error message string should not contain a newline character at either the beginning or end, and should not contain any sort of herald indicating that it is an error. The system will take care of these according to whatever its preferred style may be.

Conventionally, error messages are complete English sentences ending with a period. Newlines in the middle of long messages are acceptable. There should be no indentation after a newline in the middle of an error message. The error message need not mention the name of the function that signals the error; it is assumed that the debugger will make this information available.

Implementation note: If the debugger in a particular implementation displays error messages indented from the prevailing left margin (for example, indented by seven spaces because they are prefixed by the seven-character herald ``Error: ''), then the debugger should take care of inserting the appropriate indentation into a multi-line error message. Similarly, a debugger that prefixes error messages with semicolons so that they appear to be comments should take care of inserting a semicolon at the beginning of each line in a multi-line error message. These rules are suggested because, even within a single implementation, there may be more than one program that presents error messages to the user, and they may use different styles of presentation. The caller of error cannot anticipate all such possible styles, and so it is incumbent upon the presenter of the message to make any necessary adjustments.

Common Lisp does not specify the manner in which error messages and other messages are displayed. For the purposes of exposition, a fairly simple style of textual presentation will be used in the examples in this chapter. The character > is used to represent the command prompt symbol for a debugger.

[Function]
error format-string &rest args

old_change_begin
This function signals a fatal error. It is impossible to continue from this kind of error; thus error will never return to its caller.

The debugger printout in the following example is typical of what an implementation might print when error is called. Suppose that the (misspelled) symbol emergnecy-shutdown has no property named command (all too likely, as it is probably a typographical error for emergency-shutdown).

(defun command-dispatch (cmd) 
  (let ((fn (get cmd 'command))) 
    (if (not (null fn)) 
        (funcall fn)) 
        (error "The command ~S is unrecognized." cmd)))) 

(command-dispatch 'emergnecy-shutdown) 
Error: The command EMERGNECY-SHUTDOWN is unrecognized. 
Error signaled by function COMMAND-DISPATCH. 
>

old_change_end

change_begin
X3J13 voted in June 1988 (CONDITION-SYSTEM) to adopt a proposal for a Common Lisp Condition System. This proposal modifies the definition of error to specify its interaction with the condition system. See section 29.4.1.
change_end

Compatibility note: Lisp Machine Lisp calls this function ferror. MacLisp has a function named error that takes different arguments and can signal either a fatal or a continuable error.

[Function]
cerror continue-format-string error-format-string &rest args

old_change_begin
cerror is used to signal continuable errors. Like error, it signals an error and enters the debugger. However, cerror allows the program to be continued from the debugger after resolving the error.

If the program is continued after encountering the error, cerror returns nil. The code that follows the call to cerror will then be executed. This code should correct the problem, perhaps by accepting a new value from the user if a variable was invalid.

If the code that corrects the problem interacts with the program's use and might possibly be misled, it should make sure the error has really been corrected before continuing. One way to do this is to put the call to cerror and the correction code in a loop, checking each time to see if the error has been corrected before terminating the loop.

The continue-format-string argument, like the error-format-string argument, is given as a control string to format along with the args to construct a message string. The error message string is used in the same way that error uses it. The continue message string should describe the effect of continuing. The intent is that this message can be displayed as an aid to the user in deciding whether and how to continue. For example, it might be used by an interactive debugger as part of the documentation of its ``continue'' command.

The content of the continue message should adhere to the rules of style for error messages. It should not include any statement of how the ``continue'' command is given, since this may be different for each debugger. (It is up to the debugger to supply this information according to its own particular style of presentation and user interaction.)
old_change_end

change_begin
X3J13 voted in June 1988 (CONDITION-SYSTEM) to adopt a proposal for a Common Lisp Condition System. This proposal modifies the definition of cerror to specify its interaction with the condition system. See section 29.4.1.
change_end

Here is an example where the caller of cerror, if continued, fixes the problem without any further user interaction:

(let ((nvals (list-length vals))) 
  (unless (= nvals 3) 
    (cond ((< nvals 3) 
           (cerror "Assume missing values are zero." 
                   "Too few values in ~S;~%~ 
                    three are required, ~ 
                    but ~R ~:[were~;was~] supplied." 
                   nvals (= nvals 1)) 
           (setq vals (append vals (subseq '(0 0 0) nvals)))) 
          (t (cerror "Ignore all values after the first three." 
                     "Too many values in ~S;~%~ 
                      three are required, ~ 
                      but ~R were supplied." 
                      nvals) 
             (setq vals (subseq vals 0 3))))))

If vals were the list (-47), the interaction might look like this:

Error: Too few values in (-47); 
       three are required, but one was supplied. 
Error signaled by function EXAMPLE. 
If continued: Assume missing values are zero. 
>

In this example, a loop is used to ensure that a test is satisfied. (This example could be written more succinctly using assert or check-type, which indeed supply such loops.)

(do () 
    ((known-wordp word) word) 
  (cerror "You will be prompted for a replacement word." 
          "~S is an unknown word (possibly misspelled)." 
          word) 
  (format *query-io* "~&New word: ") 
  (setq word (read *query-io*)))

In complex cases where the error-format-string uses some of the args and the continue-format-string uses others, it may be necessary to use the format directives ~* and ~@* to skip over unwanted arguments in one or both of the format control strings.

Compatibility note: The Lisp Machine Lisp function fsignal is similar to this, but returns :no-action rather than nil, and fails to distinguish between the error message and the continue message.

[Function]
warn format-string &rest args

old_change_begin
warn prints an error message but normally doesn't go into the debugger. (However, this may be controlled by the variable *break-on-warnings*.)
old_change_end

change_begin
X3J13 voted in March 1989 (BREAK-ON-WARNINGS-OBSOLETE) to remove *break-on-warnings* from the language. See *break-on-signals*.
change_end

old_change_begin
warn returns nil.

This function would be just the same as format with the output directed to the stream in error-output, except that warn may perform various implementation-dependent formatting and other actions. For example, an implementation of warn should take care of advancing to a fresh line before and after the error message and perhaps supplying the name of the function that called warn.
old_change_end

Compatibility note: The Lisp Machine Lisp function compiler:warn is an approximate equivalent to this.

change_begin
X3J13 voted in June 1988 (CONDITION-SYSTEM) to adopt a proposal for a Common Lisp Condition System. This proposal modifies the definition of warn to specify its interaction with the condition system. See section 29.4.9.
change_end

old_change_begin

[Variable]
*break-on-warnings*

If *break-on-warnings* is not nil, then the function warn behaves like break. It prints its message and then goes to the debugger or break loop. Continuing causes warn to return nil. This flag is intended primarily for use when the user is debugging programs that issue warnings; in ``production'' use, the value of *break-on-warnings* should be nil.
old_change_end

change_begin
X3J13 voted in March 1989 (BREAK-ON-WARNINGS-OBSOLETE) to remove *break-on-warnings* from the language. See *break-on-signals*.
change_end

[Function]
break &optional format-string &rest args

old_change_begin
break prints the message and goes directly into the debugger, without allowing any possibility of interception by programmed error-handling facilities. (Right now, there aren't any error-handling facilities defined in Common Lisp, but there might be in particular implementations, and there will be some defined by Common Lisp in the future.) When continued, break returns nil. It is permissible to call break with no arguments; a suitable default message will be provided.

break is presumed to be used as a way of inserting temporary debugging ``breakpoints'' in a program, not as a way of signaling errors; it is expected that continuing from a break will not trigger any unusual recovery action. For this reason, break does not take the additional format control string argument that cerror takes. This and the lack of any possibility of interception by programmed error handling are the only program-visible differences between break and cerror. The interactive debugger may choose to display them differently; for instance, a cerror message might be prefixed with the herald ``Error: '' and a break message with ``Break: ''. This depends on the user-interface style of the particular implementation. A particular implementation may choose, according to its own style and needs, when break is called to go into a debugger different from the one used for handling errors. For example, it might go into an ordinary read-eval-print loop identical to the top-level one except for the provision of a ``continue'' command that causes break to return nil.
old_change_end

Compatibility note: In MacLisp, break is a special form (FEXPR) that takes two optional arguments. The first is a symbol (it would be a string if MacLisp had strings), which is not evaluated. The second is evaluated to produce a truth value specifying whether break should break (true) or return immediately (false). In Common Lisp one makes a call to break conditional by putting it inside a conditional form such as when or unless.

change_begin
X3J13 voted in June 1988 (CONDITION-SYSTEM) to adopt a proposal for a Common Lisp Condition System. This proposal modifies the definition of break to specify its interaction with the condition system. See section 29.4.11.
change_end

Next: Specialized Error-Signaling Forms Up: Errors Previous: Errors

AI.Repository@cs.cmu.edu