2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/control.info
6 @node Control Structures, Variables, Evaluation, Top
7 @chapter Control Structures
8 @cindex special forms for control structures
9 @cindex control structures
11 A Lisp program consists of expressions or @dfn{forms} (@pxref{Forms}).
12 We control the order of execution of the forms by enclosing them in
13 @dfn{control structures}. Control structures are special forms which
14 control when, whether, or how many times to execute the forms they
17 The simplest order of execution is sequential execution: first form
18 @var{a}, then form @var{b}, and so on. This is what happens when you
19 write several forms in succession in the body of a function, or at top
20 level in a file of Lisp code---the forms are executed in the order
21 written. We call this @dfn{textual order}. For example, if a function
22 body consists of two forms @var{a} and @var{b}, evaluation of the
23 function evaluates first @var{a} and then @var{b}, and the function's
24 value is the value of @var{b}.
26 Explicit control structures make possible an order of execution other
29 XEmacs Lisp provides several kinds of control structure, including
30 other varieties of sequencing, conditionals, iteration, and (controlled)
31 jumps---all discussed below. The built-in control structures are
32 special forms since their subforms are not necessarily evaluated or not
33 evaluated sequentially. You can use macros to define your own control
34 structure constructs (@pxref{Macros}).
37 * Sequencing:: Evaluation in textual order.
38 * Conditionals:: @code{if}, @code{cond}.
39 * Combining Conditions:: @code{and}, @code{or}, @code{not}.
40 * Iteration:: @code{while} loops.
41 * Nonlocal Exits:: Jumping out of a sequence.
47 Evaluating forms in the order they appear is the most common way
48 control passes from one form to another. In some contexts, such as in a
49 function body, this happens automatically. Elsewhere you must use a
50 control structure construct to do this: @code{progn}, the simplest
51 control construct of Lisp.
53 A @code{progn} special form looks like this:
57 (progn @var{a} @var{b} @var{c} @dots{})
62 and it says to execute the forms @var{a}, @var{b}, @var{c} and so on, in
63 that order. These forms are called the body of the @code{progn} form.
64 The value of the last form in the body becomes the value of the entire
67 @cindex implicit @code{progn}
68 In the early days of Lisp, @code{progn} was the only way to execute
69 two or more forms in succession and use the value of the last of them.
70 But programmers found they often needed to use a @code{progn} in the
71 body of a function, where (at that time) only one form was allowed. So
72 the body of a function was made into an ``implicit @code{progn}'':
73 several forms are allowed just as in the body of an actual @code{progn}.
74 Many other control structures likewise contain an implicit @code{progn}.
75 As a result, @code{progn} is not used as often as it used to be. It is
76 needed now most often inside an @code{unwind-protect}, @code{and},
77 @code{or}, or in the @var{then}-part of an @code{if}.
79 @defspec progn forms@dots{}
80 This special form evaluates all of the @var{forms}, in textual
81 order, returning the result of the final form.
85 (progn (print "The first form")
86 (print "The second form")
87 (print "The third form"))
88 @print{} "The first form"
89 @print{} "The second form"
90 @print{} "The third form"
91 @result{} "The third form"
96 Two other control constructs likewise evaluate a series of forms but return
99 @defspec prog1 form1 forms@dots{}
100 This special form evaluates @var{form1} and all of the @var{forms}, in
101 textual order, returning the result of @var{form1}.
105 (prog1 (print "The first form")
106 (print "The second form")
107 (print "The third form"))
108 @print{} "The first form"
109 @print{} "The second form"
110 @print{} "The third form"
111 @result{} "The first form"
115 Here is a way to remove the first element from a list in the variable
116 @code{x}, then return the value of that former element:
119 (prog1 (car x) (setq x (cdr x)))
123 @defspec prog2 form1 form2 forms@dots{}
124 This special form evaluates @var{form1}, @var{form2}, and all of the
125 following @var{forms}, in textual order, returning the result of
130 (prog2 (print "The first form")
131 (print "The second form")
132 (print "The third form"))
133 @print{} "The first form"
134 @print{} "The second form"
135 @print{} "The third form"
136 @result{} "The second form"
142 @section Conditionals
143 @cindex conditional evaluation
145 Conditional control structures choose among alternatives. XEmacs Lisp
146 has two conditional forms: @code{if}, which is much the same as in other
147 languages, and @code{cond}, which is a generalized case statement.
149 @defspec if condition then-form else-forms@dots{}
150 @code{if} chooses between the @var{then-form} and the @var{else-forms}
151 based on the value of @var{condition}. If the evaluated @var{condition} is
152 non-@code{nil}, @var{then-form} is evaluated and the result returned.
153 Otherwise, the @var{else-forms} are evaluated in textual order, and the
154 value of the last one is returned. (The @var{else} part of @code{if} is
155 an example of an implicit @code{progn}. @xref{Sequencing}.)
157 If @var{condition} has the value @code{nil}, and no @var{else-forms} are
158 given, @code{if} returns @code{nil}.
160 @code{if} is a special form because the branch that is not selected is
161 never evaluated---it is ignored. Thus, in the example below,
162 @code{true} is not printed because @code{print} is never called.
174 @defspec cond clause@dots{}
175 @code{cond} chooses among an arbitrary number of alternatives. Each
176 @var{clause} in the @code{cond} must be a list. The @sc{car} of this
177 list is the @var{condition}; the remaining elements, if any, the
178 @var{body-forms}. Thus, a clause looks like this:
181 (@var{condition} @var{body-forms}@dots{})
184 @code{cond} tries the clauses in textual order, by evaluating the
185 @var{condition} of each clause. If the value of @var{condition} is
186 non-@code{nil}, the clause ``succeeds''; then @code{cond} evaluates its
187 @var{body-forms}, and the value of the last of @var{body-forms} becomes
188 the value of the @code{cond}. The remaining clauses are ignored.
190 If the value of @var{condition} is @code{nil}, the clause ``fails'', so
191 the @code{cond} moves on to the following clause, trying its
194 If every @var{condition} evaluates to @code{nil}, so that every clause
195 fails, @code{cond} returns @code{nil}.
197 A clause may also look like this:
204 Then, if @var{condition} is non-@code{nil} when tested, the value of
205 @var{condition} becomes the value of the @code{cond} form.
207 The following example has four clauses, which test for the cases where
208 the value of @code{x} is a number, string, buffer and symbol,
213 (cond ((numberp x) x)
216 (setq temporary-hack x) ; @r{multiple body-forms}
217 (buffer-name x)) ; @r{in one clause}
218 ((symbolp x) (symbol-value x)))
222 Often we want to execute the last clause whenever none of the previous
223 clauses was successful. To do this, we use @code{t} as the
224 @var{condition} of the last clause, like this: @code{(t
225 @var{body-forms})}. The form @code{t} evaluates to @code{t}, which is
226 never @code{nil}, so this clause never fails, provided the @code{cond}
233 (cond ((eq a 'hack) 'foo)
240 This expression is a @code{cond} which returns @code{foo} if the value
241 of @code{a} is 1, and returns the string @code{"default"} otherwise.
244 Any conditional construct can be expressed with @code{cond} or with
245 @code{if}. Therefore, the choice between them is a matter of style.
250 (if @var{a} @var{b} @var{c})
252 (cond (@var{a} @var{b}) (t @var{c}))
256 @node Combining Conditions
257 @section Constructs for Combining Conditions
259 This section describes three constructs that are often used together
260 with @code{if} and @code{cond} to express complicated conditions. The
261 constructs @code{and} and @code{or} can also be used individually as
262 kinds of multiple conditional constructs.
265 This function tests for the falsehood of @var{condition}. It returns
266 @code{t} if @var{condition} is @code{nil}, and @code{nil} otherwise.
267 The function @code{not} is identical to @code{null}, and we recommend
268 using the name @code{null} if you are testing for an empty list.
271 @defspec and conditions@dots{}
272 The @code{and} special form tests whether all the @var{conditions} are
273 true. It works by evaluating the @var{conditions} one by one in the
276 If any of the @var{conditions} evaluates to @code{nil}, then the result
277 of the @code{and} must be @code{nil} regardless of the remaining
278 @var{conditions}; so @code{and} returns right away, ignoring the
279 remaining @var{conditions}.
281 If all the @var{conditions} turn out non-@code{nil}, then the value of
282 the last of them becomes the value of the @code{and} form.
284 Here is an example. The first condition returns the integer 1, which is
285 not @code{nil}. Similarly, the second condition returns the integer 2,
286 which is not @code{nil}. The third condition is @code{nil}, so the
287 remaining condition is never evaluated.
291 (and (print 1) (print 2) nil (print 3))
298 Here is a more realistic example of using @code{and}:
302 (if (and (consp foo) (eq (car foo) 'x))
303 (message "foo is a list starting with x"))
308 Note that @code{(car foo)} is not executed if @code{(consp foo)} returns
309 @code{nil}, thus avoiding an error.
311 @code{and} can be expressed in terms of either @code{if} or @code{cond}.
316 (and @var{arg1} @var{arg2} @var{arg3})
318 (if @var{arg1} (if @var{arg2} @var{arg3}))
320 (cond (@var{arg1} (cond (@var{arg2} @var{arg3}))))
325 @defspec or conditions@dots{}
326 The @code{or} special form tests whether at least one of the
327 @var{conditions} is true. It works by evaluating all the
328 @var{conditions} one by one in the order written.
330 If any of the @var{conditions} evaluates to a non-@code{nil} value, then
331 the result of the @code{or} must be non-@code{nil}; so @code{or} returns
332 right away, ignoring the remaining @var{conditions}. The value it
333 returns is the non-@code{nil} value of the condition just evaluated.
335 If all the @var{conditions} turn out @code{nil}, then the @code{or}
336 expression returns @code{nil}.
338 For example, this expression tests whether @code{x} is either 0 or
342 (or (eq x nil) (eq x 0))
345 Like the @code{and} construct, @code{or} can be written in terms of
346 @code{cond}. For example:
350 (or @var{arg1} @var{arg2} @var{arg3})
358 You could almost write @code{or} in terms of @code{if}, but not quite:
362 (if @var{arg1} @var{arg1}
363 (if @var{arg2} @var{arg2}
369 This is not completely equivalent because it can evaluate @var{arg1} or
370 @var{arg2} twice. By contrast, @code{(or @var{arg1} @var{arg2}
371 @var{arg3})} never evaluates any argument more than once.
379 Iteration means executing part of a program repetitively. For
380 example, you might want to repeat some computation once for each element
381 of a list, or once for each integer from 0 to @var{n}. You can do this
382 in XEmacs Lisp with the special form @code{while}:
384 @defspec while condition forms@dots{}
385 @code{while} first evaluates @var{condition}. If the result is
386 non-@code{nil}, it evaluates @var{forms} in textual order. Then it
387 reevaluates @var{condition}, and if the result is non-@code{nil}, it
388 evaluates @var{forms} again. This process repeats until @var{condition}
389 evaluates to @code{nil}.
391 There is no limit on the number of iterations that may occur. The loop
392 will continue until either @var{condition} evaluates to @code{nil} or
393 until an error or @code{throw} jumps out of it (@pxref{Nonlocal Exits}).
395 The value of a @code{while} form is always @code{nil}.
404 (princ (format "Iteration %d." num))
406 @print{} Iteration 0.
407 @print{} Iteration 1.
408 @print{} Iteration 2.
409 @print{} Iteration 3.
414 If you would like to execute something on each iteration before the
415 end-test, put it together with the end-test in a @code{progn} as the
416 first argument of @code{while}, as shown here:
422 (not (looking-at "^$"))))
427 This moves forward one line and continues moving by lines until it
428 reaches an empty. It is unusual in that the @code{while} has no body,
429 just the end test (which also does the real work of moving point).
433 @section Nonlocal Exits
434 @cindex nonlocal exits
436 A @dfn{nonlocal exit} is a transfer of control from one point in a
437 program to another remote point. Nonlocal exits can occur in XEmacs Lisp
438 as a result of errors; you can also use them under explicit control.
439 Nonlocal exits unbind all variable bindings made by the constructs being
443 * Catch and Throw:: Nonlocal exits for the program's own purposes.
444 * Examples of Catch:: Showing how such nonlocal exits can be written.
445 * Errors:: How errors are signaled and handled.
446 * Cleanups:: Arranging to run a cleanup form if an error happens.
449 @node Catch and Throw
450 @subsection Explicit Nonlocal Exits: @code{catch} and @code{throw}
452 Most control constructs affect only the flow of control within the
453 construct itself. The function @code{throw} is the exception to this
454 rule of normal program execution: it performs a nonlocal exit on
455 request. (There are other exceptions, but they are for error handling
456 only.) @code{throw} is used inside a @code{catch}, and jumps back to
457 that @code{catch}. For example:
470 The @code{throw} transfers control straight back to the corresponding
471 @code{catch}, which returns immediately. The code following the
472 @code{throw} is not executed. The second argument of @code{throw} is used
473 as the return value of the @code{catch}.
475 The @code{throw} and the @code{catch} are matched through the first
476 argument: @code{throw} searches for a @code{catch} whose first argument
477 is @code{eq} to the one specified. Thus, in the above example, the
478 @code{throw} specifies @code{foo}, and the @code{catch} specifies the
479 same symbol, so that @code{catch} is applicable. If there is more than
480 one applicable @code{catch}, the innermost one takes precedence.
482 Executing @code{throw} exits all Lisp constructs up to the matching
483 @code{catch}, including function calls. When binding constructs such as
484 @code{let} or function calls are exited in this way, the bindings are
485 unbound, just as they are when these constructs exit normally
486 (@pxref{Local Variables}). Likewise, @code{throw} restores the buffer
487 and position saved by @code{save-excursion} (@pxref{Excursions}), and
488 the narrowing status saved by @code{save-restriction} and the window
489 selection saved by @code{save-window-excursion} (@pxref{Window
490 Configurations}). It also runs any cleanups established with the
491 @code{unwind-protect} special form when it exits that form
494 The @code{throw} need not appear lexically within the @code{catch}
495 that it jumps to. It can equally well be called from another function
496 called within the @code{catch}. As long as the @code{throw} takes place
497 chronologically after entry to the @code{catch}, and chronologically
498 before exit from it, it has access to that @code{catch}. This is why
499 @code{throw} can be used in commands such as @code{exit-recursive-edit}
500 that throw back to the editor command loop (@pxref{Recursive Editing}).
502 @cindex CL note---only @code{throw} in Emacs
504 @b{Common Lisp note:} Most other versions of Lisp, including Common Lisp,
505 have several ways of transferring control nonsequentially: @code{return},
506 @code{return-from}, and @code{go}, for example. XEmacs Lisp has only
510 @defspec catch tag body@dots{}
511 @cindex tag on run time stack
512 @code{catch} establishes a return point for the @code{throw} function. The
513 return point is distinguished from other such return points by @var{tag},
514 which may be any Lisp object. The argument @var{tag} is evaluated normally
515 before the return point is established.
517 With the return point in effect, @code{catch} evaluates the forms of the
518 @var{body} in textual order. If the forms execute normally, without
519 error or nonlocal exit, the value of the last body form is returned from
522 If a @code{throw} is done within @var{body} specifying the same value
523 @var{tag}, the @code{catch} exits immediately; the value it returns is
524 whatever was specified as the second argument of @code{throw}.
527 @defun throw tag value
528 The purpose of @code{throw} is to return from a return point previously
529 established with @code{catch}. The argument @var{tag} is used to choose
530 among the various existing return points; it must be @code{eq} to the value
531 specified in the @code{catch}. If multiple return points match @var{tag},
532 the innermost one is used.
534 The argument @var{value} is used as the value to return from that
538 If no return point is in effect with tag @var{tag}, then a @code{no-catch}
539 error is signaled with data @code{(@var{tag} @var{value})}.
542 @node Examples of Catch
543 @subsection Examples of @code{catch} and @code{throw}
545 One way to use @code{catch} and @code{throw} is to exit from a doubly
546 nested loop. (In most languages, this would be done with a ``go to''.)
547 Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j}
559 (throw 'loop (list i j)))
566 If @code{foo} ever returns non-@code{nil}, we stop immediately and return a
567 list of @var{i} and @var{j}. If @code{foo} always returns @code{nil}, the
568 @code{catch} returns normally, and the value is @code{nil}, since that
569 is the result of the @code{while}.
571 Here are two tricky examples, slightly different, showing two
572 return points at once. First, two return points with the same tag,
585 (print (catch2 'hack))
593 Since both return points have tags that match the @code{throw}, it goes to
594 the inner one, the one established in @code{catch2}. Therefore,
595 @code{catch2} returns normally with value @code{yes}, and this value is
596 printed. Finally the second body form in the outer @code{catch}, which is
597 @code{'no}, is evaluated and returned from the outer @code{catch}.
599 Now let's change the argument given to @code{catch2}:
611 (print (catch2 'quux))
618 We still have two return points, but this time only the outer one has
619 the tag @code{hack}; the inner one has the tag @code{quux} instead.
620 Therefore, @code{throw} makes the outer @code{catch} return the value
621 @code{yes}. The function @code{print} is never called, and the
622 body-form @code{'no} is never evaluated.
628 When XEmacs Lisp attempts to evaluate a form that, for some reason,
629 cannot be evaluated, it @dfn{signals} an @dfn{error}.
631 When an error is signaled, XEmacs's default reaction is to print an
632 error message and terminate execution of the current command. This is
633 the right thing to do in most cases, such as if you type @kbd{C-f} at
634 the end of the buffer.
636 In complicated programs, simple termination may not be what you want.
637 For example, the program may have made temporary changes in data
638 structures, or created temporary buffers that should be deleted before
639 the program is finished. In such cases, you would use
640 @code{unwind-protect} to establish @dfn{cleanup expressions} to be
641 evaluated in case of error. (@xref{Cleanups}.) Occasionally, you may
642 wish the program to continue execution despite an error in a subroutine.
643 In these cases, you would use @code{condition-case} to establish
644 @dfn{error handlers} to recover control in case of error.
646 Resist the temptation to use error handling to transfer control from
647 one part of the program to another; use @code{catch} and @code{throw}
648 instead. @xref{Catch and Throw}.
651 * Signaling Errors:: How to report an error.
652 * Processing of Errors:: What XEmacs does when you report an error.
653 * Handling Errors:: How you can trap errors and continue execution.
654 * Error Symbols:: How errors are classified for trapping them.
657 @node Signaling Errors
658 @subsubsection How to Signal an Error
659 @cindex signaling errors
661 Most errors are signaled ``automatically'' within Lisp primitives
662 which you call for other purposes, such as if you try to take the
663 @sc{car} of an integer or move forward a character at the end of the
664 buffer; you can also signal errors explicitly with the functions
665 @code{error}, @code{signal}, and others.
667 Quitting, which happens when the user types @kbd{C-g}, is not
668 considered an error, but it is handled almost like an error.
671 @defun error format-string &rest args
672 This function signals an error with an error message constructed by
673 applying @code{format} (@pxref{String Conversion}) to
674 @var{format-string} and @var{args}.
676 This error is not continuable: you cannot continue execution after the
677 error using the debugger @kbd{r} or @kbd{c} commands. If you wish the
678 user to be able to continue execution, use @code{cerror} or
679 @code{signal} instead.
681 These examples show typical uses of @code{error}:
685 (error "You have committed an error.
686 Try something else.")
687 @error{} You have committed an error.
692 (error "You have committed %d errors." 10)
693 @error{} You have committed 10 errors.
697 @code{error} works by calling @code{signal} with two arguments: the
698 error symbol @code{error}, and a list containing the string returned by
699 @code{format}. This is repeated in an endless loop, to ensure that
700 @code{error} never returns.
702 If you want to use your own string as an error message verbatim, don't
703 just write @code{(error @var{string})}. If @var{string} contains
704 @samp{%}, it will be interpreted as a format specifier, with undesirable
705 results. Instead, use @code{(error "%s" @var{string})}.
708 @defun cerror format-string &rest args
709 This function behaves like @code{error}, except that the error it
710 signals is continuable. That means that debugger commands @kbd{c} and
711 @kbd{r} can resume execution.
714 @defun signal error-symbol data
715 This function signals a continuable error named by @var{error-symbol}.
716 The argument @var{data} is a list of additional Lisp objects relevant to
717 the circumstances of the error.
719 The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol
720 bearing a property @code{error-conditions} whose value is a list of
721 condition names. This is how XEmacs Lisp classifies different sorts of
724 The number and significance of the objects in @var{data} depends on
725 @var{error-symbol}. For example, with a @code{wrong-type-argument}
726 error, there are two objects in the list: a predicate that describes the
727 type that was expected, and the object that failed to fit that type.
728 @xref{Error Symbols}, for a description of error symbols.
730 Both @var{error-symbol} and @var{data} are available to any error
731 handlers that handle the error: @code{condition-case} binds a local
732 variable to a list of the form @code{(@var{error-symbol} .@:
733 @var{data})} (@pxref{Handling Errors}). If the error is not handled,
734 these two values are used in printing the error message.
736 The function @code{signal} can return, if the debugger is invoked and
737 the user invokes the ``return from signal'' option. If you want the
738 error not to be continuable, use @code{signal-error} instead. Note that
739 in FSF Emacs @code{signal} never returns.
743 (signal 'wrong-number-of-arguments '(x y))
744 @error{} Wrong number of arguments: x, y
748 (signal 'no-such-error '("My unknown error condition"))
749 @error{} Peculiar error (no-such-error "My unknown error condition")
754 @defun signal-error error-symbol data
755 This function behaves like @code{signal}, except that the error it
756 signals is not continuable.
759 @defmac check-argument-type predicate argument
760 This macro checks that @var{argument} satisfies @var{predicate}. If
761 that is not the case, it signals a continuable
762 @code{wrong-type-argument} error until the returned value satisfies
763 @var{predicate}, and assigns the returned value to @var{argument}. In
764 other words, execution of the program will not continue until
765 @var{predicate} is met.
767 @var{argument} is not evaluated, and should be a symbol.
768 @var{predicate} is evaluated, and should name a function.
770 As shown in the following example, @code{check-argument-type} is useful
771 in low-level code that attempts to ensure the sanity of its data before
776 (defun cache-object-internal (object wlist)
777 ;; @r{Before doing anything, make sure that @var{wlist} is indeed}
778 ;; @r{a weak list, which is what we expect.}
779 (check-argument-type 'weak-list-p wlist)
785 @node Processing of Errors
786 @subsubsection How XEmacs Processes Errors
788 When an error is signaled, @code{signal} searches for an active
789 @dfn{handler} for the error. A handler is a sequence of Lisp
790 expressions designated to be executed if an error happens in part of the
791 Lisp program. If the error has an applicable handler, the handler is
792 executed, and control resumes following the handler. The handler
793 executes in the environment of the @code{condition-case} that
794 established it; all functions called within that @code{condition-case}
795 have already been exited, and the handler cannot return to them.
797 If there is no applicable handler for the error, the current command is
798 terminated and control returns to the editor command loop, because the
799 command loop has an implicit handler for all kinds of errors. The
800 command loop's handler uses the error symbol and associated data to
801 print an error message.
803 Errors in command loop are processed using the @code{command-error}
804 function, which takes care of some necessary cleanup, and prints a
805 formatted error message to the echo area. The functions that do the
806 formatting are explained below.
808 @defun display-error error-object stream
809 This function displays @var{error-object} on @var{stream}.
810 @var{error-object} is a cons of error type, a symbol, and error
811 arguments, a list. If the error type symbol of one of its error
812 condition superclasses has an @code{display-error} property, that
813 function is invoked for printing the actual error message. Otherwise,
814 the error is printed as @samp{Error: arg1, arg2, ...}.
817 @defun error-message-string error-object
818 This function converts @var{error-object} to an error message string,
819 and returns it. The message is equivalent to the one that would be
820 printed by @code{display-error}, except that it is conveniently returned
824 @cindex @code{debug-on-error} use
825 An error that has no explicit handler may call the Lisp debugger. The
826 debugger is enabled if the variable @code{debug-on-error} (@pxref{Error
827 Debugging}) is non-@code{nil}. Unlike error handlers, the debugger runs
828 in the environment of the error, so that you can examine values of
829 variables precisely as they were at the time of the error.
831 @node Handling Errors
832 @subsubsection Writing Code to Handle Errors
833 @cindex error handler
834 @cindex handling errors
836 The usual effect of signaling an error is to terminate the command
837 that is running and return immediately to the XEmacs editor command loop.
838 You can arrange to trap errors occurring in a part of your program by
839 establishing an error handler, with the special form
840 @code{condition-case}. A simple example looks like this:
845 (delete-file filename)
851 This deletes the file named @var{filename}, catching any error and
852 returning @code{nil} if an error occurs.
854 The second argument of @code{condition-case} is called the
855 @dfn{protected form}. (In the example above, the protected form is a
856 call to @code{delete-file}.) The error handlers go into effect when
857 this form begins execution and are deactivated when this form returns.
858 They remain in effect for all the intervening time. In particular, they
859 are in effect during the execution of functions called by this form, in
860 their subroutines, and so on. This is a good thing, since, strictly
861 speaking, errors can be signaled only by Lisp primitives (including
862 @code{signal} and @code{error}) called by the protected form, not by the
863 protected form itself.
865 The arguments after the protected form are handlers. Each handler
866 lists one or more @dfn{condition names} (which are symbols) to specify
867 which errors it will handle. The error symbol specified when an error
868 is signaled also defines a list of condition names. A handler applies
869 to an error if they have any condition names in common. In the example
870 above, there is one handler, and it specifies one condition name,
871 @code{error}, which covers all errors.
873 The search for an applicable handler checks all the established handlers
874 starting with the most recently established one. Thus, if two nested
875 @code{condition-case} forms offer to handle the same error, the inner of
876 the two will actually handle it.
878 When an error is handled, control returns to the handler. Before this
879 happens, XEmacs unbinds all variable bindings made by binding constructs
880 that are being exited and executes the cleanups of all
881 @code{unwind-protect} forms that are exited. Once control arrives at
882 the handler, the body of the handler is executed.
884 After execution of the handler body, execution continues by returning
885 from the @code{condition-case} form. Because the protected form is
886 exited completely before execution of the handler, the handler cannot
887 resume execution at the point of the error, nor can it examine variable
888 bindings that were made within the protected form. All it can do is
889 clean up and proceed.
891 @code{condition-case} is often used to trap errors that are
892 predictable, such as failure to open a file in a call to
893 @code{insert-file-contents}. It is also used to trap errors that are
894 totally unpredictable, such as when the program evaluates an expression
897 @cindex @code{debug-on-signal} use
898 Even when an error is handled, the debugger may still be called if the
899 variable @code{debug-on-signal} (@pxref{Error Debugging}) is
900 non-@code{nil}. Note that this may yield unpredictable results with
901 code that traps expected errors as normal part of its operation. Do not
902 set @code{debug-on-signal} unless you know what you are doing.
904 Error signaling and handling have some resemblance to @code{throw} and
905 @code{catch}, but they are entirely separate facilities. An error
906 cannot be caught by a @code{catch}, and a @code{throw} cannot be handled
907 by an error handler (though using @code{throw} when there is no suitable
908 @code{catch} signals an error that can be handled).
910 @defspec condition-case var protected-form handlers@dots{}
911 This special form establishes the error handlers @var{handlers} around
912 the execution of @var{protected-form}. If @var{protected-form} executes
913 without error, the value it returns becomes the value of the
914 @code{condition-case} form; in this case, the @code{condition-case} has
915 no effect. The @code{condition-case} form makes a difference when an
916 error occurs during @var{protected-form}.
918 Each of the @var{handlers} is a list of the form @code{(@var{conditions}
919 @var{body}@dots{})}. Here @var{conditions} is an error condition name
920 to be handled, or a list of condition names; @var{body} is one or more
921 Lisp expressions to be executed when this handler handles an error.
922 Here are examples of handlers:
928 (arith-error (message "Division by zero"))
930 ((arith-error file-error)
932 "Either division by zero or failure to open a file"))
936 Each error that occurs has an @dfn{error symbol} that describes what
937 kind of error it is. The @code{error-conditions} property of this
938 symbol is a list of condition names (@pxref{Error Symbols}). Emacs
939 searches all the active @code{condition-case} forms for a handler that
940 specifies one or more of these condition names; the innermost matching
941 @code{condition-case} handles the error. Within this
942 @code{condition-case}, the first applicable handler handles the error.
944 After executing the body of the handler, the @code{condition-case}
945 returns normally, using the value of the last form in the handler body
946 as the overall value.
948 The argument @var{var} is a variable. @code{condition-case} does not
949 bind this variable when executing the @var{protected-form}, only when it
950 handles an error. At that time, it binds @var{var} locally to a list of
951 the form @code{(@var{error-symbol} . @var{data})}, giving the
952 particulars of the error. The handler can refer to this list to decide
953 what to do. For example, if the error is for failure opening a file,
954 the file name is the second element of @var{data}---the third element of
957 If @var{var} is @code{nil}, that means no variable is bound. Then the
958 error symbol and associated data are not available to the handler.
961 @cindex @code{arith-error} example
962 Here is an example of using @code{condition-case} to handle the error
963 that results from dividing by zero. The handler prints out a warning
964 message and returns a very large number.
968 (defun safe-divide (dividend divisor)
970 ;; @r{Protected form.}
973 (arith-error ; @r{Condition.}
974 (princ (format "Arithmetic error: %s" err))
976 @result{} safe-divide
981 @print{} Arithmetic error: (arith-error)
987 The handler specifies condition name @code{arith-error} so that it will
988 handle only division-by-zero errors. Other kinds of errors will not be
989 handled, at least not by this @code{condition-case}. Thus,
994 @error{} Wrong type argument: integer-or-marker-p, nil
998 Here is a @code{condition-case} that catches all kinds of errors,
999 including those signaled with @code{error}:
1011 ;; @r{This is a call to the function @code{error}.}
1012 (error "Rats! The variable %s was %s, not 35" 'baz baz))
1013 ;; @r{This is the handler; it is not a form.}
1014 (error (princ (format "The error was: %s" err))
1016 @print{} The error was: (error "Rats! The variable baz was 34, not 35")
1022 @subsubsection Error Symbols and Condition Names
1023 @cindex error symbol
1025 @cindex condition name
1026 @cindex user-defined error
1027 @kindex error-conditions
1029 When you signal an error, you specify an @dfn{error symbol} to specify
1030 the kind of error you have in mind. Each error has one and only one
1031 error symbol to categorize it. This is the finest classification of
1032 errors defined by the XEmacs Lisp language.
1034 These narrow classifications are grouped into a hierarchy of wider
1035 classes called @dfn{error conditions}, identified by @dfn{condition
1036 names}. The narrowest such classes belong to the error symbols
1037 themselves: each error symbol is also a condition name. There are also
1038 condition names for more extensive classes, up to the condition name
1039 @code{error} which takes in all kinds of errors. Thus, each error has
1040 one or more condition names: @code{error}, the error symbol if that
1041 is distinct from @code{error}, and perhaps some intermediate
1044 In other words, each error condition @dfn{inherits} from another error
1045 condition, with @code{error} sitting at the top of the inheritance
1048 @defun define-error error-symbol error-message &optional inherits-from
1049 This function defines a new error, denoted by @var{error-symbol}.
1050 @var{error-message} is an informative message explaining the error, and
1051 will be printed out when an unhandled error occurs. @var{error-symbol}
1052 is a sub-error of @var{inherits-from} (which defaults to @code{error}).
1054 @code{define-error} internally works by putting on @var{error-symbol}
1055 an @code{error-message} property whose value is @var{error-message}, and
1056 an @code{error-conditions} property that is a list of @var{error-symbol}
1057 followed by each of its super-errors, up to and including @code{error}.
1058 You will sometimes see code that sets this up directly rather than
1059 calling @code{define-error}, but you should @emph{not} do this yourself,
1060 unless you wish to maintain compatibility with FSF Emacs, which does not
1061 provide @code{define-error}.
1064 Here is how we define a new error symbol, @code{new-error}, that
1065 belongs to a range of errors called @code{my-own-errors}:
1069 (define-error 'my-own-errors "A whole range of errors" 'error)
1070 (define-error 'new-error "A new error" 'my-own-errors)
1075 @code{new-error} has three condition names: @code{new-error}, the
1076 narrowest classification; @code{my-own-errors}, which we imagine is a
1077 wider classification; and @code{error}, which is the widest of all.
1079 Note that it is not legal to try to define an error unless its
1080 super-error is also defined. For instance, attempting to define
1081 @code{new-error} before @code{my-own-errors} are defined will signal an
1084 The error string should start with a capital letter but it should
1085 not end with a period. This is for consistency with the rest of Emacs.
1087 Naturally, XEmacs will never signal @code{new-error} on its own; only
1088 an explicit call to @code{signal} (@pxref{Signaling Errors}) in your
1093 (signal 'new-error '(x y))
1094 @error{} A new error: x, y
1098 This error can be handled through any of the three condition names.
1099 This example handles @code{new-error} and any other errors in the class
1100 @code{my-own-errors}:
1106 (my-own-errors nil))
1110 The significant way that errors are classified is by their condition
1111 names---the names used to match errors with handlers. An error symbol
1112 serves only as a convenient way to specify the intended error message
1113 and list of condition names. It would be cumbersome to give
1114 @code{signal} a list of condition names rather than one error symbol.
1116 By contrast, using only error symbols without condition names would
1117 seriously decrease the power of @code{condition-case}. Condition names
1118 make it possible to categorize errors at various levels of generality
1119 when you write an error handler. Using error symbols alone would
1120 eliminate all but the narrowest level of classification.
1124 @xref{Standard Errors}, for a list of all the standard error symbols
1125 and their conditions.
1128 @subsection Cleaning Up from Nonlocal Exits
1130 The @code{unwind-protect} construct is essential whenever you
1131 temporarily put a data structure in an inconsistent state; it permits
1132 you to ensure the data are consistent in the event of an error or throw.
1134 @defspec unwind-protect body cleanup-forms@dots{}
1135 @cindex cleanup forms
1136 @cindex protected forms
1137 @cindex error cleanup
1139 @code{unwind-protect} executes the @var{body} with a guarantee that the
1140 @var{cleanup-forms} will be evaluated if control leaves @var{body}, no
1141 matter how that happens. The @var{body} may complete normally, or
1142 execute a @code{throw} out of the @code{unwind-protect}, or cause an
1143 error; in all cases, the @var{cleanup-forms} will be evaluated.
1145 If the @var{body} forms finish normally, @code{unwind-protect} returns
1146 the value of the last @var{body} form, after it evaluates the
1147 @var{cleanup-forms}. If the @var{body} forms do not finish,
1148 @code{unwind-protect} does not return any value in the normal sense.
1150 Only the @var{body} is actually protected by the @code{unwind-protect}.
1151 If any of the @var{cleanup-forms} themselves exits nonlocally (e.g., via
1152 a @code{throw} or an error), @code{unwind-protect} is @emph{not}
1153 guaranteed to evaluate the rest of them. If the failure of one of the
1154 @var{cleanup-forms} has the potential to cause trouble, then protect it
1155 with another @code{unwind-protect} around that form.
1157 The number of currently active @code{unwind-protect} forms counts,
1158 together with the number of local variable bindings, against the limit
1159 @code{max-specpdl-size} (@pxref{Local Variables}).
1162 For example, here we make an invisible buffer for temporary use, and
1163 make sure to kill it before finishing:
1168 (let ((buffer (get-buffer-create " *temp*")))
1172 (kill-buffer buffer))))
1177 You might think that we could just as well write @code{(kill-buffer
1178 (current-buffer))} and dispense with the variable @code{buffer}.
1179 However, the way shown above is safer, if @var{body} happens to get an
1180 error after switching to a different buffer! (Alternatively, you could
1181 write another @code{save-excursion} around the body, to ensure that the
1182 temporary buffer becomes current in time to kill it.)
1185 Here is an actual example taken from the file @file{ftp.el}. It
1186 creates a process (@pxref{Processes}) to try to establish a connection
1187 to a remote machine. As the function @code{ftp-login} is highly
1188 susceptible to numerous problems that the writer of the function cannot
1189 anticipate, it is protected with a form that guarantees deletion of the
1190 process in the event of failure. Otherwise, XEmacs might fill up with
1191 useless subprocesses.
1198 (setq process (ftp-setup-buffer host file))
1199 (if (setq win (ftp-login process host user password))
1200 (message "Logged in")
1201 (error "Ftp login failed")))
1202 (or win (and process (delete-process process)))))
1206 This example actually has a small bug: if the user types @kbd{C-g} to
1207 quit, and the quit happens immediately after the function
1208 @code{ftp-setup-buffer} returns but before the variable @code{process} is
1209 set, the process will not be killed. There is no easy way to fix this bug,
1210 but at least it is very unlikely.
1212 Here is another example which uses @code{unwind-protect} to make sure
1213 to kill a temporary buffer. In this example, the value returned by
1214 @code{unwind-protect} is used.
1217 (defun shell-command-string (cmd)
1218 "Return the output of the shell command CMD, as a string."
1220 (set-buffer (generate-new-buffer " OS*cmd"))
1221 (shell-command cmd t)
1224 (kill-buffer (current-buffer)))))