Most errors are signaled "automatically" within Lisp primitives
which you call for other purposes, such as if you try to take the CAR
of an integer or move forward a character at the end of the buffer; you
-can also signal errors explicitly with the functions `error' and
-`signal'.
+can also signal errors explicitly with the functions `error', `signal',
+and others.
Quitting, which happens when the user types `C-g', is not considered
an error, but it is handled almost like an error. *Note Quitting::.
applying `format' (*note String Conversion::) to FORMAT-STRING and
ARGS.
+ This error is not continuable: you cannot continue execution after
+ the error using the debugger `r' or `c' commands. If you wish the
+ user to be able to continue execution, use `cerror' or `signal'
+ instead.
+
These examples show typical uses of `error':
(error "You have committed an error.
`error' works by calling `signal' with two arguments: the error
symbol `error', and a list containing the string returned by
- `format'.
+ `format'. This is repeated in an endless loop, to ensure that
+ `error' never returns.
If you want to use your own string as an error message verbatim,
don't just write `(error STRING)'. If STRING contains `%', it
will be interpreted as a format specifier, with undesirable
results. Instead, use `(error "%s" STRING)'.
+ - Function: cerror format-string &rest args
+ This function behaves like `error', except that the error it
+ signals is continuable. That means that debugger commands `c' and
+ `r' can resume execution.
+
- Function: signal error-symbol data
- This function signals an error named by ERROR-SYMBOL. The
- argument DATA is a list of additional Lisp objects relevant to the
- circumstances of the error.
+ This function signals a continuable error named by ERROR-SYMBOL.
+ The argument DATA is a list of additional Lisp objects relevant to
+ the circumstances of the error.
The argument ERROR-SYMBOL must be an "error symbol"--a symbol
bearing a property `error-conditions' whose value is a list of
sorts of errors.
The number and significance of the objects in DATA depends on
- ERROR-SYMBOL. For example, with a `wrong-type-arg' error, there
- are two objects in the list: a predicate that describes the type
- that was expected, and the object that failed to fit that type.
- *Note Error Symbols::, for a description of error symbols.
+ ERROR-SYMBOL. For example, with a `wrong-type-argument' error,
+ there are two objects in the list: a predicate that describes the
+ type that was expected, and the object that failed to fit that
+ type. *Note Error Symbols::, for a description of error symbols.
Both ERROR-SYMBOL and DATA are available to any error handlers
that handle the error: `condition-case' binds a local variable to
Errors::). If the error is not handled, these two values are used
in printing the error message.
- The function `signal' never returns (though in older Emacs versions
- it could sometimes return).
+ The function `signal' can return, if the debugger is invoked and
+ the user invokes the "return from signal" option. If you want the
+ error not to be continuable, use `signal-error' instead. Note that
+ in FSF Emacs `signal' never returns.
(signal 'wrong-number-of-arguments '(x y))
error--> Wrong number of arguments: x, y
- (signal 'no-such-error '("My unknown error condition."))
- error--> peculiar error: "My unknown error condition."
+ (signal 'no-such-error '("My unknown error condition"))
+ error--> Peculiar error (no-such-error "My unknown error condition")
+
+ - Function: signal-error error-symbol data
+ This function behaves like `signal', except that the error it
+ signals is not continuable.
+
+ - Macro: check-argument-type predicate argument
+ This macro checks that ARGUMENT satisfies PREDICATE. If that is
+ not the case, it signals a continuable `wrong-type-argument' error
+ until the returned value satisfies PREDICATE, and assigns the
+ returned value to ARGUMENT. In other words, execution of the
+ program will not continue until PREDICATE is met.
+
+ ARGUMENT is not evaluated, and should be a symbol. PREDICATE is
+ evaluated, and should name a function.
- Common Lisp note: XEmacs Lisp has nothing like the Common Lisp
- concept of continuable errors.
+ As shown in the following example, `check-argument-type' is useful
+ in low-level code that attempts to ensure the sanity of its data
+ before proceeding.
+
+ (defun cache-object-internal (object wlist)
+ ;; Before doing anything, make sure that WLIST is indeed
+ ;; a weak list, which is what we expect.
+ (check-argument-type 'weak-list-p wlist)
+ ...)
\1f
File: lispref.info, Node: Processing of Errors, Next: Handling Errors, Prev: Signaling Errors, Up: Errors
command loop's handler uses the error symbol and associated data to
print an error message.
+ Errors in command loop are processed using the `command-error'
+function, which takes care of some necessary cleanup, and prints a
+formatted error message to the echo area. The functions that do the
+formatting are explained below.
+
+ - Function: display-error error-object stream
+ This function displays ERROR-OBJECT on STREAM. ERROR-OBJECT is a
+ cons of error type, a symbol, and error arguments, a list. If the
+ error type symbol of one of its error condition superclasses has
+ an `display-error' property, that function is invoked for printing
+ the actual error message. Otherwise, the error is printed as
+ `Error: arg1, arg2, ...'.
+
+ - Function: error-message-string error-object
+ This function converts ERROR-OBJECT to an error message string,
+ and returns it. The message is equivalent to the one that would be
+ printed by `display-error', except that it is conveniently returned
+ in string form.
+
An error that has no explicit handler may call the Lisp debugger.
The debugger is enabled if the variable `debug-on-error' (*note Error
Debugging::) is non-`nil'. Unlike error handlers, the debugger runs in
is also used to trap errors that are totally unpredictable, such as
when the program evaluates an expression read from the user.
+ Even when an error is handled, the debugger may still be called if
+the variable `debug-on-signal' (*note Error Debugging::) is non-`nil'.
+Note that this may yield unpredictable results with code that traps
+expected errors as normal part of its operation. Do not set
+`debug-on-signal' unless you know what you are doing.
+
Error signaling and handling have some resemblance to `throw' and
`catch', but they are entirely separate facilities. An error cannot be
caught by a `catch', and a `throw' cannot be handled by an error
-| The error was: (error "Rats! The variable baz was 34, not 35")
=> 2
-\1f
-File: lispref.info, Node: Error Symbols, Prev: Handling Errors, Up: Errors
-
-Error Symbols and Condition Names
-.................................
-
- When you signal an error, you specify an "error symbol" to specify
-the kind of error you have in mind. Each error has one and only one
-error symbol to categorize it. This is the finest classification of
-errors defined by the XEmacs Lisp language.
-
- These narrow classifications are grouped into a hierarchy of wider
-classes called "error conditions", identified by "condition names".
-The narrowest such classes belong to the error symbols themselves: each
-error symbol is also a condition name. There are also condition names
-for more extensive classes, up to the condition name `error' which
-takes in all kinds of errors. Thus, each error has one or more
-condition names: `error', the error symbol if that is distinct from
-`error', and perhaps some intermediate classifications.
-
- In order for a symbol to be an error symbol, it must have an
-`error-conditions' property which gives a list of condition names.
-This list defines the conditions that this kind of error belongs to.
-(The error symbol itself, and the symbol `error', should always be
-members of this list.) Thus, the hierarchy of condition names is
-defined by the `error-conditions' properties of the error symbols.
-
- In addition to the `error-conditions' list, the error symbol should
-have an `error-message' property whose value is a string to be printed
-when that error is signaled but not handled. If the `error-message'
-property exists, but is not a string, the error message `peculiar
-error' is used.
-
- Here is how we define a new error symbol, `new-error':
-
- (put 'new-error
- 'error-conditions
- '(error my-own-errors new-error))
- => (error my-own-errors new-error)
- (put 'new-error 'error-message "A new error")
- => "A new error"
-
-This error has three condition names: `new-error', the narrowest
-classification; `my-own-errors', which we imagine is a wider
-classification; and `error', which is the widest of all.
-
- The error string should start with a capital letter but it should
-not end with a period. This is for consistency with the rest of Emacs.
-
- Naturally, XEmacs will never signal `new-error' on its own; only an
-explicit call to `signal' (*note Signaling Errors::) in your code can
-do this:
-
- (signal 'new-error '(x y))
- error--> A new error: x, y
-
- This error can be handled through any of the three condition names.
-This example handles `new-error' and any other errors in the class
-`my-own-errors':
-
- (condition-case foo
- (bar nil t)
- (my-own-errors nil))
-
- The significant way that errors are classified is by their condition
-names--the names used to match errors with handlers. An error symbol
-serves only as a convenient way to specify the intended error message
-and list of condition names. It would be cumbersome to give `signal' a
-list of condition names rather than one error symbol.
-
- By contrast, using only error symbols without condition names would
-seriously decrease the power of `condition-case'. Condition names make
-it possible to categorize errors at various levels of generality when
-you write an error handler. Using error symbols alone would eliminate
-all but the narrowest level of classification.
-
- *Note Standard Errors::, for a list of all the standard error symbols
-and their conditions.
-
projects / chise / xemacs-chise.git.1 / blobdiff