update.
[chise/xemacs-chise.git] / man / lispref / control.texi
1 @c -*-texinfo-*-
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
10
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
15 contain.
16
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}.
25
26   Explicit control structures make possible an order of execution other
27 than sequential.
28
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}).
35
36 @menu
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.
42 @end menu
43
44 @node Sequencing
45 @section Sequencing
46
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.
52
53   A @code{progn} special form looks like this:
54
55 @example
56 @group
57 (progn @var{a} @var{b} @var{c} @dots{})
58 @end group
59 @end example
60
61 @noindent
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
65 @code{progn}.
66
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}.
78
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.
82
83 @example
84 @group
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"
92 @end group
93 @end example
94 @end defspec
95
96   Two other control constructs likewise evaluate a series of forms but return
97 a different value:
98
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}.
102
103 @example
104 @group
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"
112 @end group
113 @end example
114
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:
117
118 @example
119 (prog1 (car x) (setq x (cdr x)))
120 @end example
121 @end defspec
122
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
126 @var{form2}.
127
128 @example
129 @group
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"
137 @end group
138 @end example
139 @end defspec
140
141 @node Conditionals
142 @section Conditionals
143 @cindex conditional evaluation
144
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.
148
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}.)
156
157 If @var{condition} has the value @code{nil}, and no @var{else-forms} are
158 given, @code{if} returns @code{nil}.
159
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.
163
164 @example
165 @group
166 (if nil
167     (print 'true)
168   'very-false)
169 @result{} very-false
170 @end group
171 @end example
172 @end defspec
173
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:
179
180 @example
181 (@var{condition} @var{body-forms}@dots{})
182 @end example
183
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.
189
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
192 @var{condition}.
193
194 If every @var{condition} evaluates to @code{nil}, so that every clause
195 fails, @code{cond} returns @code{nil}.
196
197 A clause may also look like this:
198
199 @example
200 (@var{condition})
201 @end example
202
203 @noindent
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.
206
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,
209 respectively:
210
211 @example
212 @group
213 (cond ((numberp x) x)
214       ((stringp x) x)
215       ((bufferp x)
216        (setq temporary-hack x) ; @r{multiple body-forms}
217        (buffer-name x))        ; @r{in one clause}
218       ((symbolp x) (symbol-value x)))
219 @end group
220 @end example
221
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}
227 gets to it at all.
228
229 For example,
230
231 @example
232 @group
233 (cond ((eq a 'hack) 'foo)
234       (t "default"))
235 @result{} "default"
236 @end group
237 @end example
238
239 @noindent
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.
242 @end defspec
243
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.
246 For example:
247
248 @example
249 @group
250 (if @var{a} @var{b} @var{c})
251 @equiv{}
252 (cond (@var{a} @var{b}) (t @var{c}))
253 @end group
254 @end example
255
256 @node Combining Conditions
257 @section Constructs for Combining Conditions
258
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.
263
264 @defun not condition
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.
269 @end defun
270
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
274 order written.
275
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}.
280
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.
283
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.
288
289 @example
290 @group
291 (and (print 1) (print 2) nil (print 3))
292      @print{} 1
293      @print{} 2
294 @result{} nil
295 @end group
296 @end example
297
298 Here is a more realistic example of using @code{and}:
299
300 @example
301 @group
302 (if (and (consp foo) (eq (car foo) 'x))
303     (message "foo is a list starting with x"))
304 @end group
305 @end example
306
307 @noindent
308 Note that @code{(car foo)} is not executed if @code{(consp foo)} returns
309 @code{nil}, thus avoiding an error.
310
311 @code{and} can be expressed in terms of either @code{if} or @code{cond}.
312 For example:
313
314 @example
315 @group
316 (and @var{arg1} @var{arg2} @var{arg3})
317 @equiv{}
318 (if @var{arg1} (if @var{arg2} @var{arg3}))
319 @equiv{}
320 (cond (@var{arg1} (cond (@var{arg2} @var{arg3}))))
321 @end group
322 @end example
323 @end defspec
324
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.
329
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.
334
335 If all the @var{conditions} turn out @code{nil}, then the @code{or}
336 expression returns @code{nil}.
337
338 For example, this expression tests whether @code{x} is either 0 or
339 @code{nil}:
340
341 @example
342 (or (eq x nil) (eq x 0))
343 @end example
344
345 Like the @code{and} construct, @code{or} can be written in terms of
346 @code{cond}.  For example:
347
348 @example
349 @group
350 (or @var{arg1} @var{arg2} @var{arg3})
351 @equiv{}
352 (cond (@var{arg1})
353       (@var{arg2})
354       (@var{arg3}))
355 @end group
356 @end example
357
358 You could almost write @code{or} in terms of @code{if}, but not quite:
359
360 @example
361 @group
362 (if @var{arg1} @var{arg1}
363   (if @var{arg2} @var{arg2}
364     @var{arg3}))
365 @end group
366 @end example
367
368 @noindent
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.
372 @end defspec
373
374 @node Iteration
375 @section Iteration
376 @cindex iteration
377 @cindex recursion
378
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}:
383
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}.
390
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}).
394
395 The value of a @code{while} form is always @code{nil}.
396
397 @example
398 @group
399 (setq num 0)
400      @result{} 0
401 @end group
402 @group
403 (while (< num 4)
404   (princ (format "Iteration %d." num))
405   (setq num (1+ num)))
406      @print{} Iteration 0.
407      @print{} Iteration 1.
408      @print{} Iteration 2.
409      @print{} Iteration 3.
410      @result{} nil
411 @end group
412 @end example
413
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:
417
418 @example
419 @group
420 (while (progn
421          (forward-line 1)
422          (not (looking-at "^$"))))
423 @end group
424 @end example
425
426 @noindent
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).
430 @end defspec
431
432 @node Nonlocal Exits
433 @section Nonlocal Exits
434 @cindex nonlocal exits
435
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
440 exited.
441
442 @menu
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.
447 @end menu
448
449 @node Catch and Throw
450 @subsection Explicit Nonlocal Exits: @code{catch} and @code{throw}
451
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:
458
459 @example
460 @group
461 (catch 'foo
462   (progn
463     @dots{}
464     (throw 'foo t)
465     @dots{}))
466 @end group
467 @end example
468
469 @noindent
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}.
474
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.
481
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
492 (@pxref{Cleanups}).
493
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}).
501
502 @cindex CL note---only @code{throw} in Emacs
503 @quotation
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
507 @code{throw}.
508 @end quotation
509
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.
516
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
520 the @code{catch}.
521
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}.
525 @end defspec
526
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.
533
534 The argument @var{value} is used as the value to return from that
535 @code{catch}.
536
537 @kindex no-catch
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})}.
540 @end defun
541
542 @node Examples of Catch
543 @subsection Examples of @code{catch} and @code{throw}
544
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}
548 varying from 0 to 9:
549
550 @example
551 @group
552 (defun search-foo ()
553   (catch 'loop
554     (let ((i 0))
555       (while (< i 10)
556         (let ((j 0))
557           (while (< j 10)
558             (if (foo i j)
559                 (throw 'loop (list i j)))
560             (setq j (1+ j))))
561         (setq i (1+ i))))))
562 @end group
563 @end example
564
565 @noindent
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}.
570
571   Here are two tricky examples, slightly different, showing two
572 return points at once.  First, two return points with the same tag,
573 @code{hack}:
574
575 @example
576 @group
577 (defun catch2 (tag)
578   (catch tag
579     (throw 'hack 'yes)))
580 @result{} catch2
581 @end group
582
583 @group
584 (catch 'hack
585   (print (catch2 'hack))
586   'no)
587 @print{} yes
588 @result{} no
589 @end group
590 @end example
591
592 @noindent
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}.
598
599   Now let's change the argument given to @code{catch2}:
600
601 @example
602 @group
603 (defun catch2 (tag)
604   (catch tag
605     (throw 'hack 'yes)))
606 @result{} catch2
607 @end group
608
609 @group
610 (catch 'hack
611   (print (catch2 'quux))
612   'no)
613 @result{} yes
614 @end group
615 @end example
616
617 @noindent
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.
623
624 @node Errors
625 @subsection Errors
626 @cindex errors
627
628   When XEmacs Lisp attempts to evaluate a form that, for some reason,
629 cannot be evaluated, it @dfn{signals} an @dfn{error}.
630
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.
635
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.
645
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}.
649
650 @menu
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.
655 @end menu
656
657 @node Signaling Errors
658 @subsubsection How to Signal an Error
659 @cindex signaling errors
660
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.
666
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.
669 @xref{Quitting}.
670
671 XEmacs has a rich hierarchy of error symbols predefined via @code{deferror}.
672
673 @example
674 error
675   syntax-error
676     invalid-read-syntax
677     list-formation-error
678       malformed-list
679         malformed-property-list
680       circular-list
681         circular-property-list
682
683   invalid-argument
684     wrong-type-argument
685     args-out-of-range
686     wrong-number-of-arguments
687     invalid-function
688     no-catch
689
690   invalid-state
691     void-function
692     cyclic-function-indirection
693     void-variable
694     cyclic-variable-indirection
695
696   invalid-operation
697     invalid-change
698       setting-constant
699     editing-error
700       beginning-of-buffer
701       end-of-buffer
702       buffer-read-only
703     io-error
704       end-of-file
705     arith-error
706       range-error
707       domain-error
708       singularity-error
709       overflow-error
710       underflow-error
711 @end example
712
713 The five most common errors you will probably use or base your new
714 errors off of are @code{syntax-error}, @code{invalid-argument},
715 @code{invalid-state}, @code{invalid-operation}, and
716 @code{invalid-change}.  Note the semantic differences:
717
718 @itemize @bullet
719 @item
720 @code{syntax-error} is for errors in complex structures: parsed strings,
721 lists, and the like.
722
723 @item
724 @code{invalid-argument} is for errors in a simple value.  Typically, the
725 entire value, not just one part of it, is wrong.
726
727 @item
728 @code{invalid-state} means that some settings have been changed in such
729 a way that their current state is unallowable.  More and more, code is
730 being written more carefully, and catches the error when the settings
731 are being changed, rather than afterwards.  This leads us to the next
732 error:
733
734 @item
735 @code{invalid-change} means that an attempt is being made to change some
736 settings into an invalid state.  @code{invalid-change} is a type of
737 @code{invalid-operation}.
738
739 @item
740 @code{invalid-operation} refers to all cases where code is trying to do
741 something that's disallowed.  This includes file errors, buffer errors
742 (e.g. running off the end of a buffer), @code{invalid-change} as just
743 mentioned, and arithmetic errors.
744 @end itemize
745
746 @defun error datum &rest args
747 This function signals a non-continuable error.
748
749 @var{datum} should normally be an error symbol, i.e. a symbol defined
750 using @code{define-error}.  @var{args} will be made into a list, and
751 @var{datum} and @var{args} passed as the two arguments to @code{signal},
752 the most basic error handling function.
753
754 This error is not continuable: you cannot continue execution after the
755 error using the debugger @kbd{r} command.  See also @code{cerror}.
756
757 The correct semantics of @var{args} varies from error to error, but for
758 most errors that need to be generated in Lisp code, the first argument
759 should be a string describing the *context* of the error (i.e. the exact
760 operation being performed and what went wrong), and the remaining
761 arguments or \"frobs\" (most often, there is one) specify the offending
762 object(s) and/or provide additional details such as the exact error when
763 a file error occurred, e.g.:
764
765 @itemize @bullet
766 @item
767 the buffer in which an editing error occurred.
768 @item
769 an invalid value that was encountered. (In such cases, the string
770 should describe the purpose or \"semantics\" of the value [e.g. if the
771 value is an argument to a function, the name of the argument; if the value
772 is the value corresponding to a keyword, the name of the keyword; if the
773 value is supposed to be a list length, say this and say what the purpose
774 of the list is; etc.] as well as specifying why the value is invalid, if
775 that's not self-evident.)
776 @item
777 the file in which an error occurred. (In such cases, there should be a
778 second frob, probably a string, specifying the exact error that occurred.
779 This does not occur in the string that precedes the first frob, because
780 that frob describes the exact operation that was happening.
781 @end itemize
782
783 For historical compatibility, DATUM can also be a string.  In this case,
784 @var{datum} and @var{args} are passed together as the arguments to
785 @code{format}, and then an error is signalled using the error symbol
786 @code{error} and formatted string.  Although this usage of @code{error}
787 is very common, it is deprecated because it totally defeats the purpose
788 of having structured errors.  There is now a rich set of defined errors
789 to use.
790
791 See also @code{cerror}, @code{signal}, and @code{signal-error}."
792
793 These examples show typical uses of @code{error}:
794
795 @example
796 @group
797 (error 'syntax-error
798        "Dialog descriptor must supply at least one button"
799         descriptor)
800 @end group
801
802 @group
803 (error "You have committed an error.
804         Try something else.")
805      @error{} You have committed an error.
806         Try something else.
807 @end group
808
809 @group
810 (error "You have committed %d errors." 10)
811      @error{} You have committed 10 errors.
812 @end group
813 @end example
814
815 If you want to use your own string as an error message verbatim, don't
816 just write @code{(error @var{string})}.  If @var{string} contains
817 @samp{%}, it will be interpreted as a format specifier, with undesirable
818 results.  Instead, use @code{(error "%s" @var{string})}.
819 @end defun
820
821 @defun cerror datum &rest args
822 This function behaves like @code{error}, except that the error it
823 signals is continuable.  That means that debugger commands @kbd{c} and
824 @kbd{r} can resume execution.
825 @end defun
826
827 @defun signal error-symbol data
828 This function signals a continuable error named by @var{error-symbol}.
829 The argument @var{data} is a list of additional Lisp objects relevant to
830 the circumstances of the error.
831
832 The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol
833 bearing a property @code{error-conditions} whose value is a list of
834 condition names.  This is how XEmacs Lisp classifies different sorts of
835 errors.
836
837 The number and significance of the objects in @var{data} depends on
838 @var{error-symbol}.  For example, with a @code{wrong-type-argument}
839 error, there are two objects in the list: a predicate that describes the
840 type that was expected, and the object that failed to fit that type.
841 @xref{Error Symbols}, for a description of error symbols.
842
843 Both @var{error-symbol} and @var{data} are available to any error
844 handlers that handle the error: @code{condition-case} binds a local
845 variable to a list of the form @code{(@var{error-symbol} .@:
846 @var{data})} (@pxref{Handling Errors}).  If the error is not handled,
847 these two values are used in printing the error message.
848
849 The function @code{signal} can return, if the debugger is invoked and
850 the user invokes the ``return from signal'' option.  If you want the
851 error not to be continuable, use @code{signal-error} instead.  Note that
852 in FSF Emacs @code{signal} never returns.
853
854 @smallexample
855 @group
856 (signal 'wrong-number-of-arguments '(x y))
857      @error{} Wrong number of arguments: x, y
858 @end group
859
860 @group
861 (signal 'no-such-error '("My unknown error condition"))
862      @error{} Peculiar error (no-such-error "My unknown error condition")
863 @end group
864 @end smallexample
865 @end defun
866
867 @defun signal-error error-symbol data
868 This function behaves like @code{signal}, except that the error it
869 signals is not continuable.
870 @end defun
871
872 @defmac check-argument-type predicate argument
873 This macro checks that @var{argument} satisfies @var{predicate}.  If
874 that is not the case, it signals a continuable
875 @code{wrong-type-argument} error until the returned value satisfies
876 @var{predicate}, and assigns the returned value to @var{argument}.  In
877 other words, execution of the program will not continue until
878 @var{predicate} is met.
879
880 @var{argument} is not evaluated, and should be a symbol.
881 @var{predicate} is evaluated, and should name a function.
882
883 As shown in the following example, @code{check-argument-type} is useful
884 in low-level code that attempts to ensure the sanity of its data before
885 proceeding.
886
887 @example
888 @group
889 (defun cache-object-internal (object wlist)
890   ;; @r{Before doing anything, make sure that @var{wlist} is indeed}
891   ;; @r{a weak list, which is what we expect.}
892   (check-argument-type 'weak-list-p wlist)
893   @dots{})
894 @end group
895 @end example
896 @end defmac
897
898 @node Processing of Errors
899 @subsubsection How XEmacs Processes Errors
900
901 When an error is signaled, @code{signal} searches for an active
902 @dfn{handler} for the error.  A handler is a sequence of Lisp
903 expressions designated to be executed if an error happens in part of the
904 Lisp program.  If the error has an applicable handler, the handler is
905 executed, and control resumes following the handler.  The handler
906 executes in the environment of the @code{condition-case} that
907 established it; all functions called within that @code{condition-case}
908 have already been exited, and the handler cannot return to them.
909
910 If there is no applicable handler for the error, the current command is
911 terminated and control returns to the editor command loop, because the
912 command loop has an implicit handler for all kinds of errors.  The
913 command loop's handler uses the error symbol and associated data to
914 print an error message.
915
916 Errors in command loop are processed using the @code{command-error}
917 function, which takes care of some necessary cleanup, and prints a
918 formatted error message to the echo area.  The functions that do the
919 formatting are explained below.
920
921 @defun display-error error-object stream
922 This function displays @var{error-object} on @var{stream}.
923 @var{error-object} is a cons of error type, a symbol, and error
924 arguments, a list.  If the error type symbol of one of its error
925 condition superclasses has a @code{display-error} property, that
926 function is invoked for printing the actual error message.  Otherwise,
927 the error is printed as @samp{Error: arg1, arg2, ...}.
928 @end defun
929
930 @defun error-message-string error-object
931 This function converts @var{error-object} to an error message string,
932 and returns it.  The message is equivalent to the one that would be
933 printed by @code{display-error}, except that it is conveniently returned
934 in string form.
935 @end defun
936
937 @cindex @code{debug-on-error} use
938 An error that has no explicit handler may call the Lisp debugger.  The
939 debugger is enabled if the variable @code{debug-on-error} (@pxref{Error
940 Debugging}) is non-@code{nil}.  Unlike error handlers, the debugger runs
941 in the environment of the error, so that you can examine values of
942 variables precisely as they were at the time of the error.
943
944 @node Handling Errors
945 @subsubsection Writing Code to Handle Errors
946 @cindex error handler
947 @cindex handling errors
948
949   The usual effect of signaling an error is to terminate the command
950 that is running and return immediately to the XEmacs editor command loop.
951 You can arrange to trap errors occurring in a part of your program by
952 establishing an error handler, with the special form
953 @code{condition-case}.  A simple example looks like this:
954
955 @example
956 @group
957 (condition-case nil
958     (delete-file filename)
959   (error nil))
960 @end group
961 @end example
962
963 @noindent
964 This deletes the file named @var{filename}, catching any error and
965 returning @code{nil} if an error occurs.
966
967   The second argument of @code{condition-case} is called the
968 @dfn{protected form}.  (In the example above, the protected form is a
969 call to @code{delete-file}.)  The error handlers go into effect when
970 this form begins execution and are deactivated when this form returns.
971 They remain in effect for all the intervening time.  In particular, they
972 are in effect during the execution of functions called by this form, in
973 their subroutines, and so on.  This is a good thing, since, strictly
974 speaking, errors can be signaled only by Lisp primitives (including
975 @code{signal} and @code{error}) called by the protected form, not by the
976 protected form itself.
977
978   The arguments after the protected form are handlers.  Each handler
979 lists one or more @dfn{condition names} (which are symbols) to specify
980 which errors it will handle.  The error symbol specified when an error
981 is signaled also defines a list of condition names.  A handler applies
982 to an error if they have any condition names in common.  In the example
983 above, there is one handler, and it specifies one condition name,
984 @code{error}, which covers all errors.
985
986   The search for an applicable handler checks all the established handlers
987 starting with the most recently established one.  Thus, if two nested
988 @code{condition-case} forms offer to handle the same error, the inner of
989 the two will actually handle it.
990
991   When an error is handled, control returns to the handler.  Before this
992 happens, XEmacs unbinds all variable bindings made by binding constructs
993 that are being exited and executes the cleanups of all
994 @code{unwind-protect} forms that are exited.  Once control arrives at
995 the handler, the body of the handler is executed.
996
997   After execution of the handler body, execution continues by returning
998 from the @code{condition-case} form.  Because the protected form is
999 exited completely before execution of the handler, the handler cannot
1000 resume execution at the point of the error, nor can it examine variable
1001 bindings that were made within the protected form.  All it can do is
1002 clean up and proceed.
1003
1004   @code{condition-case} is often used to trap errors that are
1005 predictable, such as failure to open a file in a call to
1006 @code{insert-file-contents}.  It is also used to trap errors that are
1007 totally unpredictable, such as when the program evaluates an expression
1008 read from the user.
1009
1010 @cindex @code{debug-on-signal} use
1011   Even when an error is handled, the debugger may still be called if the
1012 variable @code{debug-on-signal} (@pxref{Error Debugging}) is
1013 non-@code{nil}.  Note that this may yield unpredictable results with
1014 code that traps expected errors as normal part of its operation.  Do not
1015 set @code{debug-on-signal} unless you know what you are doing.
1016
1017   Error signaling and handling have some resemblance to @code{throw} and
1018 @code{catch}, but they are entirely separate facilities.  An error
1019 cannot be caught by a @code{catch}, and a @code{throw} cannot be handled
1020 by an error handler (though using @code{throw} when there is no suitable
1021 @code{catch} signals an error that can be handled).
1022
1023 @defspec condition-case var protected-form handlers@dots{}
1024 This special form establishes the error handlers @var{handlers} around
1025 the execution of @var{protected-form}.  If @var{protected-form} executes
1026 without error, the value it returns becomes the value of the
1027 @code{condition-case} form; in this case, the @code{condition-case} has
1028 no effect.  The @code{condition-case} form makes a difference when an
1029 error occurs during @var{protected-form}.
1030
1031 Each of the @var{handlers} is a list of the form @code{(@var{conditions}
1032 @var{body}@dots{})}.  Here @var{conditions} is an error condition name
1033 to be handled, or a list of condition names; @var{body} is one or more
1034 Lisp expressions to be executed when this handler handles an error.
1035 Here are examples of handlers:
1036
1037 @smallexample
1038 @group
1039 (error nil)
1040
1041 (arith-error (message "Division by zero"))
1042
1043 ((arith-error file-error)
1044  (message
1045   "Either division by zero or failure to open a file"))
1046 @end group
1047 @end smallexample
1048
1049 Each error that occurs has an @dfn{error symbol} that describes what
1050 kind of error it is.  The @code{error-conditions} property of this
1051 symbol is a list of condition names (@pxref{Error Symbols}).  Emacs
1052 searches all the active @code{condition-case} forms for a handler that
1053 specifies one or more of these condition names; the innermost matching
1054 @code{condition-case} handles the error.  Within this
1055 @code{condition-case}, the first applicable handler handles the error.
1056
1057 After executing the body of the handler, the @code{condition-case}
1058 returns normally, using the value of the last form in the handler body
1059 as the overall value.
1060
1061 The argument @var{var} is a variable.  @code{condition-case} does not
1062 bind this variable when executing the @var{protected-form}, only when it
1063 handles an error.  At that time, it binds @var{var} locally to a list of
1064 the form @code{(@var{error-symbol} . @var{data})}, giving the
1065 particulars of the error.  The handler can refer to this list to decide
1066 what to do.  For example, if the error is for failure opening a file,
1067 the file name is the second element of @var{data}---the third element of
1068 @var{var}.
1069
1070 If @var{var} is @code{nil}, that means no variable is bound.  Then the
1071 error symbol and associated data are not available to the handler.
1072 @end defspec
1073
1074 @cindex @code{arith-error} example
1075 Here is an example of using @code{condition-case} to handle the error
1076 that results from dividing by zero.  The handler prints out a warning
1077 message and returns a very large number.
1078
1079 @smallexample
1080 @group
1081 (defun safe-divide (dividend divisor)
1082   (condition-case err
1083       ;; @r{Protected form.}
1084       (/ dividend divisor)
1085     ;; @r{The handler.}
1086     (arith-error                        ; @r{Condition.}
1087      (princ (format "Arithmetic error: %s" err))
1088      1000000)))
1089 @result{} safe-divide
1090 @end group
1091
1092 @group
1093 (safe-divide 5 0)
1094      @print{} Arithmetic error: (arith-error)
1095 @result{} 1000000
1096 @end group
1097 @end smallexample
1098
1099 @noindent
1100 The handler specifies condition name @code{arith-error} so that it will
1101 handle only division-by-zero errors.  Other kinds of errors will not be
1102 handled, at least not by this @code{condition-case}.  Thus,
1103
1104 @smallexample
1105 @group
1106 (safe-divide nil 3)
1107      @error{} Wrong type argument: integer-or-marker-p, nil
1108 @end group
1109 @end smallexample
1110
1111   Here is a @code{condition-case} that catches all kinds of errors,
1112 including those signaled with @code{error}:
1113
1114 @smallexample
1115 @group
1116 (setq baz 34)
1117      @result{} 34
1118 @end group
1119
1120 @group
1121 (condition-case err
1122     (if (eq baz 35)
1123         t
1124       ;; @r{This is a call to the function @code{error}.}
1125       (error "Rats!  The variable %s was %s, not 35" 'baz baz))
1126   ;; @r{This is the handler; it is not a form.}
1127   (error (princ (format "The error was: %s" err))
1128          2))
1129 @print{} The error was: (error "Rats!  The variable baz was 34, not 35")
1130 @result{} 2
1131 @end group
1132 @end smallexample
1133
1134 @node Error Symbols
1135 @subsubsection Error Symbols and Condition Names
1136 @cindex error symbol
1137 @cindex error name
1138 @cindex condition name
1139 @cindex user-defined error
1140 @kindex error-conditions
1141
1142   When you signal an error, you specify an @dfn{error symbol} to specify
1143 the kind of error you have in mind.  Each error has one and only one
1144 error symbol to categorize it.  This is the finest classification of
1145 errors defined by the XEmacs Lisp language.
1146
1147   These narrow classifications are grouped into a hierarchy of wider
1148 classes called @dfn{error conditions}, identified by @dfn{condition
1149 names}.  The narrowest such classes belong to the error symbols
1150 themselves: each error symbol is also a condition name.  There are also
1151 condition names for more extensive classes, up to the condition name
1152 @code{error} which takes in all kinds of errors.  Thus, each error has
1153 one or more condition names: @code{error}, the error symbol if that
1154 is distinct from @code{error}, and perhaps some intermediate
1155 classifications.
1156
1157   In other words, each error condition @dfn{inherits} from another error
1158 condition, with @code{error} sitting at the top of the inheritance
1159 hierarchy.
1160
1161 @defun define-error error-symbol error-message &optional inherits-from
1162   This function defines a new error, denoted by @var{error-symbol}.
1163 @var{error-message} is an informative message explaining the error, and
1164 will be printed out when an unhandled error occurs.  @var{error-symbol}
1165 is a sub-error of @var{inherits-from} (which defaults to @code{error}).
1166
1167   @code{define-error} internally works by putting on @var{error-symbol}
1168 an @code{error-message} property whose value is @var{error-message}, and
1169 an @code{error-conditions} property that is a list of @var{error-symbol}
1170 followed by each of its super-errors, up to and including @code{error}.
1171 You will sometimes see code that sets this up directly rather than
1172 calling @code{define-error}, but you should @emph{not} do this yourself,
1173 unless you wish to maintain compatibility with FSF Emacs, which does not
1174 provide @code{define-error}.
1175 @end defun
1176
1177   Here is how we define a new error symbol, @code{new-error}, that
1178 belongs to a range of errors called @code{my-own-errors}:
1179
1180 @example
1181 @group
1182 (define-error 'my-own-errors "A whole range of errors" 'error)
1183 (define-error 'new-error "A new error" 'my-own-errors)
1184 @end group
1185 @end example
1186
1187 @noindent
1188 @code{new-error} has three condition names: @code{new-error}, the
1189 narrowest classification; @code{my-own-errors}, which we imagine is a
1190 wider classification; and @code{error}, which is the widest of all.
1191
1192   Note that it is not legal to try to define an error unless its
1193 super-error is also defined.  For instance, attempting to define
1194 @code{new-error} before @code{my-own-errors} are defined will signal an
1195 error.
1196
1197   The error string should start with a capital letter but it should
1198 not end with a period.  This is for consistency with the rest of Emacs.
1199
1200   Naturally, XEmacs will never signal @code{new-error} on its own; only
1201 an explicit call to @code{signal} (@pxref{Signaling Errors}) in your
1202 code can do this:
1203
1204 @example
1205 @group
1206 (signal 'new-error '(x y))
1207      @error{} A new error: x, y
1208 @end group
1209 @end example
1210
1211   This error can be handled through any of the three condition names.
1212 This example handles @code{new-error} and any other errors in the class
1213 @code{my-own-errors}:
1214
1215 @example
1216 @group
1217 (condition-case foo
1218     (bar nil t)
1219   (my-own-errors nil))
1220 @end group
1221 @end example
1222
1223   The significant way that errors are classified is by their condition
1224 names---the names used to match errors with handlers.  An error symbol
1225 serves only as a convenient way to specify the intended error message
1226 and list of condition names.  It would be cumbersome to give
1227 @code{signal} a list of condition names rather than one error symbol.
1228
1229   By contrast, using only error symbols without condition names would
1230 seriously decrease the power of @code{condition-case}.  Condition names
1231 make it possible to categorize errors at various levels of generality
1232 when you write an error handler.  Using error symbols alone would
1233 eliminate all but the narrowest level of classification.
1234
1235
1236
1237   @xref{Standard Errors}, for a list of all the standard error symbols
1238 and their conditions.
1239
1240 @node Cleanups
1241 @subsection Cleaning Up from Nonlocal Exits
1242
1243   The @code{unwind-protect} construct is essential whenever you
1244 temporarily put a data structure in an inconsistent state; it permits
1245 you to ensure the data are consistent in the event of an error or throw.
1246
1247 @defspec unwind-protect body cleanup-forms@dots{}
1248 @cindex cleanup forms
1249 @cindex protected forms
1250 @cindex error cleanup
1251 @cindex unwinding
1252 @code{unwind-protect} executes the @var{body} with a guarantee that the
1253 @var{cleanup-forms} will be evaluated if control leaves @var{body}, no
1254 matter how that happens.  The @var{body} may complete normally, or
1255 execute a @code{throw} out of the @code{unwind-protect}, or cause an
1256 error; in all cases, the @var{cleanup-forms} will be evaluated.
1257
1258 If the @var{body} forms finish normally, @code{unwind-protect} returns
1259 the value of the last @var{body} form, after it evaluates the
1260 @var{cleanup-forms}.  If the @var{body} forms do not finish,
1261 @code{unwind-protect} does not return any value in the normal sense.
1262
1263 Only the @var{body} is actually protected by the @code{unwind-protect}.
1264 If any of the @var{cleanup-forms} themselves exits nonlocally (e.g., via
1265 a @code{throw} or an error), @code{unwind-protect} is @emph{not}
1266 guaranteed to evaluate the rest of them.  If the failure of one of the
1267 @var{cleanup-forms} has the potential to cause trouble, then protect it
1268 with another @code{unwind-protect} around that form.
1269
1270 The number of currently active @code{unwind-protect} forms counts,
1271 together with the number of local variable bindings, against the limit
1272 @code{max-specpdl-size} (@pxref{Local Variables}).
1273 @end defspec
1274
1275   For example, here we make an invisible buffer for temporary use, and
1276 make sure to kill it before finishing:
1277
1278 @smallexample
1279 @group
1280 (save-excursion
1281   (let ((buffer (get-buffer-create " *temp*")))
1282     (set-buffer buffer)
1283     (unwind-protect
1284         @var{body}
1285       (kill-buffer buffer))))
1286 @end group
1287 @end smallexample
1288
1289 @noindent
1290 You might think that we could just as well write @code{(kill-buffer
1291 (current-buffer))} and dispense with the variable @code{buffer}.
1292 However, the way shown above is safer, if @var{body} happens to get an
1293 error after switching to a different buffer!  (Alternatively, you could
1294 write another @code{save-excursion} around the body, to ensure that the
1295 temporary buffer becomes current in time to kill it.)
1296
1297 @findex ftp-login
1298   Here is an actual example taken from the file @file{ftp.el}.  It
1299 creates a process (@pxref{Processes}) to try to establish a connection
1300 to a remote machine.  As the function @code{ftp-login} is highly
1301 susceptible to numerous problems that the writer of the function cannot
1302 anticipate, it is protected with a form that guarantees deletion of the
1303 process in the event of failure.  Otherwise, XEmacs might fill up with
1304 useless subprocesses.
1305
1306 @smallexample
1307 @group
1308 (let ((win nil))
1309   (unwind-protect
1310       (progn
1311         (setq process (ftp-setup-buffer host file))
1312         (if (setq win (ftp-login process host user password))
1313             (message "Logged in")
1314           (error "Ftp login failed")))
1315     (or win (and process (delete-process process)))))
1316 @end group
1317 @end smallexample
1318
1319   This example actually has a small bug: if the user types @kbd{C-g} to
1320 quit, and the quit happens immediately after the function
1321 @code{ftp-setup-buffer} returns but before the variable @code{process} is
1322 set, the process will not be killed.  There is no easy way to fix this bug,
1323 but at least it is very unlikely.
1324
1325   Here is another example which uses @code{unwind-protect} to make sure
1326 to kill a temporary buffer.  In this example, the value returned by
1327 @code{unwind-protect} is used.
1328
1329 @smallexample
1330 (defun shell-command-string (cmd)
1331   "Return the output of the shell command CMD, as a string."
1332   (save-excursion
1333     (set-buffer (generate-new-buffer " OS*cmd"))
1334     (shell-command cmd t)
1335     (unwind-protect
1336         (buffer-string)
1337       (kill-buffer (current-buffer)))))
1338 @end smallexample