-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
The first step in evaluating a nonempty list is to examine its first
element. This element alone determines what kind of form the list is
and how the rest of the list is to be processed. The first element is
-*not* evaluated, as it would be in some Lisp dialects such as Scheme.
+_not_ evaluated, as it would be in some Lisp dialects such as Scheme.
\1f
File: lispref.info, Node: Function Indirection, Next: Function Forms, Prev: Classifying Lists, Up: Forms
The following example illustrates the symbol indirection process. We
use `fset' to set the function cell of a symbol and `symbol-function'
-to get the function cell contents (*note Function Cells::.).
+to get the function cell contents (*note Function Cells::).
Specifically, we store the symbol `car' into the function cell of
`first', and the symbol `first' into the function cell of `erste'.
(symbol-function 'car)
=> #<subr car>
-
(fset 'first 'car)
=> car
-
(fset 'erste 'first)
=> first
-
(erste '(1 2 3)) ; Call the function referenced by `erste'.
=> 1
The built-in function `indirect-function' provides an easy way to
perform symbol function indirection explicitly.
- - Function: indirect-function FUNCTION
+ - 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,
remaining elements of the list from left to right. The results are the
actual argument values, one value for each list element. The next step
is to call the function with this list of arguments, effectively using
-the function `apply' (*note Calling Functions::.). If the function is
+the function `apply' (*note Calling Functions::). If the function is
written in Lisp, the arguments are used to bind the argument variables
-of the function (*note Lambda Expressions::.); then the forms in the
+of the function (*note Lambda Expressions::); then the forms in the
function body are evaluated in order, and the value of the last body
form becomes the value of the function call.
If the first element of a list being evaluated is a macro object,
then the list is a "macro call". When a macro call is evaluated, the
-elements of the rest of the list are *not* initially evaluated.
+elements of the rest of the list are _not_ initially evaluated.
Instead, these elements themselves are used as the arguments of the
macro. The macro definition computes a replacement form, called the
"expansion" of the macro, to be evaluated in place of the original
XEmacs Lisp with a reference to where each is described.
`and'
- *note Combining Conditions::.
+ *note Combining Conditions::
`catch'
- *note Catch and Throw::.
+ *note Catch and Throw::
`cond'
- *note Conditionals::.
+ *note Conditionals::
`condition-case'
- *note Handling Errors::.
+ *note Handling Errors::
`defconst'
- *note Defining Variables::.
+ *note Defining Variables::
`defmacro'
- *note Defining Macros::.
+ *note Defining Macros::
`defun'
- *note Defining Functions::.
+ *note Defining Functions::
`defvar'
- *note Defining Variables::.
+ *note Defining Variables::
`function'
- *note Anonymous Functions::.
+ *note Anonymous Functions::
`if'
- *note Conditionals::.
+ *note Conditionals::
`interactive'
- *note Interactive Call::.
+ *note Interactive Call::
`let'
`let*'
- *note Local Variables::.
+ *note Local Variables::
`or'
- *note Combining Conditions::.
+ *note Combining Conditions::
`prog1'
`prog2'
`progn'
- *note Sequencing::.
+ *note Sequencing::
`quote'
- *note Quoting::.
+ *note Quoting::
`save-current-buffer'
- *note Excursions::.
+ *note Excursions::
`save-excursion'
- *note Excursions::.
+ *note Excursions::
`save-restriction'
- *note Narrowing::.
+ *note Narrowing::
`save-selected-window'
- *note Excursions::.
+ *note Excursions::
`save-window-excursion'
- *note Window Configurations::.
+ *note Window Configurations::
`setq'
- *note Setting Variables::.
+ *note Setting Variables::
`setq-default'
- *note Creating Buffer-Local::.
+ *note Creating Buffer-Local::
`unwind-protect'
- *note Nonlocal Exits::.
+ *note Nonlocal Exits::
`while'
- *note Iteration::.
+ *note Iteration::
`with-output-to-temp-buffer'
- *note Temporary Displays::.
+ *note Temporary Displays::
Common Lisp note: here are some comparisons of special forms in
XEmacs Lisp and Common Lisp. `setq', `if', and `catch' are
not necessary to quote self-evaluating objects such as numbers, strings,
and vectors.)
- - Special Form: quote OBJECT
+ - Special Form: quote object
This special form returns OBJECT, without evaluating it.
Because `quote' is used so often in programs, Lisp provides a
=> [(quote foo)]
Other quoting constructs include `function' (*note Anonymous
-Functions::.), which causes an anonymous lambda expression written in
-Lisp to be compiled, and ``' (*note Backquote::.), which is used to
-quote only part of a list, while computing and substituting other parts.
+Functions::), which causes an anonymous lambda expression written in
+Lisp to be compiled, and ``' (*note Backquote::), which is used to quote
+only part of a list, while computing and substituting other parts.
\1f
File: lispref.info, Node: Control Structures, Next: Variables, Prev: Evaluation, Up: Top
Control Structures
******************
- A Lisp program consists of expressions or "forms" (*note Forms::.).
+ A Lisp program consists of expressions or "forms" (*note Forms::).
We control the order of execution of the forms by enclosing them in
"control structures". Control structures are special forms which
control when, whether, or how many times to execute the forms they
jumps--all discussed below. The built-in control structures are
special forms since their subforms are not necessarily evaluated or not
evaluated sequentially. You can use macros to define your own control
-structure constructs (*note Macros::.).
+structure constructs (*note Macros::).
* Menu:
is not used as often as it used to be. It is needed now most often
inside an `unwind-protect', `and', `or', or in the THEN-part of an `if'.
- - Special Form: progn FORMS...
+ - Special Form: progn forms...
This special form evaluates all of the FORMS, in textual order,
returning the result of the final form.
Two other control constructs likewise evaluate a series of forms but
return a different value:
- - Special Form: prog1 FORM1 FORMS...
+ - Special Form: prog1 form1 forms...
This special form evaluates FORM1 and all of the FORMS, in textual
order, returning the result of FORM1.
(prog1 (car x) (setq x (cdr x)))
- - Special Form: prog2 FORM1 FORM2 FORMS...
+ - Special Form: prog2 form1 form2 forms...
This special form evaluates FORM1, FORM2, and all of the following
FORMS, in textual order, returning the result of FORM2.
Lisp has two conditional forms: `if', which is much the same as in other
languages, and `cond', which is a generalized case statement.
- - Special Form: if CONDITION THEN-FORM ELSE-FORMS...
+ - Special Form: if condition then-form else-forms...
`if' chooses between the THEN-FORM and the ELSE-FORMS based on the
value of CONDITION. If the evaluated CONDITION is non-`nil',
THEN-FORM is evaluated and the result returned. Otherwise, the
'very-false)
=> very-false
- - Special Form: cond CLAUSE...
+ - Special Form: cond clause...
`cond' chooses among an arbitrary number of alternatives. Each
CLAUSE in the `cond' must be a list. The CAR of this list is the
CONDITION; the remaining elements, if any, the BODY-FORMS. Thus,
`and' and `or' can also be used individually as kinds of multiple
conditional constructs.
- - Function: not CONDITION
+ - Function: not condition
This function tests for the falsehood of CONDITION. It returns
`t' if CONDITION is `nil', and `nil' otherwise. The function
`not' is identical to `null', and we recommend using the name
`null' if you are testing for an empty list.
- - Special Form: and CONDITIONS...
+ - Special Form: and conditions...
The `and' special form tests whether all the CONDITIONS are true.
It works by evaluating the CONDITIONS one by one in the order
written.
==
(cond (ARG1 (cond (ARG2 ARG3))))
- - Special Form: or CONDITIONS...
+ - Special Form: or conditions...
The `or' special form tests whether at least one of the CONDITIONS
is true. It works by evaluating all the CONDITIONS one by one in
the order written.
of a list, or once for each integer from 0 to N. You can do this in
XEmacs Lisp with the special form `while':
- - Special Form: while CONDITION FORMS...
+ - Special Form: while condition forms...
`while' first evaluates CONDITION. If the result is non-`nil', it
evaluates FORMS in textual order. Then it reevaluates CONDITION,
and if the result is non-`nil', it evaluates FORMS again. This
There is no limit on the number of iterations that may occur. The
loop will continue until either CONDITION evaluates to `nil' or
- until an error or `throw' jumps out of it (*note Nonlocal
- Exits::.).
+ until an error or `throw' jumps out of it (*note Nonlocal Exits::).
The value of a `while' form is always `nil'.
`catch', including function calls. When binding constructs such as
`let' or function calls are exited in this way, the bindings are
unbound, just as they are when these constructs exit normally (*note
-Local Variables::.). Likewise, `throw' restores the buffer and
-position saved by `save-excursion' (*note Excursions::.), and the
-narrowing status saved by `save-restriction' and the window selection
-saved by `save-window-excursion' (*note Window Configurations::.). It
-also runs any cleanups established with the `unwind-protect' special
-form when it exits that form (*note Cleanups::.).
+Local Variables::). Likewise, `throw' restores the buffer and position
+saved by `save-excursion' (*note Excursions::), and the narrowing
+status saved by `save-restriction' and the window selection saved by
+`save-window-excursion' (*note Window Configurations::). It also runs
+any cleanups established with the `unwind-protect' special form when it
+exits that form (*note Cleanups::).
The `throw' need not appear lexically within the `catch' that it
jumps to. It can equally well be called from another function called
after entry to the `catch', and chronologically before exit from it, it
has access to that `catch'. This is why `throw' can be used in
commands such as `exit-recursive-edit' that throw back to the editor
-command loop (*note Recursive Editing::.).
+command loop (*note Recursive Editing::).
Common Lisp note: Most other versions of Lisp, including Common
Lisp, have several ways of transferring control nonsequentially:
`return', `return-from', and `go', for example. XEmacs Lisp has
only `throw'.
- - Special Form: catch TAG BODY...
+ - Special Form: catch tag body...
`catch' establishes a return point for the `throw' function. The
return point is distinguished from other such return points by TAG,
which may be any Lisp object. The argument TAG is evaluated
the `catch' exits immediately; the value it returns is whatever
was specified as the second argument of `throw'.
- - Function: throw TAG VALUE
+ - Function: throw tag value
The purpose of `throw' is to return from a return point previously
established with `catch'. The argument TAG is used to choose
among the various existing return points; it must be `eq' to the
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
+ - 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.
+ 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' 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: 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.
+ - 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 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
a list of the form `(ERROR-SYMBOL . DATA)' (*note Handling
- Errors::.). If the error is not handled, these two values are
- used in printing the error message.
+ 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 (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.
- (signal 'no-such-error '("My unknown error condition."))
- error--> peculiar error: "My unknown error condition."
+ 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.
- Common Lisp note: XEmacs Lisp has nothing like the Common Lisp
- concept of continuable errors.
+ (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
+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
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
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...
+ - 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
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
+ 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.
(princ (format "Arithmetic error: %s" err))
1000000)))
=> safe-divide
-
+
(safe-divide 5 0)
-| Arithmetic error: (arith-error)
=> 1000000
(setq baz 34)
=> 34
-
+
(condition-case err
(if (eq baz 35)
t
-| 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