-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Self-Evaluating Forms, Next: Symbol Forms, Up: Forms
+
+Self-Evaluating Forms
+---------------------
+
+ A "self-evaluating form" is any form that is not a list or symbol.
+Self-evaluating forms evaluate to themselves: the result of evaluation
+is the same object that was evaluated. Thus, the number 25 evaluates to
+25, and the string `"foo"' evaluates to the string `"foo"'. Likewise,
+evaluation of a vector does not cause evaluation of the elements of the
+vector--it returns the same vector with its contents unchanged.
+
+ '123 ; An object, shown without evaluation.
+ => 123
+ 123 ; Evaluated as usual--result is the same.
+ => 123
+ (eval '123) ; Evaluated "by hand"--result is the same.
+ => 123
+ (eval (eval '123)) ; Evaluating twice changes nothing.
+ => 123
+
+ It is common to write numbers, characters, strings, and even vectors
+in Lisp code, taking advantage of the fact that they self-evaluate.
+However, it is quite unusual to do this for types that lack a read
+syntax, because there's no way to write them textually. It is possible
+to construct Lisp expressions containing these types by means of a Lisp
+program. Here is an example:
+
+ ;; Build an expression containing a buffer object.
+ (setq buffer (list 'print (current-buffer)))
+ => (print #<buffer eval.texi>)
+ ;; Evaluate it.
+ (eval buffer)
+ -| #<buffer eval.texi>
+ => #<buffer eval.texi>
+
+\1f
File: lispref.info, Node: Symbol Forms, Next: Classifying Lists, Prev: Self-Evaluating Forms, Up: Forms
Symbol Forms
The built-in function `indirect-function' provides an easy way to
perform symbol function indirection explicitly.
- - Function: indirect-function function
- This function returns the meaning of FUNCTION as a function. If
- FUNCTION is a symbol, then it finds FUNCTION's function definition
- and starts over with that value. If FUNCTION is not a symbol,
- then it returns FUNCTION itself.
+ - Function: indirect-function object
+ This function returns the meaning of OBJECT as a function. If
+ OBJECT is a symbol, then it finds OBJECT's function definition and
+ starts over with that value. If OBJECT is not a symbol, then it
+ returns OBJECT itself.
Here is how you could define `indirect-function' in Lisp:
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::.
- - Function: error format-string &rest args
- This function signals an error with an error message constructed by
- applying `format' (*note String Conversion::) to FORMAT-STRING and
- ARGS.
+ XEmacs has a rich hierarchy of error symbols predefined via
+`deferror'.
+
+ error
+ syntax-error
+ invalid-read-syntax
+ list-formation-error
+ malformed-list
+ malformed-property-list
+ circular-list
+ circular-property-list
+
+ invalid-argument
+ wrong-type-argument
+ args-out-of-range
+ wrong-number-of-arguments
+ invalid-function
+ no-catch
+
+ invalid-state
+ void-function
+ cyclic-function-indirection
+ void-variable
+ cyclic-variable-indirection
+
+ invalid-operation
+ invalid-change
+ setting-constant
+ editing-error
+ beginning-of-buffer
+ end-of-buffer
+ buffer-read-only
+ io-error
+ end-of-file
+ arith-error
+ range-error
+ domain-error
+ singularity-error
+ overflow-error
+ underflow-error
+
+ The five most common errors you will probably use or base your new
+errors off of are `syntax-error', `invalid-argument', `invalid-state',
+`invalid-operation', and `invalid-change'. Note the semantic
+differences:
+
+ * `syntax-error' is for errors in complex structures: parsed strings,
+ lists, and the like.
+
+ * `invalid-argument' is for errors in a simple value. Typically, the
+ entire value, not just one part of it, is wrong.
+
+ * `invalid-state' means that some settings have been changed in such
+ a way that their current state is unallowable. More and more,
+ code is being written more carefully, and catches the error when
+ the settings are being changed, rather than afterwards. This
+ leads us to the next error:
+
+ * `invalid-change' means that an attempt is being made to change some
+ settings into an invalid state. `invalid-change' is a type of
+ `invalid-operation'.
+
+ * `invalid-operation' refers to all cases where code is trying to do
+ something that's disallowed. This includes file errors, buffer
+ errors (e.g. running off the end of a buffer), `invalid-change' as
+ just mentioned, and arithmetic errors.
+
+ - Function: error datum &rest args
+ This function signals a non-continuable error.
+
+ DATUM should normally be an error symbol, i.e. a symbol defined
+ using `define-error'. ARGS will be made into a list, and DATUM
+ and ARGS passed as the two arguments to `signal', the most basic
+ error handling function.
+
+ This error is not continuable: you cannot continue execution after
+ the error using the debugger `r' command. See also `cerror'.
+
+ The correct semantics of ARGS varies from error to error, but for
+ most errors that need to be generated in Lisp code, the first
+ argument should be a string describing the *context* of the error
+ (i.e. the exact operation being performed and what went wrong),
+ and the remaining arguments or \"frobs\" (most often, there is
+ one) specify the offending object(s) and/or provide additional
+ details such as the exact error when a file error occurred, e.g.:
+
+ * the buffer in which an editing error occurred.
+
+ * an invalid value that was encountered. (In such cases, the
+ string should describe the purpose or \"semantics\" of the
+ value [e.g. if the value is an argument to a function, the
+ name of the argument; if the value is the value corresponding
+ to a keyword, the name of the keyword; if the value is
+ supposed to be a list length, say this and say what the
+ purpose of the list is; etc.] as well as specifying why the
+ value is invalid, if that's not self-evident.)
+
+ * the file in which an error occurred. (In such cases, there
+ should be a second frob, probably a string, specifying the
+ exact error that occurred. This does not occur in the string
+ that precedes the first frob, because that frob describes the
+ exact operation that was happening.
+
+ For historical compatibility, DATUM can also be a string. In this
+ case, DATUM and ARGS are passed together as the arguments to
+ `format', and then an error is signalled using the error symbol
+ `error' and formatted string. Although this usage of `error' is
+ very common, it is deprecated because it totally defeats the
+ purpose of having structured errors. There is now a rich set of
+ defined errors to use.
+
+ See also `cerror', `signal', and `signal-error'."
These examples show typical uses of `error':
+ (error 'syntax-error
+ "Dialog descriptor must supply at least one button"
+ descriptor)
+
(error "You have committed an error.
Try something else.")
error--> You have committed an error.
(error "You have committed %d errors." 10)
error--> You have committed 10 errors.
- `error' works by calling `signal' with two arguments: the error
- symbol `error', and a list containing the string returned by
- `format'.
-
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 datum &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")
- Common Lisp note: XEmacs Lisp has nothing like the Common Lisp
- concept of continuable errors.
+ - 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.
+
+ 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
the environment of the error, so that you can examine values of
variables precisely as they were at the time of the error.
-\1f
-File: lispref.info, Node: Handling Errors, Next: Error Symbols, Prev: Processing of Errors, Up: Errors
-
-Writing Code to Handle Errors
-.............................
-
- The usual effect of signaling an error is to terminate the command
-that is running and return immediately to the XEmacs editor command
-loop. You can arrange to trap errors occurring in a part of your
-program by establishing an error handler, with the special form
-`condition-case'. A simple example looks like this:
-
- (condition-case nil
- (delete-file filename)
- (error nil))
-
-This deletes the file named FILENAME, catching any error and returning
-`nil' if an error occurs.
-
- The second argument of `condition-case' is called the "protected
-form". (In the example above, the protected form is a call to
-`delete-file'.) The error handlers go into effect when this form
-begins execution and are deactivated when this form returns. They
-remain in effect for all the intervening time. In particular, they are
-in effect during the execution of functions called by this form, in
-their subroutines, and so on. This is a good thing, since, strictly
-speaking, errors can be signaled only by Lisp primitives (including
-`signal' and `error') called by the protected form, not by the
-protected form itself.
-
- The arguments after the protected form are handlers. Each handler
-lists one or more "condition names" (which are symbols) to specify
-which errors it will handle. The error symbol specified when an error
-is signaled also defines a list of condition names. A handler applies
-to an error if they have any condition names in common. In the example
-above, there is one handler, and it specifies one condition name,
-`error', which covers all errors.
-
- The search for an applicable handler checks all the established
-handlers starting with the most recently established one. Thus, if two
-nested `condition-case' forms offer to handle the same error, the inner
-of the two will actually handle it.
-
- When an error is handled, control returns to the handler. Before
-this happens, XEmacs unbinds all variable bindings made by binding
-constructs that are being exited and executes the cleanups of all
-`unwind-protect' forms that are exited. Once control arrives at the
-handler, the body of the handler is executed.
-
- After execution of the handler body, execution continues by returning
-from the `condition-case' form. Because the protected form is exited
-completely before execution of the handler, the handler cannot resume
-execution at the point of the error, nor can it examine variable
-bindings that were made within the protected form. All it can do is
-clean up and proceed.
-
- `condition-case' is often used to trap errors that are predictable,
-such as failure to open a file in a call to `insert-file-contents'. It
-is also used to trap errors that are totally unpredictable, such as
-when the program evaluates an expression read from the user.
-
- 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
-handler (though using `throw' when there is no suitable `catch' signals
-an error that can be handled).
-
- - Special Form: condition-case var protected-form handlers...
- This special form establishes the error handlers HANDLERS around
- the execution of PROTECTED-FORM. If PROTECTED-FORM executes
- without error, the value it returns becomes the value of the
- `condition-case' form; in this case, the `condition-case' has no
- effect. The `condition-case' form makes a difference when an
- error occurs during PROTECTED-FORM.
-
- Each of the HANDLERS is a list of the form `(CONDITIONS BODY...)'.
- Here CONDITIONS is an error condition name to be handled, or a
- list of condition names; BODY is one or more Lisp expressions to
- be executed when this handler handles an error. Here are examples
- of handlers:
-
- (error nil)
-
- (arith-error (message "Division by zero"))
-
- ((arith-error file-error)
- (message
- "Either division by zero or failure to open a file"))
-
- Each error that occurs has an "error symbol" that describes what
- kind of error it is. The `error-conditions' property of this
- symbol is a list of condition names (*note Error Symbols::). Emacs
- searches all the active `condition-case' forms for a handler that
- specifies one or more of these condition names; the innermost
- matching `condition-case' handles the error. Within this
- `condition-case', the first applicable handler handles the error.
-
- After executing the body of the handler, the `condition-case'
- returns normally, using the value of the last form in the handler
- body as the overall value.
-
- The argument VAR is a variable. `condition-case' does not bind
- this variable when executing the PROTECTED-FORM, only when it
- handles an error. At that time, it binds VAR locally to a list of
- the form `(ERROR-SYMBOL . DATA)', giving the particulars of the
- error. The handler can refer to this list to decide what to do.
- For example, if the error is for failure opening a file, the file
- name is the second element of DATA--the third element of VAR.
-
- If VAR is `nil', that means no variable is bound. Then the error
- symbol and associated data are not available to the handler.
-
- Here is an example of using `condition-case' to handle the error
-that results from dividing by zero. The handler prints out a warning
-message and returns a very large number.
-
- (defun safe-divide (dividend divisor)
- (condition-case err
- ;; Protected form.
- (/ dividend divisor)
- ;; The handler.
- (arith-error ; Condition.
- (princ (format "Arithmetic error: %s" err))
- 1000000)))
- => safe-divide
-
- (safe-divide 5 0)
- -| Arithmetic error: (arith-error)
- => 1000000
-
-The handler specifies condition name `arith-error' so that it will
-handle only division-by-zero errors. Other kinds of errors will not be
-handled, at least not by this `condition-case'. Thus,
-
- (safe-divide nil 3)
- error--> Wrong type argument: integer-or-marker-p, nil
-
- Here is a `condition-case' that catches all kinds of errors,
-including those signaled with `error':
-
- (setq baz 34)
- => 34
-
- (condition-case err
- (if (eq baz 35)
- t
- ;; This is a call to the function `error'.
- (error "Rats! The variable %s was %s, not 35" 'baz baz))
- ;; This is the handler; it is not a form.
- (error (princ (format "The error was: %s" err))
- 2))
- -| 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 / blobdiff