+++ /dev/null
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
-
-INFO-DIR-SECTION XEmacs Editor
-START-INFO-DIR-ENTRY
-* Lispref: (lispref). XEmacs Lisp Reference Manual.
-END-INFO-DIR-ENTRY
-
- Edition History:
-
- GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
-Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
-Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
-XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
-GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
-Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
-Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
-Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
-November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
-Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
-Copyright (C) 1995, 1996 Ben Wing.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Foundation.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the section entitled "GNU General Public License" is included
-exactly as in the original, and provided that the entire resulting
-derived work is distributed under the terms of a permission notice
-identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that the section entitled "GNU General Public License"
-may be included in a translation approved by the Free Software
-Foundation instead of in the original English.
-
-\1f
-File: lispref.info, Node: Symbol Forms, Next: Classifying Lists, Prev: Self-Evaluating Forms, Up: Forms
-
-Symbol Forms
-------------
-
- When a symbol is evaluated, it is treated as a variable. The result
-is the variable's value, if it has one. If it has none (if its value
-cell is void), an error is signaled. For more information on the use of
-variables, see *Note Variables::.
-
- In the following example, we set the value of a symbol with `setq'.
-Then we evaluate the symbol, and get back the value that `setq' stored.
-
- (setq a 123)
- => 123
- (eval 'a)
- => 123
- a
- => 123
-
- The symbols `nil' and `t' are treated specially, so that the value
-of `nil' is always `nil', and the value of `t' is always `t'; you
-cannot set or bind them to any other values. Thus, these two symbols
-act like self-evaluating forms, even though `eval' treats them like any
-other symbol.
-
-\1f
-File: lispref.info, Node: Classifying Lists, Next: Function Indirection, Prev: Symbol Forms, Up: Forms
-
-Classification of List Forms
-----------------------------
-
- A form that is a nonempty list is either a function call, a macro
-call, or a special form, according to its first element. These three
-kinds of forms are evaluated in different ways, described below. The
-remaining list elements constitute the "arguments" for the function,
-macro, or special form.
-
- 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.
-
-\1f
-File: lispref.info, Node: Function Indirection, Next: Function Forms, Prev: Classifying Lists, Up: Forms
-
-Symbol Function Indirection
----------------------------
-
- If the first element of the list is a symbol then evaluation examines
-the symbol's function cell, and uses its contents instead of the
-original symbol. If the contents are another symbol, this process,
-called "symbol function indirection", is repeated until it obtains a
-non-symbol. *Note Function Names::, for more information about using a
-symbol as a name for a function stored in the function cell of the
-symbol.
-
- One possible consequence of this process is an infinite loop, in the
-event that a symbol's function cell refers to the same symbol. Or a
-symbol may have a void function cell, in which case the subroutine
-`symbol-function' signals a `void-function' error. But if neither of
-these things happens, we eventually obtain a non-symbol, which ought to
-be a function or other suitable object.
-
- More precisely, we should now have a Lisp function (a lambda
-expression), a byte-code function, a primitive function, a Lisp macro, a
-special form, or an autoload object. Each of these types is a case
-described in one of the following sections. If the object is not one of
-these types, the error `invalid-function' is signaled.
-
- 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::.).
-Specifically, we store the symbol `car' into the function cell of
-`first', and the symbol `first' into the function cell of `erste'.
-
- ;; Build this function cell linkage:
- ;; ------------- ----- ------- -------
- ;; | #<subr car> | <-- | car | <-- | first | <-- | 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
-
- By contrast, the following example calls a function without any
-symbol function indirection, because the first element is an anonymous
-Lisp function, not a symbol.
-
- ((lambda (arg) (erste arg))
- '(1 2 3))
- => 1
-
-Executing the function itself evaluates its body; this does involve
-symbol function indirection when calling `erste'.
-
- 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.
-
- Here is how you could define `indirect-function' in Lisp:
-
- (defun indirect-function (function)
- (if (symbolp function)
- (indirect-function (symbol-function function))
- function))
-
-\1f
-File: lispref.info, Node: Function Forms, Next: Macro Forms, Prev: Function Indirection, Up: Forms
-
-Evaluation of Function Forms
-----------------------------
-
- If the first element of a list being evaluated is a Lisp function
-object, byte-code object or primitive function object, then that list is
-a "function call". For example, here is a call to the function `+':
-
- (+ 1 x)
-
- The first step in evaluating a function call is to evaluate the
-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
-written in Lisp, the arguments are used to bind the argument variables
-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.
-
-\1f
-File: lispref.info, Node: Macro Forms, Next: Special Forms, Prev: Function Forms, Up: Forms
-
-Lisp Macro Evaluation
----------------------
-
- 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.
-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
-form. The expansion may be any sort of form: a self-evaluating
-constant, a symbol, or a list. If the expansion is itself a macro call,
-this process of expansion repeats until some other sort of form results.
-
- Ordinary evaluation of a macro call finishes by evaluating the
-expansion. However, the macro expansion is not necessarily evaluated
-right away, or at all, because other programs also expand macro calls,
-and they may or may not evaluate the expansions.
-
- Normally, the argument expressions are not evaluated as part of
-computing the macro expansion, but instead appear as part of the
-expansion, so they are computed when the expansion is computed.
-
- For example, given a macro defined as follows:
-
- (defmacro cadr (x)
- (list 'car (list 'cdr x)))
-
-an expression such as `(cadr (assq 'handler list))' is a macro call,
-and its expansion is:
-
- (car (cdr (assq 'handler list)))
-
-Note that the argument `(assq 'handler list)' appears in the expansion.
-
- *Note Macros::, for a complete description of XEmacs Lisp macros.
-
-\1f
-File: lispref.info, Node: Special Forms, Next: Autoloading, Prev: Macro Forms, Up: Forms
-
-Special Forms
--------------
-
- A "special form" is a primitive function specially marked so that
-its arguments are not all evaluated. Most special forms define control
-structures or perform variable bindings--things which functions cannot
-do.
-
- Each special form has its own rules for which arguments are evaluated
-and which are used without evaluation. Whether a particular argument is
-evaluated may depend on the results of evaluating other arguments.
-
- Here is a list, in alphabetical order, of all of the special forms in
-XEmacs Lisp with a reference to where each is described.
-
-`and'
- *note Combining Conditions::.
-
-`catch'
- *note Catch and Throw::.
-
-`cond'
- *note Conditionals::.
-
-`condition-case'
- *note Handling Errors::.
-
-`defconst'
- *note Defining Variables::.
-
-`defmacro'
- *note Defining Macros::.
-
-`defun'
- *note Defining Functions::.
-
-`defvar'
- *note Defining Variables::.
-
-`function'
- *note Anonymous Functions::.
-
-`if'
- *note Conditionals::.
-
-`interactive'
- *note Interactive Call::.
-
-`let'
-`let*'
- *note Local Variables::.
-
-`or'
- *note Combining Conditions::.
-
-`prog1'
-`prog2'
-`progn'
- *note Sequencing::.
-
-`quote'
- *note Quoting::.
-
-`save-current-buffer'
- *note Excursions::.
-
-`save-excursion'
- *note Excursions::.
-
-`save-restriction'
- *note Narrowing::.
-
-`save-selected-window'
- *note Excursions::.
-
-`save-window-excursion'
- *note Window Configurations::.
-
-`setq'
- *note Setting Variables::.
-
-`setq-default'
- *note Creating Buffer-Local::.
-
-`unwind-protect'
- *note Nonlocal Exits::.
-
-`while'
- *note Iteration::.
-
-`with-output-to-temp-buffer'
- *note Temporary Displays::.
-
- Common Lisp note: here are some comparisons of special forms in
- XEmacs Lisp and Common Lisp. `setq', `if', and `catch' are
- special forms in both XEmacs Lisp and Common Lisp. `defun' is a
- special form in XEmacs Lisp, but a macro in Common Lisp.
- `save-excursion' is a special form in XEmacs Lisp, but doesn't
- exist in Common Lisp. `throw' is a special form in Common Lisp
- (because it must be able to throw multiple values), but it is a
- function in XEmacs Lisp (which doesn't have multiple values).
-
-\1f
-File: lispref.info, Node: Autoloading, Prev: Special Forms, Up: Forms
-
-Autoloading
------------
-
- The "autoload" feature allows you to call a function or macro whose
-function definition has not yet been loaded into XEmacs. It specifies
-which file contains the definition. When an autoload object appears as
-a symbol's function definition, calling that symbol as a function
-automatically loads the specified file; then it calls the real
-definition loaded from that file. *Note Autoload::.
-
-\1f
-File: lispref.info, Node: Quoting, Prev: Forms, Up: Evaluation
-
-Quoting
-=======
-
- The special form `quote' returns its single argument, as written,
-without evaluating it. This provides a way to include constant symbols
-and lists, which are not self-evaluating objects, in a program. (It is
-not necessary to quote self-evaluating objects such as numbers, strings,
-and vectors.)
-
- - Special Form: quote OBJECT
- This special form returns OBJECT, without evaluating it.
-
- Because `quote' is used so often in programs, Lisp provides a
-convenient read syntax for it. An apostrophe character (`'') followed
-by a Lisp object (in read syntax) expands to a list whose first element
-is `quote', and whose second element is the object. Thus, the read
-syntax `'x' is an abbreviation for `(quote x)'.
-
- Here are some examples of expressions that use `quote':
-
- (quote (+ 1 2))
- => (+ 1 2)
- (quote foo)
- => foo
- 'foo
- => foo
- ''foo
- => (quote foo)
- '(quote foo)
- => (quote foo)
- ['foo]
- => [(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.
-
-\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::.).
-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
-contain.
-
- The simplest order of execution is sequential execution: first form
-A, then form B, and so on. This is what happens when you write several
-forms in succession in the body of a function, or at top level in a
-file of Lisp code--the forms are executed in the order written. We
-call this "textual order". For example, if a function body consists of
-two forms A and B, evaluation of the function evaluates first A and
-then B, and the function's value is the value of B.
-
- Explicit control structures make possible an order of execution other
-than sequential.
-
- XEmacs Lisp provides several kinds of control structure, including
-other varieties of sequencing, conditionals, iteration, and (controlled)
-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::.).
-
-* Menu:
-
-* Sequencing:: Evaluation in textual order.
-* Conditionals:: `if', `cond'.
-* Combining Conditions:: `and', `or', `not'.
-* Iteration:: `while' loops.
-* Nonlocal Exits:: Jumping out of a sequence.
-
-\1f
-File: lispref.info, Node: Sequencing, Next: Conditionals, Up: Control Structures
-
-Sequencing
-==========
-
- Evaluating forms in the order they appear is the most common way
-control passes from one form to another. In some contexts, such as in a
-function body, this happens automatically. Elsewhere you must use a
-control structure construct to do this: `progn', the simplest control
-construct of Lisp.
-
- A `progn' special form looks like this:
-
- (progn A B C ...)
-
-and it says to execute the forms A, B, C and so on, in that order.
-These forms are called the body of the `progn' form. The value of the
-last form in the body becomes the value of the entire `progn'.
-
- In the early days of Lisp, `progn' was the only way to execute two
-or more forms in succession and use the value of the last of them. But
-programmers found they often needed to use a `progn' in the body of a
-function, where (at that time) only one form was allowed. So the body
-of a function was made into an "implicit `progn'": several forms are
-allowed just as in the body of an actual `progn'. Many other control
-structures likewise contain an implicit `progn'. As a result, `progn'
-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...
- This special form evaluates all of the FORMS, in textual order,
- returning the result of the final form.
-
- (progn (print "The first form")
- (print "The second form")
- (print "The third form"))
- -| "The first form"
- -| "The second form"
- -| "The third form"
- => "The third form"
-
- Two other control constructs likewise evaluate a series of forms but
-return a different value:
-
- - Special Form: prog1 FORM1 FORMS...
- This special form evaluates FORM1 and all of the FORMS, in textual
- order, returning the result of FORM1.
-
- (prog1 (print "The first form")
- (print "The second form")
- (print "The third form"))
- -| "The first form"
- -| "The second form"
- -| "The third form"
- => "The first form"
-
- Here is a way to remove the first element from a list in the
- variable `x', then return the value of that former element:
-
- (prog1 (car x) (setq x (cdr x)))
-
- - 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.
-
- (prog2 (print "The first form")
- (print "The second form")
- (print "The third form"))
- -| "The first form"
- -| "The second form"
- -| "The third form"
- => "The second form"
-
-\1f
-File: lispref.info, Node: Conditionals, Next: Combining Conditions, Prev: Sequencing, Up: Control Structures
-
-Conditionals
-============
-
- Conditional control structures choose among alternatives. XEmacs
-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...
- `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
- ELSE-FORMS are evaluated in textual order, and the value of the
- last one is returned. (The ELSE part of `if' is an example of an
- implicit `progn'. *Note Sequencing::.)
-
- If CONDITION has the value `nil', and no ELSE-FORMS are given,
- `if' returns `nil'.
-
- `if' is a special form because the branch that is not selected is
- never evaluated--it is ignored. Thus, in the example below,
- `true' is not printed because `print' is never called.
-
- (if nil
- (print 'true)
- 'very-false)
- => very-false
-
- - 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,
- a clause looks like this:
-
- (CONDITION BODY-FORMS...)
-
- `cond' tries the clauses in textual order, by evaluating the
- CONDITION of each clause. If the value of CONDITION is non-`nil',
- the clause "succeeds"; then `cond' evaluates its BODY-FORMS, and
- the value of the last of BODY-FORMS becomes the value of the
- `cond'. The remaining clauses are ignored.
-
- If the value of CONDITION is `nil', the clause "fails", so the
- `cond' moves on to the following clause, trying its CONDITION.
-
- If every CONDITION evaluates to `nil', so that every clause fails,
- `cond' returns `nil'.
-
- A clause may also look like this:
-
- (CONDITION)
-
- Then, if CONDITION is non-`nil' when tested, the value of
- CONDITION becomes the value of the `cond' form.
-
- The following example has four clauses, which test for the cases
- where the value of `x' is a number, string, buffer and symbol,
- respectively:
-
- (cond ((numberp x) x)
- ((stringp x) x)
- ((bufferp x)
- (setq temporary-hack x) ; multiple body-forms
- (buffer-name x)) ; in one clause
- ((symbolp x) (symbol-value x)))
-
- Often we want to execute the last clause whenever none of the
- previous clauses was successful. To do this, we use `t' as the
- CONDITION of the last clause, like this: `(t BODY-FORMS)'. The
- form `t' evaluates to `t', which is never `nil', so this clause
- never fails, provided the `cond' gets to it at all.
-
- For example,
-
- (cond ((eq a 'hack) 'foo)
- (t "default"))
- => "default"
-
- This expression is a `cond' which returns `foo' if the value of
- `a' is 1, and returns the string `"default"' otherwise.
-
- Any conditional construct can be expressed with `cond' or with `if'.
-Therefore, the choice between them is a matter of style. For example:
-
- (if A B C)
- ==
- (cond (A B) (t C))
-
-\1f
-File: lispref.info, Node: Combining Conditions, Next: Iteration, Prev: Conditionals, Up: Control Structures
-
-Constructs for Combining Conditions
-===================================
-
- This section describes three constructs that are often used together
-with `if' and `cond' to express complicated conditions. The constructs
-`and' and `or' can also be used individually as kinds of multiple
-conditional constructs.
-
- - 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...
- The `and' special form tests whether all the CONDITIONS are true.
- It works by evaluating the CONDITIONS one by one in the order
- written.
-
- If any of the CONDITIONS evaluates to `nil', then the result of
- the `and' must be `nil' regardless of the remaining CONDITIONS; so
- `and' returns right away, ignoring the remaining CONDITIONS.
-
- If all the CONDITIONS turn out non-`nil', then the value of the
- last of them becomes the value of the `and' form.
-
- Here is an example. The first condition returns the integer 1,
- which is not `nil'. Similarly, the second condition returns the
- integer 2, which is not `nil'. The third condition is `nil', so
- the remaining condition is never evaluated.
-
- (and (print 1) (print 2) nil (print 3))
- -| 1
- -| 2
- => nil
-
- Here is a more realistic example of using `and':
-
- (if (and (consp foo) (eq (car foo) 'x))
- (message "foo is a list starting with x"))
-
- Note that `(car foo)' is not executed if `(consp foo)' returns
- `nil', thus avoiding an error.
-
- `and' can be expressed in terms of either `if' or `cond'. For
- example:
-
- (and ARG1 ARG2 ARG3)
- ==
- (if ARG1 (if ARG2 ARG3))
- ==
- (cond (ARG1 (cond (ARG2 ARG3))))
-
- - 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.
-
- If any of the CONDITIONS evaluates to a non-`nil' value, then the
- result of the `or' must be non-`nil'; so `or' returns right away,
- ignoring the remaining CONDITIONS. The value it returns is the
- non-`nil' value of the condition just evaluated.
-
- If all the CONDITIONS turn out `nil', then the `or' expression
- returns `nil'.
-
- For example, this expression tests whether `x' is either 0 or
- `nil':
-
- (or (eq x nil) (eq x 0))
-
- Like the `and' construct, `or' can be written in terms of `cond'.
- For example:
-
- (or ARG1 ARG2 ARG3)
- ==
- (cond (ARG1)
- (ARG2)
- (ARG3))
-
- You could almost write `or' in terms of `if', but not quite:
-
- (if ARG1 ARG1
- (if ARG2 ARG2
- ARG3))
-
- This is not completely equivalent because it can evaluate ARG1 or
- ARG2 twice. By contrast, `(or ARG1 ARG2 ARG3)' never evaluates
- any argument more than once.
-
-\1f
-File: lispref.info, Node: Iteration, Next: Nonlocal Exits, Prev: Combining Conditions, Up: Control Structures
-
-Iteration
-=========
-
- Iteration means executing part of a program repetitively. For
-example, you might want to repeat some computation once for each element
-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...
- `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
- process repeats until CONDITION evaluates to `nil'.
-
- 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::.).
-
- The value of a `while' form is always `nil'.
-
- (setq num 0)
- => 0
- (while (< num 4)
- (princ (format "Iteration %d." num))
- (setq num (1+ num)))
- -| Iteration 0.
- -| Iteration 1.
- -| Iteration 2.
- -| Iteration 3.
- => nil
-
- If you would like to execute something on each iteration before the
- end-test, put it together with the end-test in a `progn' as the
- first argument of `while', as shown here:
-
- (while (progn
- (forward-line 1)
- (not (looking-at "^$"))))
-
- This moves forward one line and continues moving by lines until it
- reaches an empty. It is unusual in that the `while' has no body,
- just the end test (which also does the real work of moving point).
-
-\1f
-File: lispref.info, Node: Nonlocal Exits, Prev: Iteration, Up: Control Structures
-
-Nonlocal Exits
-==============
-
- A "nonlocal exit" is a transfer of control from one point in a
-program to another remote point. Nonlocal exits can occur in XEmacs
-Lisp as a result of errors; you can also use them under explicit
-control. Nonlocal exits unbind all variable bindings made by the
-constructs being exited.
-
-* Menu:
-
-* Catch and Throw:: Nonlocal exits for the program's own purposes.
-* Examples of Catch:: Showing how such nonlocal exits can be written.
-* Errors:: How errors are signaled and handled.
-* Cleanups:: Arranging to run a cleanup form if an error happens.
-
-\1f
-File: lispref.info, Node: Catch and Throw, Next: Examples of Catch, Up: Nonlocal Exits
-
-Explicit Nonlocal Exits: `catch' and `throw'
---------------------------------------------
-
- Most control constructs affect only the flow of control within the
-construct itself. The function `throw' is the exception to this rule
-of normal program execution: it performs a nonlocal exit on request.
-(There are other exceptions, but they are for error handling only.)
-`throw' is used inside a `catch', and jumps back to that `catch'. For
-example:
-
- (catch 'foo
- (progn
- ...
- (throw 'foo t)
- ...))
-
-The `throw' transfers control straight back to the corresponding
-`catch', which returns immediately. The code following the `throw' is
-not executed. The second argument of `throw' is used as the return
-value of the `catch'.
-
- The `throw' and the `catch' are matched through the first argument:
-`throw' searches for a `catch' whose first argument is `eq' to the one
-specified. Thus, in the above example, the `throw' specifies `foo',
-and the `catch' specifies the same symbol, so that `catch' is
-applicable. If there is more than one applicable `catch', the
-innermost one takes precedence.
-
- Executing `throw' exits all Lisp constructs up to the matching
-`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::.).
-
- The `throw' need not appear lexically within the `catch' that it
-jumps to. It can equally well be called from another function called
-within the `catch'. As long as the `throw' takes place chronologically
-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::.).
-
- 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...
- `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
- normally before the return point is established.
-
- With the return point in effect, `catch' evaluates the forms of the
- BODY in textual order. If the forms execute normally, without
- error or nonlocal exit, the value of the last body form is
- returned from the `catch'.
-
- If a `throw' is done within BODY specifying the same value TAG,
- the `catch' exits immediately; the value it returns is whatever
- was specified as the second argument of `throw'.
-
- - 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
- value specified in the `catch'. If multiple return points match
- TAG, the innermost one is used.
-
- The argument VALUE is used as the value to return from that
- `catch'.
-
- If no return point is in effect with tag TAG, then a `no-catch'
- error is signaled with data `(TAG VALUE)'.
-
-\1f
-File: lispref.info, Node: Examples of Catch, Next: Errors, Prev: Catch and Throw, Up: Nonlocal Exits
-
-Examples of `catch' and `throw'
--------------------------------
-
- One way to use `catch' and `throw' is to exit from a doubly nested
-loop. (In most languages, this would be done with a "go to".) Here we
-compute `(foo I J)' for I and J varying from 0 to 9:
-
- (defun search-foo ()
- (catch 'loop
- (let ((i 0))
- (while (< i 10)
- (let ((j 0))
- (while (< j 10)
- (if (foo i j)
- (throw 'loop (list i j)))
- (setq j (1+ j))))
- (setq i (1+ i))))))
-
-If `foo' ever returns non-`nil', we stop immediately and return a list
-of I and J. If `foo' always returns `nil', the `catch' returns
-normally, and the value is `nil', since that is the result of the
-`while'.
-
- Here are two tricky examples, slightly different, showing two return
-points at once. First, two return points with the same tag, `hack':
-
- (defun catch2 (tag)
- (catch tag
- (throw 'hack 'yes)))
- => catch2
-
- (catch 'hack
- (print (catch2 'hack))
- 'no)
- -| yes
- => no
-
-Since both return points have tags that match the `throw', it goes to
-the inner one, the one established in `catch2'. Therefore, `catch2'
-returns normally with value `yes', and this value is printed. Finally
-the second body form in the outer `catch', which is `'no', is evaluated
-and returned from the outer `catch'.
-
- Now let's change the argument given to `catch2':
-
- (defun catch2 (tag)
- (catch tag
- (throw 'hack 'yes)))
- => catch2
-
- (catch 'hack
- (print (catch2 'quux))
- 'no)
- => yes
-
-We still have two return points, but this time only the outer one has
-the tag `hack'; the inner one has the tag `quux' instead. Therefore,
-`throw' makes the outer `catch' return the value `yes'. The function
-`print' is never called, and the body-form `'no' is never evaluated.
-
-\1f
-File: lispref.info, Node: Errors, Next: Cleanups, Prev: Examples of Catch, Up: Nonlocal Exits
-
-Errors
-------
-
- When XEmacs Lisp attempts to evaluate a form that, for some reason,
-cannot be evaluated, it "signals" an "error".
-
- When an error is signaled, XEmacs's default reaction is to print an
-error message and terminate execution of the current command. This is
-the right thing to do in most cases, such as if you type `C-f' at the
-end of the buffer.
-
- In complicated programs, simple termination may not be what you want.
-For example, the program may have made temporary changes in data
-structures, or created temporary buffers that should be deleted before
-the program is finished. In such cases, you would use `unwind-protect'
-to establish "cleanup expressions" to be evaluated in case of error.
-(*Note Cleanups::.) Occasionally, you may wish the program to continue
-execution despite an error in a subroutine. In these cases, you would
-use `condition-case' to establish "error handlers" to recover control
-in case of error.
-
- Resist the temptation to use error handling to transfer control from
-one part of the program to another; use `catch' and `throw' instead.
-*Note Catch and Throw::.
-
-* Menu:
-
-* Signaling Errors:: How to report an error.
-* Processing of Errors:: What XEmacs does when you report an error.
-* Handling Errors:: How you can trap errors and continue execution.
-* Error Symbols:: How errors are classified for trapping them.
-
-\1f
-File: lispref.info, Node: Signaling Errors, Next: Processing of Errors, Up: Errors
-
-How to Signal an Error
-......................
-
- 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'.
-
- 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.
-
- These examples show typical uses of `error':
-
- (error "You have committed an error.
- Try something else.")
- error--> You have committed an error.
- Try something else.
-
- (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: 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.
-
- The argument ERROR-SYMBOL must be an "error symbol"--a symbol
- bearing a property `error-conditions' whose value is a list of
- condition names. This is how XEmacs Lisp classifies different
- 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.
-
- 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.
-
- The function `signal' never returns (though in older Emacs versions
- it could sometimes return).
-
- (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."
-
- Common Lisp note: XEmacs Lisp has nothing like the Common Lisp
- concept of continuable errors.
-
-\1f
-File: lispref.info, Node: Processing of Errors, Next: Handling Errors, Prev: Signaling Errors, Up: Errors
-
-How XEmacs Processes Errors
-...........................
-
- When an error is signaled, `signal' searches for an active "handler"
-for the error. A handler is a sequence of Lisp expressions designated
-to be executed if an error happens in part of the Lisp program. If the
-error has an applicable handler, the handler is executed, and control
-resumes following the handler. The handler executes in the environment
-of the `condition-case' that established it; all functions called
-within that `condition-case' have already been exited, and the handler
-cannot return to them.
-
- If there is no applicable handler for the error, the current command
-is terminated and control returns to the editor command loop, because
-the command loop has an implicit handler for all kinds of errors. The
-command loop's handler uses the error symbol and associated data to
-print an error message.
-
- 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