This is ../info/lispref.info, produced by makeinfo version 4.0 from lispref/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.  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 #) ;; Evaluate it. (eval buffer) -| # => #  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.  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.  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: ;; ------------- ----- ------- ------- ;; | # | <-- | car | <-- | first | <-- | erste | ;; ------------- ----- ------- ------- (symbol-function '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 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: (defun indirect-function (function) (if (symbolp function) (indirect-function (symbol-function function)) function))  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.  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.  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).  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::.  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.  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.  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"  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))  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.  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).  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.  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)'.  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.  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.  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', `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::. 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. Try something else. (error "You have committed %d errors." 10) error--> You have committed 10 errors. 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 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 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-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. 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. 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) ...)  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. 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.