1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Symbol Forms, Next: Classifying Lists, Prev: Self-Evaluating Forms, Up: Forms
58 When a symbol is evaluated, it is treated as a variable. The result
59 is the variable's value, if it has one. If it has none (if its value
60 cell is void), an error is signaled. For more information on the use of
61 variables, see *Note Variables::.
63 In the following example, we set the value of a symbol with `setq'.
64 Then we evaluate the symbol, and get back the value that `setq' stored.
73 The symbols `nil' and `t' are treated specially, so that the value
74 of `nil' is always `nil', and the value of `t' is always `t'; you
75 cannot set or bind them to any other values. Thus, these two symbols
76 act like self-evaluating forms, even though `eval' treats them like any
80 File: lispref.info, Node: Classifying Lists, Next: Function Indirection, Prev: Symbol Forms, Up: Forms
82 Classification of List Forms
83 ----------------------------
85 A form that is a nonempty list is either a function call, a macro
86 call, or a special form, according to its first element. These three
87 kinds of forms are evaluated in different ways, described below. The
88 remaining list elements constitute the "arguments" for the function,
89 macro, or special form.
91 The first step in evaluating a nonempty list is to examine its first
92 element. This element alone determines what kind of form the list is
93 and how the rest of the list is to be processed. The first element is
94 _not_ evaluated, as it would be in some Lisp dialects such as Scheme.
97 File: lispref.info, Node: Function Indirection, Next: Function Forms, Prev: Classifying Lists, Up: Forms
99 Symbol Function Indirection
100 ---------------------------
102 If the first element of the list is a symbol then evaluation examines
103 the symbol's function cell, and uses its contents instead of the
104 original symbol. If the contents are another symbol, this process,
105 called "symbol function indirection", is repeated until it obtains a
106 non-symbol. *Note Function Names::, for more information about using a
107 symbol as a name for a function stored in the function cell of the
110 One possible consequence of this process is an infinite loop, in the
111 event that a symbol's function cell refers to the same symbol. Or a
112 symbol may have a void function cell, in which case the subroutine
113 `symbol-function' signals a `void-function' error. But if neither of
114 these things happens, we eventually obtain a non-symbol, which ought to
115 be a function or other suitable object.
117 More precisely, we should now have a Lisp function (a lambda
118 expression), a byte-code function, a primitive function, a Lisp macro, a
119 special form, or an autoload object. Each of these types is a case
120 described in one of the following sections. If the object is not one of
121 these types, the error `invalid-function' is signaled.
123 The following example illustrates the symbol indirection process. We
124 use `fset' to set the function cell of a symbol and `symbol-function'
125 to get the function cell contents (*note Function Cells::).
126 Specifically, we store the symbol `car' into the function cell of
127 `first', and the symbol `first' into the function cell of `erste'.
129 ;; Build this function cell linkage:
130 ;; ------------- ----- ------- -------
131 ;; | #<subr car> | <-- | car | <-- | first | <-- | erste |
132 ;; ------------- ----- ------- -------
134 (symbol-function 'car)
140 (erste '(1 2 3)) ; Call the function referenced by `erste'.
143 By contrast, the following example calls a function without any
144 symbol function indirection, because the first element is an anonymous
145 Lisp function, not a symbol.
147 ((lambda (arg) (erste arg))
151 Executing the function itself evaluates its body; this does involve
152 symbol function indirection when calling `erste'.
154 The built-in function `indirect-function' provides an easy way to
155 perform symbol function indirection explicitly.
157 - Function: indirect-function function
158 This function returns the meaning of FUNCTION as a function. If
159 FUNCTION is a symbol, then it finds FUNCTION's function definition
160 and starts over with that value. If FUNCTION is not a symbol,
161 then it returns FUNCTION itself.
163 Here is how you could define `indirect-function' in Lisp:
165 (defun indirect-function (function)
166 (if (symbolp function)
167 (indirect-function (symbol-function function))
171 File: lispref.info, Node: Function Forms, Next: Macro Forms, Prev: Function Indirection, Up: Forms
173 Evaluation of Function Forms
174 ----------------------------
176 If the first element of a list being evaluated is a Lisp function
177 object, byte-code object or primitive function object, then that list is
178 a "function call". For example, here is a call to the function `+':
182 The first step in evaluating a function call is to evaluate the
183 remaining elements of the list from left to right. The results are the
184 actual argument values, one value for each list element. The next step
185 is to call the function with this list of arguments, effectively using
186 the function `apply' (*note Calling Functions::). If the function is
187 written in Lisp, the arguments are used to bind the argument variables
188 of the function (*note Lambda Expressions::); then the forms in the
189 function body are evaluated in order, and the value of the last body
190 form becomes the value of the function call.
193 File: lispref.info, Node: Macro Forms, Next: Special Forms, Prev: Function Forms, Up: Forms
195 Lisp Macro Evaluation
196 ---------------------
198 If the first element of a list being evaluated is a macro object,
199 then the list is a "macro call". When a macro call is evaluated, the
200 elements of the rest of the list are _not_ initially evaluated.
201 Instead, these elements themselves are used as the arguments of the
202 macro. The macro definition computes a replacement form, called the
203 "expansion" of the macro, to be evaluated in place of the original
204 form. The expansion may be any sort of form: a self-evaluating
205 constant, a symbol, or a list. If the expansion is itself a macro call,
206 this process of expansion repeats until some other sort of form results.
208 Ordinary evaluation of a macro call finishes by evaluating the
209 expansion. However, the macro expansion is not necessarily evaluated
210 right away, or at all, because other programs also expand macro calls,
211 and they may or may not evaluate the expansions.
213 Normally, the argument expressions are not evaluated as part of
214 computing the macro expansion, but instead appear as part of the
215 expansion, so they are computed when the expansion is computed.
217 For example, given a macro defined as follows:
220 (list 'car (list 'cdr x)))
222 an expression such as `(cadr (assq 'handler list))' is a macro call,
223 and its expansion is:
225 (car (cdr (assq 'handler list)))
227 Note that the argument `(assq 'handler list)' appears in the expansion.
229 *Note Macros::, for a complete description of XEmacs Lisp macros.
232 File: lispref.info, Node: Special Forms, Next: Autoloading, Prev: Macro Forms, Up: Forms
237 A "special form" is a primitive function specially marked so that
238 its arguments are not all evaluated. Most special forms define control
239 structures or perform variable bindings--things which functions cannot
242 Each special form has its own rules for which arguments are evaluated
243 and which are used without evaluation. Whether a particular argument is
244 evaluated may depend on the results of evaluating other arguments.
246 Here is a list, in alphabetical order, of all of the special forms in
247 XEmacs Lisp with a reference to where each is described.
250 *note Combining Conditions::
253 *note Catch and Throw::
259 *note Handling Errors::
262 *note Defining Variables::
265 *note Defining Macros::
268 *note Defining Functions::
271 *note Defining Variables::
274 *note Anonymous Functions::
280 *note Interactive Call::
284 *note Local Variables::
287 *note Combining Conditions::
297 `save-current-buffer'
306 `save-selected-window'
309 `save-window-excursion'
310 *note Window Configurations::
313 *note Setting Variables::
316 *note Creating Buffer-Local::
319 *note Nonlocal Exits::
324 `with-output-to-temp-buffer'
325 *note Temporary Displays::
327 Common Lisp note: here are some comparisons of special forms in
328 XEmacs Lisp and Common Lisp. `setq', `if', and `catch' are
329 special forms in both XEmacs Lisp and Common Lisp. `defun' is a
330 special form in XEmacs Lisp, but a macro in Common Lisp.
331 `save-excursion' is a special form in XEmacs Lisp, but doesn't
332 exist in Common Lisp. `throw' is a special form in Common Lisp
333 (because it must be able to throw multiple values), but it is a
334 function in XEmacs Lisp (which doesn't have multiple values).
337 File: lispref.info, Node: Autoloading, Prev: Special Forms, Up: Forms
342 The "autoload" feature allows you to call a function or macro whose
343 function definition has not yet been loaded into XEmacs. It specifies
344 which file contains the definition. When an autoload object appears as
345 a symbol's function definition, calling that symbol as a function
346 automatically loads the specified file; then it calls the real
347 definition loaded from that file. *Note Autoload::.
350 File: lispref.info, Node: Quoting, Prev: Forms, Up: Evaluation
355 The special form `quote' returns its single argument, as written,
356 without evaluating it. This provides a way to include constant symbols
357 and lists, which are not self-evaluating objects, in a program. (It is
358 not necessary to quote self-evaluating objects such as numbers, strings,
361 - Special Form: quote object
362 This special form returns OBJECT, without evaluating it.
364 Because `quote' is used so often in programs, Lisp provides a
365 convenient read syntax for it. An apostrophe character (`'') followed
366 by a Lisp object (in read syntax) expands to a list whose first element
367 is `quote', and whose second element is the object. Thus, the read
368 syntax `'x' is an abbreviation for `(quote x)'.
370 Here are some examples of expressions that use `quote':
385 Other quoting constructs include `function' (*note Anonymous
386 Functions::), which causes an anonymous lambda expression written in
387 Lisp to be compiled, and ``' (*note Backquote::), which is used to quote
388 only part of a list, while computing and substituting other parts.
391 File: lispref.info, Node: Control Structures, Next: Variables, Prev: Evaluation, Up: Top
396 A Lisp program consists of expressions or "forms" (*note Forms::).
397 We control the order of execution of the forms by enclosing them in
398 "control structures". Control structures are special forms which
399 control when, whether, or how many times to execute the forms they
402 The simplest order of execution is sequential execution: first form
403 A, then form B, and so on. This is what happens when you write several
404 forms in succession in the body of a function, or at top level in a
405 file of Lisp code--the forms are executed in the order written. We
406 call this "textual order". For example, if a function body consists of
407 two forms A and B, evaluation of the function evaluates first A and
408 then B, and the function's value is the value of B.
410 Explicit control structures make possible an order of execution other
413 XEmacs Lisp provides several kinds of control structure, including
414 other varieties of sequencing, conditionals, iteration, and (controlled)
415 jumps--all discussed below. The built-in control structures are
416 special forms since their subforms are not necessarily evaluated or not
417 evaluated sequentially. You can use macros to define your own control
418 structure constructs (*note Macros::).
422 * Sequencing:: Evaluation in textual order.
423 * Conditionals:: `if', `cond'.
424 * Combining Conditions:: `and', `or', `not'.
425 * Iteration:: `while' loops.
426 * Nonlocal Exits:: Jumping out of a sequence.
429 File: lispref.info, Node: Sequencing, Next: Conditionals, Up: Control Structures
434 Evaluating forms in the order they appear is the most common way
435 control passes from one form to another. In some contexts, such as in a
436 function body, this happens automatically. Elsewhere you must use a
437 control structure construct to do this: `progn', the simplest control
440 A `progn' special form looks like this:
444 and it says to execute the forms A, B, C and so on, in that order.
445 These forms are called the body of the `progn' form. The value of the
446 last form in the body becomes the value of the entire `progn'.
448 In the early days of Lisp, `progn' was the only way to execute two
449 or more forms in succession and use the value of the last of them. But
450 programmers found they often needed to use a `progn' in the body of a
451 function, where (at that time) only one form was allowed. So the body
452 of a function was made into an "implicit `progn'": several forms are
453 allowed just as in the body of an actual `progn'. Many other control
454 structures likewise contain an implicit `progn'. As a result, `progn'
455 is not used as often as it used to be. It is needed now most often
456 inside an `unwind-protect', `and', `or', or in the THEN-part of an `if'.
458 - Special Form: progn forms...
459 This special form evaluates all of the FORMS, in textual order,
460 returning the result of the final form.
462 (progn (print "The first form")
463 (print "The second form")
464 (print "The third form"))
470 Two other control constructs likewise evaluate a series of forms but
471 return a different value:
473 - Special Form: prog1 form1 forms...
474 This special form evaluates FORM1 and all of the FORMS, in textual
475 order, returning the result of FORM1.
477 (prog1 (print "The first form")
478 (print "The second form")
479 (print "The third form"))
485 Here is a way to remove the first element from a list in the
486 variable `x', then return the value of that former element:
488 (prog1 (car x) (setq x (cdr x)))
490 - Special Form: prog2 form1 form2 forms...
491 This special form evaluates FORM1, FORM2, and all of the following
492 FORMS, in textual order, returning the result of FORM2.
494 (prog2 (print "The first form")
495 (print "The second form")
496 (print "The third form"))
503 File: lispref.info, Node: Conditionals, Next: Combining Conditions, Prev: Sequencing, Up: Control Structures
508 Conditional control structures choose among alternatives. XEmacs
509 Lisp has two conditional forms: `if', which is much the same as in other
510 languages, and `cond', which is a generalized case statement.
512 - Special Form: if condition then-form else-forms...
513 `if' chooses between the THEN-FORM and the ELSE-FORMS based on the
514 value of CONDITION. If the evaluated CONDITION is non-`nil',
515 THEN-FORM is evaluated and the result returned. Otherwise, the
516 ELSE-FORMS are evaluated in textual order, and the value of the
517 last one is returned. (The ELSE part of `if' is an example of an
518 implicit `progn'. *Note Sequencing::.)
520 If CONDITION has the value `nil', and no ELSE-FORMS are given,
523 `if' is a special form because the branch that is not selected is
524 never evaluated--it is ignored. Thus, in the example below,
525 `true' is not printed because `print' is never called.
532 - Special Form: cond clause...
533 `cond' chooses among an arbitrary number of alternatives. Each
534 CLAUSE in the `cond' must be a list. The CAR of this list is the
535 CONDITION; the remaining elements, if any, the BODY-FORMS. Thus,
536 a clause looks like this:
538 (CONDITION BODY-FORMS...)
540 `cond' tries the clauses in textual order, by evaluating the
541 CONDITION of each clause. If the value of CONDITION is non-`nil',
542 the clause "succeeds"; then `cond' evaluates its BODY-FORMS, and
543 the value of the last of BODY-FORMS becomes the value of the
544 `cond'. The remaining clauses are ignored.
546 If the value of CONDITION is `nil', the clause "fails", so the
547 `cond' moves on to the following clause, trying its CONDITION.
549 If every CONDITION evaluates to `nil', so that every clause fails,
550 `cond' returns `nil'.
552 A clause may also look like this:
556 Then, if CONDITION is non-`nil' when tested, the value of
557 CONDITION becomes the value of the `cond' form.
559 The following example has four clauses, which test for the cases
560 where the value of `x' is a number, string, buffer and symbol,
563 (cond ((numberp x) x)
566 (setq temporary-hack x) ; multiple body-forms
567 (buffer-name x)) ; in one clause
568 ((symbolp x) (symbol-value x)))
570 Often we want to execute the last clause whenever none of the
571 previous clauses was successful. To do this, we use `t' as the
572 CONDITION of the last clause, like this: `(t BODY-FORMS)'. The
573 form `t' evaluates to `t', which is never `nil', so this clause
574 never fails, provided the `cond' gets to it at all.
578 (cond ((eq a 'hack) 'foo)
582 This expression is a `cond' which returns `foo' if the value of
583 `a' is 1, and returns the string `"default"' otherwise.
585 Any conditional construct can be expressed with `cond' or with `if'.
586 Therefore, the choice between them is a matter of style. For example:
593 File: lispref.info, Node: Combining Conditions, Next: Iteration, Prev: Conditionals, Up: Control Structures
595 Constructs for Combining Conditions
596 ===================================
598 This section describes three constructs that are often used together
599 with `if' and `cond' to express complicated conditions. The constructs
600 `and' and `or' can also be used individually as kinds of multiple
601 conditional constructs.
603 - Function: not condition
604 This function tests for the falsehood of CONDITION. It returns
605 `t' if CONDITION is `nil', and `nil' otherwise. The function
606 `not' is identical to `null', and we recommend using the name
607 `null' if you are testing for an empty list.
609 - Special Form: and conditions...
610 The `and' special form tests whether all the CONDITIONS are true.
611 It works by evaluating the CONDITIONS one by one in the order
614 If any of the CONDITIONS evaluates to `nil', then the result of
615 the `and' must be `nil' regardless of the remaining CONDITIONS; so
616 `and' returns right away, ignoring the remaining CONDITIONS.
618 If all the CONDITIONS turn out non-`nil', then the value of the
619 last of them becomes the value of the `and' form.
621 Here is an example. The first condition returns the integer 1,
622 which is not `nil'. Similarly, the second condition returns the
623 integer 2, which is not `nil'. The third condition is `nil', so
624 the remaining condition is never evaluated.
626 (and (print 1) (print 2) nil (print 3))
631 Here is a more realistic example of using `and':
633 (if (and (consp foo) (eq (car foo) 'x))
634 (message "foo is a list starting with x"))
636 Note that `(car foo)' is not executed if `(consp foo)' returns
637 `nil', thus avoiding an error.
639 `and' can be expressed in terms of either `if' or `cond'. For
644 (if ARG1 (if ARG2 ARG3))
646 (cond (ARG1 (cond (ARG2 ARG3))))
648 - Special Form: or conditions...
649 The `or' special form tests whether at least one of the CONDITIONS
650 is true. It works by evaluating all the CONDITIONS one by one in
653 If any of the CONDITIONS evaluates to a non-`nil' value, then the
654 result of the `or' must be non-`nil'; so `or' returns right away,
655 ignoring the remaining CONDITIONS. The value it returns is the
656 non-`nil' value of the condition just evaluated.
658 If all the CONDITIONS turn out `nil', then the `or' expression
661 For example, this expression tests whether `x' is either 0 or
664 (or (eq x nil) (eq x 0))
666 Like the `and' construct, `or' can be written in terms of `cond'.
675 You could almost write `or' in terms of `if', but not quite:
681 This is not completely equivalent because it can evaluate ARG1 or
682 ARG2 twice. By contrast, `(or ARG1 ARG2 ARG3)' never evaluates
683 any argument more than once.
686 File: lispref.info, Node: Iteration, Next: Nonlocal Exits, Prev: Combining Conditions, Up: Control Structures
691 Iteration means executing part of a program repetitively. For
692 example, you might want to repeat some computation once for each element
693 of a list, or once for each integer from 0 to N. You can do this in
694 XEmacs Lisp with the special form `while':
696 - Special Form: while condition forms...
697 `while' first evaluates CONDITION. If the result is non-`nil', it
698 evaluates FORMS in textual order. Then it reevaluates CONDITION,
699 and if the result is non-`nil', it evaluates FORMS again. This
700 process repeats until CONDITION evaluates to `nil'.
702 There is no limit on the number of iterations that may occur. The
703 loop will continue until either CONDITION evaluates to `nil' or
704 until an error or `throw' jumps out of it (*note Nonlocal Exits::).
706 The value of a `while' form is always `nil'.
711 (princ (format "Iteration %d." num))
719 If you would like to execute something on each iteration before the
720 end-test, put it together with the end-test in a `progn' as the
721 first argument of `while', as shown here:
725 (not (looking-at "^$"))))
727 This moves forward one line and continues moving by lines until it
728 reaches an empty. It is unusual in that the `while' has no body,
729 just the end test (which also does the real work of moving point).
732 File: lispref.info, Node: Nonlocal Exits, Prev: Iteration, Up: Control Structures
737 A "nonlocal exit" is a transfer of control from one point in a
738 program to another remote point. Nonlocal exits can occur in XEmacs
739 Lisp as a result of errors; you can also use them under explicit
740 control. Nonlocal exits unbind all variable bindings made by the
741 constructs being exited.
745 * Catch and Throw:: Nonlocal exits for the program's own purposes.
746 * Examples of Catch:: Showing how such nonlocal exits can be written.
747 * Errors:: How errors are signaled and handled.
748 * Cleanups:: Arranging to run a cleanup form if an error happens.
751 File: lispref.info, Node: Catch and Throw, Next: Examples of Catch, Up: Nonlocal Exits
753 Explicit Nonlocal Exits: `catch' and `throw'
754 --------------------------------------------
756 Most control constructs affect only the flow of control within the
757 construct itself. The function `throw' is the exception to this rule
758 of normal program execution: it performs a nonlocal exit on request.
759 (There are other exceptions, but they are for error handling only.)
760 `throw' is used inside a `catch', and jumps back to that `catch'. For
769 The `throw' transfers control straight back to the corresponding
770 `catch', which returns immediately. The code following the `throw' is
771 not executed. The second argument of `throw' is used as the return
772 value of the `catch'.
774 The `throw' and the `catch' are matched through the first argument:
775 `throw' searches for a `catch' whose first argument is `eq' to the one
776 specified. Thus, in the above example, the `throw' specifies `foo',
777 and the `catch' specifies the same symbol, so that `catch' is
778 applicable. If there is more than one applicable `catch', the
779 innermost one takes precedence.
781 Executing `throw' exits all Lisp constructs up to the matching
782 `catch', including function calls. When binding constructs such as
783 `let' or function calls are exited in this way, the bindings are
784 unbound, just as they are when these constructs exit normally (*note
785 Local Variables::). Likewise, `throw' restores the buffer and position
786 saved by `save-excursion' (*note Excursions::), and the narrowing
787 status saved by `save-restriction' and the window selection saved by
788 `save-window-excursion' (*note Window Configurations::). It also runs
789 any cleanups established with the `unwind-protect' special form when it
790 exits that form (*note Cleanups::).
792 The `throw' need not appear lexically within the `catch' that it
793 jumps to. It can equally well be called from another function called
794 within the `catch'. As long as the `throw' takes place chronologically
795 after entry to the `catch', and chronologically before exit from it, it
796 has access to that `catch'. This is why `throw' can be used in
797 commands such as `exit-recursive-edit' that throw back to the editor
798 command loop (*note Recursive Editing::).
800 Common Lisp note: Most other versions of Lisp, including Common
801 Lisp, have several ways of transferring control nonsequentially:
802 `return', `return-from', and `go', for example. XEmacs Lisp has
805 - Special Form: catch tag body...
806 `catch' establishes a return point for the `throw' function. The
807 return point is distinguished from other such return points by TAG,
808 which may be any Lisp object. The argument TAG is evaluated
809 normally before the return point is established.
811 With the return point in effect, `catch' evaluates the forms of the
812 BODY in textual order. If the forms execute normally, without
813 error or nonlocal exit, the value of the last body form is
814 returned from the `catch'.
816 If a `throw' is done within BODY specifying the same value TAG,
817 the `catch' exits immediately; the value it returns is whatever
818 was specified as the second argument of `throw'.
820 - Function: throw tag value
821 The purpose of `throw' is to return from a return point previously
822 established with `catch'. The argument TAG is used to choose
823 among the various existing return points; it must be `eq' to the
824 value specified in the `catch'. If multiple return points match
825 TAG, the innermost one is used.
827 The argument VALUE is used as the value to return from that
830 If no return point is in effect with tag TAG, then a `no-catch'
831 error is signaled with data `(TAG VALUE)'.
834 File: lispref.info, Node: Examples of Catch, Next: Errors, Prev: Catch and Throw, Up: Nonlocal Exits
836 Examples of `catch' and `throw'
837 -------------------------------
839 One way to use `catch' and `throw' is to exit from a doubly nested
840 loop. (In most languages, this would be done with a "go to".) Here we
841 compute `(foo I J)' for I and J varying from 0 to 9:
850 (throw 'loop (list i j)))
854 If `foo' ever returns non-`nil', we stop immediately and return a list
855 of I and J. If `foo' always returns `nil', the `catch' returns
856 normally, and the value is `nil', since that is the result of the
859 Here are two tricky examples, slightly different, showing two return
860 points at once. First, two return points with the same tag, `hack':
868 (print (catch2 'hack))
873 Since both return points have tags that match the `throw', it goes to
874 the inner one, the one established in `catch2'. Therefore, `catch2'
875 returns normally with value `yes', and this value is printed. Finally
876 the second body form in the outer `catch', which is `'no', is evaluated
877 and returned from the outer `catch'.
879 Now let's change the argument given to `catch2':
887 (print (catch2 'quux))
891 We still have two return points, but this time only the outer one has
892 the tag `hack'; the inner one has the tag `quux' instead. Therefore,
893 `throw' makes the outer `catch' return the value `yes'. The function
894 `print' is never called, and the body-form `'no' is never evaluated.
897 File: lispref.info, Node: Errors, Next: Cleanups, Prev: Examples of Catch, Up: Nonlocal Exits
902 When XEmacs Lisp attempts to evaluate a form that, for some reason,
903 cannot be evaluated, it "signals" an "error".
905 When an error is signaled, XEmacs's default reaction is to print an
906 error message and terminate execution of the current command. This is
907 the right thing to do in most cases, such as if you type `C-f' at the
910 In complicated programs, simple termination may not be what you want.
911 For example, the program may have made temporary changes in data
912 structures, or created temporary buffers that should be deleted before
913 the program is finished. In such cases, you would use `unwind-protect'
914 to establish "cleanup expressions" to be evaluated in case of error.
915 (*Note Cleanups::.) Occasionally, you may wish the program to continue
916 execution despite an error in a subroutine. In these cases, you would
917 use `condition-case' to establish "error handlers" to recover control
920 Resist the temptation to use error handling to transfer control from
921 one part of the program to another; use `catch' and `throw' instead.
922 *Note Catch and Throw::.
926 * Signaling Errors:: How to report an error.
927 * Processing of Errors:: What XEmacs does when you report an error.
928 * Handling Errors:: How you can trap errors and continue execution.
929 * Error Symbols:: How errors are classified for trapping them.
932 File: lispref.info, Node: Signaling Errors, Next: Processing of Errors, Up: Errors
934 How to Signal an Error
935 ......................
937 Most errors are signaled "automatically" within Lisp primitives
938 which you call for other purposes, such as if you try to take the CAR
939 of an integer or move forward a character at the end of the buffer; you
940 can also signal errors explicitly with the functions `error', `signal',
943 Quitting, which happens when the user types `C-g', is not considered
944 an error, but it is handled almost like an error. *Note Quitting::.
946 - Function: error format-string &rest args
947 This function signals an error with an error message constructed by
948 applying `format' (*note String Conversion::) to FORMAT-STRING and
951 This error is not continuable: you cannot continue execution after
952 the error using the debugger `r' or `c' commands. If you wish the
953 user to be able to continue execution, use `cerror' or `signal'
956 These examples show typical uses of `error':
958 (error "You have committed an error.
959 Try something else.")
960 error--> You have committed an error.
963 (error "You have committed %d errors." 10)
964 error--> You have committed 10 errors.
966 `error' works by calling `signal' with two arguments: the error
967 symbol `error', and a list containing the string returned by
968 `format'. This is repeated in an endless loop, to ensure that
969 `error' never returns.
971 If you want to use your own string as an error message verbatim,
972 don't just write `(error STRING)'. If STRING contains `%', it
973 will be interpreted as a format specifier, with undesirable
974 results. Instead, use `(error "%s" STRING)'.
976 - Function: cerror format-string &rest args
977 This function behaves like `error', except that the error it
978 signals is continuable. That means that debugger commands `c' and
979 `r' can resume execution.
981 - Function: signal error-symbol data
982 This function signals a continuable error named by ERROR-SYMBOL.
983 The argument DATA is a list of additional Lisp objects relevant to
984 the circumstances of the error.
986 The argument ERROR-SYMBOL must be an "error symbol"--a symbol
987 bearing a property `error-conditions' whose value is a list of
988 condition names. This is how XEmacs Lisp classifies different
991 The number and significance of the objects in DATA depends on
992 ERROR-SYMBOL. For example, with a `wrong-type-argument' error,
993 there are two objects in the list: a predicate that describes the
994 type that was expected, and the object that failed to fit that
995 type. *Note Error Symbols::, for a description of error symbols.
997 Both ERROR-SYMBOL and DATA are available to any error handlers
998 that handle the error: `condition-case' binds a local variable to
999 a list of the form `(ERROR-SYMBOL . DATA)' (*note Handling
1000 Errors::). If the error is not handled, these two values are used
1001 in printing the error message.
1003 The function `signal' can return, if the debugger is invoked and
1004 the user invokes the "return from signal" option. If you want the
1005 error not to be continuable, use `signal-error' instead. Note that
1006 in FSF Emacs `signal' never returns.
1008 (signal 'wrong-number-of-arguments '(x y))
1009 error--> Wrong number of arguments: x, y
1011 (signal 'no-such-error '("My unknown error condition"))
1012 error--> Peculiar error (no-such-error "My unknown error condition")
1014 - Function: signal-error error-symbol data
1015 This function behaves like `signal', except that the error it
1016 signals is not continuable.
1018 - Macro: check-argument-type predicate argument
1019 This macro checks that ARGUMENT satisfies PREDICATE. If that is
1020 not the case, it signals a continuable `wrong-type-argument' error
1021 until the returned value satisfies PREDICATE, and assigns the
1022 returned value to ARGUMENT. In other words, execution of the
1023 program will not continue until PREDICATE is met.
1025 ARGUMENT is not evaluated, and should be a symbol. PREDICATE is
1026 evaluated, and should name a function.
1028 As shown in the following example, `check-argument-type' is useful
1029 in low-level code that attempts to ensure the sanity of its data
1032 (defun cache-object-internal (object wlist)
1033 ;; Before doing anything, make sure that WLIST is indeed
1034 ;; a weak list, which is what we expect.
1035 (check-argument-type 'weak-list-p wlist)
1039 File: lispref.info, Node: Processing of Errors, Next: Handling Errors, Prev: Signaling Errors, Up: Errors
1041 How XEmacs Processes Errors
1042 ...........................
1044 When an error is signaled, `signal' searches for an active "handler"
1045 for the error. A handler is a sequence of Lisp expressions designated
1046 to be executed if an error happens in part of the Lisp program. If the
1047 error has an applicable handler, the handler is executed, and control
1048 resumes following the handler. The handler executes in the environment
1049 of the `condition-case' that established it; all functions called
1050 within that `condition-case' have already been exited, and the handler
1051 cannot return to them.
1053 If there is no applicable handler for the error, the current command
1054 is terminated and control returns to the editor command loop, because
1055 the command loop has an implicit handler for all kinds of errors. The
1056 command loop's handler uses the error symbol and associated data to
1057 print an error message.
1059 Errors in command loop are processed using the `command-error'
1060 function, which takes care of some necessary cleanup, and prints a
1061 formatted error message to the echo area. The functions that do the
1062 formatting are explained below.
1064 - Function: display-error error-object stream
1065 This function displays ERROR-OBJECT on STREAM. ERROR-OBJECT is a
1066 cons of error type, a symbol, and error arguments, a list. If the
1067 error type symbol of one of its error condition superclasses has
1068 an `display-error' property, that function is invoked for printing
1069 the actual error message. Otherwise, the error is printed as
1070 `Error: arg1, arg2, ...'.
1072 - Function: error-message-string error-object
1073 This function converts ERROR-OBJECT to an error message string,
1074 and returns it. The message is equivalent to the one that would be
1075 printed by `display-error', except that it is conveniently returned
1078 An error that has no explicit handler may call the Lisp debugger.
1079 The debugger is enabled if the variable `debug-on-error' (*note Error
1080 Debugging::) is non-`nil'. Unlike error handlers, the debugger runs in
1081 the environment of the error, so that you can examine values of
1082 variables precisely as they were at the time of the error.
1085 File: lispref.info, Node: Handling Errors, Next: Error Symbols, Prev: Processing of Errors, Up: Errors
1087 Writing Code to Handle Errors
1088 .............................
1090 The usual effect of signaling an error is to terminate the command
1091 that is running and return immediately to the XEmacs editor command
1092 loop. You can arrange to trap errors occurring in a part of your
1093 program by establishing an error handler, with the special form
1094 `condition-case'. A simple example looks like this:
1097 (delete-file filename)
1100 This deletes the file named FILENAME, catching any error and returning
1101 `nil' if an error occurs.
1103 The second argument of `condition-case' is called the "protected
1104 form". (In the example above, the protected form is a call to
1105 `delete-file'.) The error handlers go into effect when this form
1106 begins execution and are deactivated when this form returns. They
1107 remain in effect for all the intervening time. In particular, they are
1108 in effect during the execution of functions called by this form, in
1109 their subroutines, and so on. This is a good thing, since, strictly
1110 speaking, errors can be signaled only by Lisp primitives (including
1111 `signal' and `error') called by the protected form, not by the
1112 protected form itself.
1114 The arguments after the protected form are handlers. Each handler
1115 lists one or more "condition names" (which are symbols) to specify
1116 which errors it will handle. The error symbol specified when an error
1117 is signaled also defines a list of condition names. A handler applies
1118 to an error if they have any condition names in common. In the example
1119 above, there is one handler, and it specifies one condition name,
1120 `error', which covers all errors.
1122 The search for an applicable handler checks all the established
1123 handlers starting with the most recently established one. Thus, if two
1124 nested `condition-case' forms offer to handle the same error, the inner
1125 of the two will actually handle it.
1127 When an error is handled, control returns to the handler. Before
1128 this happens, XEmacs unbinds all variable bindings made by binding
1129 constructs that are being exited and executes the cleanups of all
1130 `unwind-protect' forms that are exited. Once control arrives at the
1131 handler, the body of the handler is executed.
1133 After execution of the handler body, execution continues by returning
1134 from the `condition-case' form. Because the protected form is exited
1135 completely before execution of the handler, the handler cannot resume
1136 execution at the point of the error, nor can it examine variable
1137 bindings that were made within the protected form. All it can do is
1138 clean up and proceed.
1140 `condition-case' is often used to trap errors that are predictable,
1141 such as failure to open a file in a call to `insert-file-contents'. It
1142 is also used to trap errors that are totally unpredictable, such as
1143 when the program evaluates an expression read from the user.
1145 Even when an error is handled, the debugger may still be called if
1146 the variable `debug-on-signal' (*note Error Debugging::) is non-`nil'.
1147 Note that this may yield unpredictable results with code that traps
1148 expected errors as normal part of its operation. Do not set
1149 `debug-on-signal' unless you know what you are doing.
1151 Error signaling and handling have some resemblance to `throw' and
1152 `catch', but they are entirely separate facilities. An error cannot be
1153 caught by a `catch', and a `throw' cannot be handled by an error
1154 handler (though using `throw' when there is no suitable `catch' signals
1155 an error that can be handled).
1157 - Special Form: condition-case var protected-form handlers...
1158 This special form establishes the error handlers HANDLERS around
1159 the execution of PROTECTED-FORM. If PROTECTED-FORM executes
1160 without error, the value it returns becomes the value of the
1161 `condition-case' form; in this case, the `condition-case' has no
1162 effect. The `condition-case' form makes a difference when an
1163 error occurs during PROTECTED-FORM.
1165 Each of the HANDLERS is a list of the form `(CONDITIONS BODY...)'.
1166 Here CONDITIONS is an error condition name to be handled, or a
1167 list of condition names; BODY is one or more Lisp expressions to
1168 be executed when this handler handles an error. Here are examples
1173 (arith-error (message "Division by zero"))
1175 ((arith-error file-error)
1177 "Either division by zero or failure to open a file"))
1179 Each error that occurs has an "error symbol" that describes what
1180 kind of error it is. The `error-conditions' property of this
1181 symbol is a list of condition names (*note Error Symbols::). Emacs
1182 searches all the active `condition-case' forms for a handler that
1183 specifies one or more of these condition names; the innermost
1184 matching `condition-case' handles the error. Within this
1185 `condition-case', the first applicable handler handles the error.
1187 After executing the body of the handler, the `condition-case'
1188 returns normally, using the value of the last form in the handler
1189 body as the overall value.
1191 The argument VAR is a variable. `condition-case' does not bind
1192 this variable when executing the PROTECTED-FORM, only when it
1193 handles an error. At that time, it binds VAR locally to a list of
1194 the form `(ERROR-SYMBOL . DATA)', giving the particulars of the
1195 error. The handler can refer to this list to decide what to do.
1196 For example, if the error is for failure opening a file, the file
1197 name is the second element of DATA--the third element of VAR.
1199 If VAR is `nil', that means no variable is bound. Then the error
1200 symbol and associated data are not available to the handler.
1202 Here is an example of using `condition-case' to handle the error
1203 that results from dividing by zero. The handler prints out a warning
1204 message and returns a very large number.
1206 (defun safe-divide (dividend divisor)
1209 (/ dividend divisor)
1211 (arith-error ; Condition.
1212 (princ (format "Arithmetic error: %s" err))
1217 -| Arithmetic error: (arith-error)
1220 The handler specifies condition name `arith-error' so that it will
1221 handle only division-by-zero errors. Other kinds of errors will not be
1222 handled, at least not by this `condition-case'. Thus,
1225 error--> Wrong type argument: integer-or-marker-p, nil
1227 Here is a `condition-case' that catches all kinds of errors,
1228 including those signaled with `error':
1236 ;; This is a call to the function `error'.
1237 (error "Rats! The variable %s was %s, not 35" 'baz baz))
1238 ;; This is the handler; it is not a form.
1239 (error (princ (format "The error was: %s" err))
1241 -| The error was: (error "Rats! The variable baz was 34, not 35")
projects / chise / xemacs-chise.git.1 / blob