| 1 | @c -*-texinfo-*- |
| 2 | @c This is part of the GNU Emacs Lisp Reference Manual. |
| 3 | @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 |
| 4 | @c Free Software Foundation, Inc. |
| 5 | @c See the file elisp.texi for copying conditions. |
| 6 | @setfilename ../info/control |
| 7 | @node Control Structures, Variables, Evaluation, Top |
| 8 | @chapter Control Structures |
| 9 | @cindex special forms for control structures |
| 10 | @cindex control structures |
| 11 | |
| 12 | A Lisp program consists of expressions or @dfn{forms} (@pxref{Forms}). |
| 13 | We control the order of execution of these forms by enclosing them in |
| 14 | @dfn{control structures}. Control structures are special forms which |
| 15 | control when, whether, or how many times to execute the forms they |
| 16 | contain. |
| 17 | |
| 18 | The simplest order of execution is sequential execution: first form |
| 19 | @var{a}, then form @var{b}, and so on. This is what happens when you |
| 20 | write several forms in succession in the body of a function, or at top |
| 21 | level in a file of Lisp code---the forms are executed in the order |
| 22 | written. We call this @dfn{textual order}. For example, if a function |
| 23 | body consists of two forms @var{a} and @var{b}, evaluation of the |
| 24 | function evaluates first @var{a} and then @var{b}. The result of |
| 25 | evaluating @var{b} becomes the value of the function. |
| 26 | |
| 27 | Explicit control structures make possible an order of execution other |
| 28 | than sequential. |
| 29 | |
| 30 | Emacs Lisp provides several kinds of control structure, including |
| 31 | other varieties of sequencing, conditionals, iteration, and (controlled) |
| 32 | jumps---all discussed below. The built-in control structures are |
| 33 | special forms since their subforms are not necessarily evaluated or not |
| 34 | evaluated sequentially. You can use macros to define your own control |
| 35 | structure constructs (@pxref{Macros}). |
| 36 | |
| 37 | @menu |
| 38 | * Sequencing:: Evaluation in textual order. |
| 39 | * Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. |
| 40 | * Combining Conditions:: @code{and}, @code{or}, @code{not}. |
| 41 | * Iteration:: @code{while} loops. |
| 42 | * Nonlocal Exits:: Jumping out of a sequence. |
| 43 | @end menu |
| 44 | |
| 45 | @node Sequencing |
| 46 | @section Sequencing |
| 47 | |
| 48 | Evaluating forms in the order they appear is the most common way |
| 49 | control passes from one form to another. In some contexts, such as in a |
| 50 | function body, this happens automatically. Elsewhere you must use a |
| 51 | control structure construct to do this: @code{progn}, the simplest |
| 52 | control construct of Lisp. |
| 53 | |
| 54 | A @code{progn} special form looks like this: |
| 55 | |
| 56 | @example |
| 57 | @group |
| 58 | (progn @var{a} @var{b} @var{c} @dots{}) |
| 59 | @end group |
| 60 | @end example |
| 61 | |
| 62 | @noindent |
| 63 | and it says to execute the forms @var{a}, @var{b}, @var{c}, and so on, in |
| 64 | that order. These forms are called the @dfn{body} of the @code{progn} form. |
| 65 | The value of the last form in the body becomes the value of the entire |
| 66 | @code{progn}. @code{(progn)} returns @code{nil}. |
| 67 | |
| 68 | @cindex implicit @code{progn} |
| 69 | In the early days of Lisp, @code{progn} was the only way to execute |
| 70 | two or more forms in succession and use the value of the last of them. |
| 71 | But programmers found they often needed to use a @code{progn} in the |
| 72 | body of a function, where (at that time) only one form was allowed. So |
| 73 | the body of a function was made into an ``implicit @code{progn}'': |
| 74 | several forms are allowed just as in the body of an actual @code{progn}. |
| 75 | Many other control structures likewise contain an implicit @code{progn}. |
| 76 | As a result, @code{progn} is not used as much as it was many years ago. |
| 77 | It is needed now most often inside an @code{unwind-protect}, @code{and}, |
| 78 | @code{or}, or in the @var{then}-part of an @code{if}. |
| 79 | |
| 80 | @defspec progn forms@dots{} |
| 81 | This special form evaluates all of the @var{forms}, in textual |
| 82 | order, returning the result of the final form. |
| 83 | |
| 84 | @example |
| 85 | @group |
| 86 | (progn (print "The first form") |
| 87 | (print "The second form") |
| 88 | (print "The third form")) |
| 89 | @print{} "The first form" |
| 90 | @print{} "The second form" |
| 91 | @print{} "The third form" |
| 92 | @result{} "The third form" |
| 93 | @end group |
| 94 | @end example |
| 95 | @end defspec |
| 96 | |
| 97 | Two other control constructs likewise evaluate a series of forms but return |
| 98 | a different value: |
| 99 | |
| 100 | @defspec prog1 form1 forms@dots{} |
| 101 | This special form evaluates @var{form1} and all of the @var{forms}, in |
| 102 | textual order, returning the result of @var{form1}. |
| 103 | |
| 104 | @example |
| 105 | @group |
| 106 | (prog1 (print "The first form") |
| 107 | (print "The second form") |
| 108 | (print "The third form")) |
| 109 | @print{} "The first form" |
| 110 | @print{} "The second form" |
| 111 | @print{} "The third form" |
| 112 | @result{} "The first form" |
| 113 | @end group |
| 114 | @end example |
| 115 | |
| 116 | Here is a way to remove the first element from a list in the variable |
| 117 | @code{x}, then return the value of that former element: |
| 118 | |
| 119 | @example |
| 120 | (prog1 (car x) (setq x (cdr x))) |
| 121 | @end example |
| 122 | @end defspec |
| 123 | |
| 124 | @defspec prog2 form1 form2 forms@dots{} |
| 125 | This special form evaluates @var{form1}, @var{form2}, and all of the |
| 126 | following @var{forms}, in textual order, returning the result of |
| 127 | @var{form2}. |
| 128 | |
| 129 | @example |
| 130 | @group |
| 131 | (prog2 (print "The first form") |
| 132 | (print "The second form") |
| 133 | (print "The third form")) |
| 134 | @print{} "The first form" |
| 135 | @print{} "The second form" |
| 136 | @print{} "The third form" |
| 137 | @result{} "The second form" |
| 138 | @end group |
| 139 | @end example |
| 140 | @end defspec |
| 141 | |
| 142 | @node Conditionals |
| 143 | @section Conditionals |
| 144 | @cindex conditional evaluation |
| 145 | |
| 146 | Conditional control structures choose among alternatives. Emacs Lisp |
| 147 | has four conditional forms: @code{if}, which is much the same as in |
| 148 | other languages; @code{when} and @code{unless}, which are variants of |
| 149 | @code{if}; and @code{cond}, which is a generalized case statement. |
| 150 | |
| 151 | @defspec if condition then-form else-forms@dots{} |
| 152 | @code{if} chooses between the @var{then-form} and the @var{else-forms} |
| 153 | based on the value of @var{condition}. If the evaluated @var{condition} is |
| 154 | non-@code{nil}, @var{then-form} is evaluated and the result returned. |
| 155 | Otherwise, the @var{else-forms} are evaluated in textual order, and the |
| 156 | value of the last one is returned. (The @var{else} part of @code{if} is |
| 157 | an example of an implicit @code{progn}. @xref{Sequencing}.) |
| 158 | |
| 159 | If @var{condition} has the value @code{nil}, and no @var{else-forms} are |
| 160 | given, @code{if} returns @code{nil}. |
| 161 | |
| 162 | @code{if} is a special form because the branch that is not selected is |
| 163 | never evaluated---it is ignored. Thus, in the example below, |
| 164 | @code{true} is not printed because @code{print} is never called. |
| 165 | |
| 166 | @example |
| 167 | @group |
| 168 | (if nil |
| 169 | (print 'true) |
| 170 | 'very-false) |
| 171 | @result{} very-false |
| 172 | @end group |
| 173 | @end example |
| 174 | @end defspec |
| 175 | |
| 176 | @defmac when condition then-forms@dots{} |
| 177 | This is a variant of @code{if} where there are no @var{else-forms}, |
| 178 | and possibly several @var{then-forms}. In particular, |
| 179 | |
| 180 | @example |
| 181 | (when @var{condition} @var{a} @var{b} @var{c}) |
| 182 | @end example |
| 183 | |
| 184 | @noindent |
| 185 | is entirely equivalent to |
| 186 | |
| 187 | @example |
| 188 | (if @var{condition} (progn @var{a} @var{b} @var{c}) nil) |
| 189 | @end example |
| 190 | @end defmac |
| 191 | |
| 192 | @defmac unless condition forms@dots{} |
| 193 | This is a variant of @code{if} where there is no @var{then-form}: |
| 194 | |
| 195 | @example |
| 196 | (unless @var{condition} @var{a} @var{b} @var{c}) |
| 197 | @end example |
| 198 | |
| 199 | @noindent |
| 200 | is entirely equivalent to |
| 201 | |
| 202 | @example |
| 203 | (if @var{condition} nil |
| 204 | @var{a} @var{b} @var{c}) |
| 205 | @end example |
| 206 | @end defmac |
| 207 | |
| 208 | @defspec cond clause@dots{} |
| 209 | @code{cond} chooses among an arbitrary number of alternatives. Each |
| 210 | @var{clause} in the @code{cond} must be a list. The @sc{car} of this |
| 211 | list is the @var{condition}; the remaining elements, if any, the |
| 212 | @var{body-forms}. Thus, a clause looks like this: |
| 213 | |
| 214 | @example |
| 215 | (@var{condition} @var{body-forms}@dots{}) |
| 216 | @end example |
| 217 | |
| 218 | @code{cond} tries the clauses in textual order, by evaluating the |
| 219 | @var{condition} of each clause. If the value of @var{condition} is |
| 220 | non-@code{nil}, the clause ``succeeds''; then @code{cond} evaluates its |
| 221 | @var{body-forms}, and the value of the last of @var{body-forms} becomes |
| 222 | the value of the @code{cond}. The remaining clauses are ignored. |
| 223 | |
| 224 | If the value of @var{condition} is @code{nil}, the clause ``fails'', so |
| 225 | the @code{cond} moves on to the following clause, trying its |
| 226 | @var{condition}. |
| 227 | |
| 228 | If every @var{condition} evaluates to @code{nil}, so that every clause |
| 229 | fails, @code{cond} returns @code{nil}. |
| 230 | |
| 231 | A clause may also look like this: |
| 232 | |
| 233 | @example |
| 234 | (@var{condition}) |
| 235 | @end example |
| 236 | |
| 237 | @noindent |
| 238 | Then, if @var{condition} is non-@code{nil} when tested, the value of |
| 239 | @var{condition} becomes the value of the @code{cond} form. |
| 240 | |
| 241 | The following example has four clauses, which test for the cases where |
| 242 | the value of @code{x} is a number, string, buffer and symbol, |
| 243 | respectively: |
| 244 | |
| 245 | @example |
| 246 | @group |
| 247 | (cond ((numberp x) x) |
| 248 | ((stringp x) x) |
| 249 | ((bufferp x) |
| 250 | (setq temporary-hack x) ; @r{multiple body-forms} |
| 251 | (buffer-name x)) ; @r{in one clause} |
| 252 | ((symbolp x) (symbol-value x))) |
| 253 | @end group |
| 254 | @end example |
| 255 | |
| 256 | Often we want to execute the last clause whenever none of the previous |
| 257 | clauses was successful. To do this, we use @code{t} as the |
| 258 | @var{condition} of the last clause, like this: @code{(t |
| 259 | @var{body-forms})}. The form @code{t} evaluates to @code{t}, which is |
| 260 | never @code{nil}, so this clause never fails, provided the @code{cond} |
| 261 | gets to it at all. |
| 262 | |
| 263 | For example, |
| 264 | |
| 265 | @example |
| 266 | @group |
| 267 | (setq a 5) |
| 268 | (cond ((eq a 'hack) 'foo) |
| 269 | (t "default")) |
| 270 | @result{} "default" |
| 271 | @end group |
| 272 | @end example |
| 273 | |
| 274 | @noindent |
| 275 | This @code{cond} expression returns @code{foo} if the value of @code{a} |
| 276 | is @code{hack}, and returns the string @code{"default"} otherwise. |
| 277 | @end defspec |
| 278 | |
| 279 | Any conditional construct can be expressed with @code{cond} or with |
| 280 | @code{if}. Therefore, the choice between them is a matter of style. |
| 281 | For example: |
| 282 | |
| 283 | @example |
| 284 | @group |
| 285 | (if @var{a} @var{b} @var{c}) |
| 286 | @equiv{} |
| 287 | (cond (@var{a} @var{b}) (t @var{c})) |
| 288 | @end group |
| 289 | @end example |
| 290 | |
| 291 | @node Combining Conditions |
| 292 | @section Constructs for Combining Conditions |
| 293 | |
| 294 | This section describes three constructs that are often used together |
| 295 | with @code{if} and @code{cond} to express complicated conditions. The |
| 296 | constructs @code{and} and @code{or} can also be used individually as |
| 297 | kinds of multiple conditional constructs. |
| 298 | |
| 299 | @defun not condition |
| 300 | This function tests for the falsehood of @var{condition}. It returns |
| 301 | @code{t} if @var{condition} is @code{nil}, and @code{nil} otherwise. |
| 302 | The function @code{not} is identical to @code{null}, and we recommend |
| 303 | using the name @code{null} if you are testing for an empty list. |
| 304 | @end defun |
| 305 | |
| 306 | @defspec and conditions@dots{} |
| 307 | The @code{and} special form tests whether all the @var{conditions} are |
| 308 | true. It works by evaluating the @var{conditions} one by one in the |
| 309 | order written. |
| 310 | |
| 311 | If any of the @var{conditions} evaluates to @code{nil}, then the result |
| 312 | of the @code{and} must be @code{nil} regardless of the remaining |
| 313 | @var{conditions}; so @code{and} returns @code{nil} right away, ignoring |
| 314 | the remaining @var{conditions}. |
| 315 | |
| 316 | If all the @var{conditions} turn out non-@code{nil}, then the value of |
| 317 | the last of them becomes the value of the @code{and} form. Just |
| 318 | @code{(and)}, with no @var{conditions}, returns @code{t}, appropriate |
| 319 | because all the @var{conditions} turned out non-@code{nil}. (Think |
| 320 | about it; which one did not?) |
| 321 | |
| 322 | Here is an example. The first condition returns the integer 1, which is |
| 323 | not @code{nil}. Similarly, the second condition returns the integer 2, |
| 324 | which is not @code{nil}. The third condition is @code{nil}, so the |
| 325 | remaining condition is never evaluated. |
| 326 | |
| 327 | @example |
| 328 | @group |
| 329 | (and (print 1) (print 2) nil (print 3)) |
| 330 | @print{} 1 |
| 331 | @print{} 2 |
| 332 | @result{} nil |
| 333 | @end group |
| 334 | @end example |
| 335 | |
| 336 | Here is a more realistic example of using @code{and}: |
| 337 | |
| 338 | @example |
| 339 | @group |
| 340 | (if (and (consp foo) (eq (car foo) 'x)) |
| 341 | (message "foo is a list starting with x")) |
| 342 | @end group |
| 343 | @end example |
| 344 | |
| 345 | @noindent |
| 346 | Note that @code{(car foo)} is not executed if @code{(consp foo)} returns |
| 347 | @code{nil}, thus avoiding an error. |
| 348 | |
| 349 | @code{and} can be expressed in terms of either @code{if} or @code{cond}. |
| 350 | For example: |
| 351 | |
| 352 | @example |
| 353 | @group |
| 354 | (and @var{arg1} @var{arg2} @var{arg3}) |
| 355 | @equiv{} |
| 356 | (if @var{arg1} (if @var{arg2} @var{arg3})) |
| 357 | @equiv{} |
| 358 | (cond (@var{arg1} (cond (@var{arg2} @var{arg3})))) |
| 359 | @end group |
| 360 | @end example |
| 361 | @end defspec |
| 362 | |
| 363 | @defspec or conditions@dots{} |
| 364 | The @code{or} special form tests whether at least one of the |
| 365 | @var{conditions} is true. It works by evaluating all the |
| 366 | @var{conditions} one by one in the order written. |
| 367 | |
| 368 | If any of the @var{conditions} evaluates to a non-@code{nil} value, then |
| 369 | the result of the @code{or} must be non-@code{nil}; so @code{or} returns |
| 370 | right away, ignoring the remaining @var{conditions}. The value it |
| 371 | returns is the non-@code{nil} value of the condition just evaluated. |
| 372 | |
| 373 | If all the @var{conditions} turn out @code{nil}, then the @code{or} |
| 374 | expression returns @code{nil}. Just @code{(or)}, with no |
| 375 | @var{conditions}, returns @code{nil}, appropriate because all the |
| 376 | @var{conditions} turned out @code{nil}. (Think about it; which one |
| 377 | did not?) |
| 378 | |
| 379 | For example, this expression tests whether @code{x} is either |
| 380 | @code{nil} or the integer zero: |
| 381 | |
| 382 | @example |
| 383 | (or (eq x nil) (eq x 0)) |
| 384 | @end example |
| 385 | |
| 386 | Like the @code{and} construct, @code{or} can be written in terms of |
| 387 | @code{cond}. For example: |
| 388 | |
| 389 | @example |
| 390 | @group |
| 391 | (or @var{arg1} @var{arg2} @var{arg3}) |
| 392 | @equiv{} |
| 393 | (cond (@var{arg1}) |
| 394 | (@var{arg2}) |
| 395 | (@var{arg3})) |
| 396 | @end group |
| 397 | @end example |
| 398 | |
| 399 | You could almost write @code{or} in terms of @code{if}, but not quite: |
| 400 | |
| 401 | @example |
| 402 | @group |
| 403 | (if @var{arg1} @var{arg1} |
| 404 | (if @var{arg2} @var{arg2} |
| 405 | @var{arg3})) |
| 406 | @end group |
| 407 | @end example |
| 408 | |
| 409 | @noindent |
| 410 | This is not completely equivalent because it can evaluate @var{arg1} or |
| 411 | @var{arg2} twice. By contrast, @code{(or @var{arg1} @var{arg2} |
| 412 | @var{arg3})} never evaluates any argument more than once. |
| 413 | @end defspec |
| 414 | |
| 415 | @node Iteration |
| 416 | @section Iteration |
| 417 | @cindex iteration |
| 418 | @cindex recursion |
| 419 | |
| 420 | Iteration means executing part of a program repetitively. For |
| 421 | example, you might want to repeat some computation once for each element |
| 422 | of a list, or once for each integer from 0 to @var{n}. You can do this |
| 423 | in Emacs Lisp with the special form @code{while}: |
| 424 | |
| 425 | @defspec while condition forms@dots{} |
| 426 | @code{while} first evaluates @var{condition}. If the result is |
| 427 | non-@code{nil}, it evaluates @var{forms} in textual order. Then it |
| 428 | reevaluates @var{condition}, and if the result is non-@code{nil}, it |
| 429 | evaluates @var{forms} again. This process repeats until @var{condition} |
| 430 | evaluates to @code{nil}. |
| 431 | |
| 432 | There is no limit on the number of iterations that may occur. The loop |
| 433 | will continue until either @var{condition} evaluates to @code{nil} or |
| 434 | until an error or @code{throw} jumps out of it (@pxref{Nonlocal Exits}). |
| 435 | |
| 436 | The value of a @code{while} form is always @code{nil}. |
| 437 | |
| 438 | @example |
| 439 | @group |
| 440 | (setq num 0) |
| 441 | @result{} 0 |
| 442 | @end group |
| 443 | @group |
| 444 | (while (< num 4) |
| 445 | (princ (format "Iteration %d." num)) |
| 446 | (setq num (1+ num))) |
| 447 | @print{} Iteration 0. |
| 448 | @print{} Iteration 1. |
| 449 | @print{} Iteration 2. |
| 450 | @print{} Iteration 3. |
| 451 | @result{} nil |
| 452 | @end group |
| 453 | @end example |
| 454 | |
| 455 | To write a ``repeat...until'' loop, which will execute something on each |
| 456 | iteration and then do the end-test, put the body followed by the |
| 457 | end-test in a @code{progn} as the first argument of @code{while}, as |
| 458 | shown here: |
| 459 | |
| 460 | @example |
| 461 | @group |
| 462 | (while (progn |
| 463 | (forward-line 1) |
| 464 | (not (looking-at "^$")))) |
| 465 | @end group |
| 466 | @end example |
| 467 | |
| 468 | @noindent |
| 469 | This moves forward one line and continues moving by lines until it |
| 470 | reaches an empty line. It is peculiar in that the @code{while} has no |
| 471 | body, just the end test (which also does the real work of moving point). |
| 472 | @end defspec |
| 473 | |
| 474 | The @code{dolist} and @code{dotimes} macros provide convenient ways to |
| 475 | write two common kinds of loops. |
| 476 | |
| 477 | @defmac dolist (var list [result]) body@dots{} |
| 478 | @tindex dolist |
| 479 | This construct executes @var{body} once for each element of @var{list}, |
| 480 | using the variable @var{var} to hold the current element. Then it |
| 481 | returns the value of evaluating @var{result}, or @code{nil} if |
| 482 | @var{result} is omitted. For example, here is how you could use |
| 483 | @code{dolist} to define the @code{reverse} function: |
| 484 | |
| 485 | @example |
| 486 | (defun reverse (list) |
| 487 | (let (value) |
| 488 | (dolist (elt list value) |
| 489 | (setq value (cons elt value))))) |
| 490 | @end example |
| 491 | @end defmac |
| 492 | |
| 493 | @defmac dotimes (var count [result]) body@dots{} |
| 494 | @tindex dotimes |
| 495 | This construct executes @var{body} once for each integer from 0 |
| 496 | (inclusive) to @var{count} (exclusive), using the variable @var{var} to |
| 497 | hold the integer for the current iteration. Then it returns the value |
| 498 | of evaluating @var{result}, or @code{nil} if @var{result} is omitted. |
| 499 | Here is an example of using @code{dotimes} do something 100 times: |
| 500 | |
| 501 | @example |
| 502 | (dotimes (i 100) |
| 503 | (insert "I will not obey absurd orders\n")) |
| 504 | @end example |
| 505 | @end defmac |
| 506 | |
| 507 | @node Nonlocal Exits |
| 508 | @section Nonlocal Exits |
| 509 | @cindex nonlocal exits |
| 510 | |
| 511 | A @dfn{nonlocal exit} is a transfer of control from one point in a |
| 512 | program to another remote point. Nonlocal exits can occur in Emacs Lisp |
| 513 | as a result of errors; you can also use them under explicit control. |
| 514 | Nonlocal exits unbind all variable bindings made by the constructs being |
| 515 | exited. |
| 516 | |
| 517 | @menu |
| 518 | * Catch and Throw:: Nonlocal exits for the program's own purposes. |
| 519 | * Examples of Catch:: Showing how such nonlocal exits can be written. |
| 520 | * Errors:: How errors are signaled and handled. |
| 521 | * Cleanups:: Arranging to run a cleanup form if an error happens. |
| 522 | @end menu |
| 523 | |
| 524 | @node Catch and Throw |
| 525 | @subsection Explicit Nonlocal Exits: @code{catch} and @code{throw} |
| 526 | |
| 527 | Most control constructs affect only the flow of control within the |
| 528 | construct itself. The function @code{throw} is the exception to this |
| 529 | rule of normal program execution: it performs a nonlocal exit on |
| 530 | request. (There are other exceptions, but they are for error handling |
| 531 | only.) @code{throw} is used inside a @code{catch}, and jumps back to |
| 532 | that @code{catch}. For example: |
| 533 | |
| 534 | @example |
| 535 | @group |
| 536 | (defun foo-outer () |
| 537 | (catch 'foo |
| 538 | (foo-inner))) |
| 539 | |
| 540 | (defun foo-inner () |
| 541 | @dots{} |
| 542 | (if x |
| 543 | (throw 'foo t)) |
| 544 | @dots{}) |
| 545 | @end group |
| 546 | @end example |
| 547 | |
| 548 | @noindent |
| 549 | The @code{throw} form, if executed, transfers control straight back to |
| 550 | the corresponding @code{catch}, which returns immediately. The code |
| 551 | following the @code{throw} is not executed. The second argument of |
| 552 | @code{throw} is used as the return value of the @code{catch}. |
| 553 | |
| 554 | The function @code{throw} finds the matching @code{catch} based on the |
| 555 | first argument: it searches for a @code{catch} whose first argument is |
| 556 | @code{eq} to the one specified in the @code{throw}. If there is more |
| 557 | than one applicable @code{catch}, the innermost one takes precedence. |
| 558 | Thus, in the above example, the @code{throw} specifies @code{foo}, and |
| 559 | the @code{catch} in @code{foo-outer} specifies the same symbol, so that |
| 560 | @code{catch} is the applicable one (assuming there is no other matching |
| 561 | @code{catch} in between). |
| 562 | |
| 563 | Executing @code{throw} exits all Lisp constructs up to the matching |
| 564 | @code{catch}, including function calls. When binding constructs such as |
| 565 | @code{let} or function calls are exited in this way, the bindings are |
| 566 | unbound, just as they are when these constructs exit normally |
| 567 | (@pxref{Local Variables}). Likewise, @code{throw} restores the buffer |
| 568 | and position saved by @code{save-excursion} (@pxref{Excursions}), and |
| 569 | the narrowing status saved by @code{save-restriction} and the window |
| 570 | selection saved by @code{save-window-excursion} (@pxref{Window |
| 571 | Configurations}). It also runs any cleanups established with the |
| 572 | @code{unwind-protect} special form when it exits that form |
| 573 | (@pxref{Cleanups}). |
| 574 | |
| 575 | The @code{throw} need not appear lexically within the @code{catch} |
| 576 | that it jumps to. It can equally well be called from another function |
| 577 | called within the @code{catch}. As long as the @code{throw} takes place |
| 578 | chronologically after entry to the @code{catch}, and chronologically |
| 579 | before exit from it, it has access to that @code{catch}. This is why |
| 580 | @code{throw} can be used in commands such as @code{exit-recursive-edit} |
| 581 | that throw back to the editor command loop (@pxref{Recursive Editing}). |
| 582 | |
| 583 | @cindex CL note---only @code{throw} in Emacs |
| 584 | @quotation |
| 585 | @b{Common Lisp note:} Most other versions of Lisp, including Common Lisp, |
| 586 | have several ways of transferring control nonsequentially: @code{return}, |
| 587 | @code{return-from}, and @code{go}, for example. Emacs Lisp has only |
| 588 | @code{throw}. |
| 589 | @end quotation |
| 590 | |
| 591 | @defspec catch tag body@dots{} |
| 592 | @cindex tag on run time stack |
| 593 | @code{catch} establishes a return point for the @code{throw} function. |
| 594 | The return point is distinguished from other such return points by |
| 595 | @var{tag}, which may be any Lisp object except @code{nil}. The argument |
| 596 | @var{tag} is evaluated normally before the return point is established. |
| 597 | |
| 598 | With the return point in effect, @code{catch} evaluates the forms of the |
| 599 | @var{body} in textual order. If the forms execute normally (without |
| 600 | error or nonlocal exit) the value of the last body form is returned from |
| 601 | the @code{catch}. |
| 602 | |
| 603 | If a @code{throw} is executed during the execution of @var{body}, |
| 604 | specifying the same value @var{tag}, the @code{catch} form exits |
| 605 | immediately; the value it returns is whatever was specified as the |
| 606 | second argument of @code{throw}. |
| 607 | @end defspec |
| 608 | |
| 609 | @defun throw tag value |
| 610 | The purpose of @code{throw} is to return from a return point previously |
| 611 | established with @code{catch}. The argument @var{tag} is used to choose |
| 612 | among the various existing return points; it must be @code{eq} to the value |
| 613 | specified in the @code{catch}. If multiple return points match @var{tag}, |
| 614 | the innermost one is used. |
| 615 | |
| 616 | The argument @var{value} is used as the value to return from that |
| 617 | @code{catch}. |
| 618 | |
| 619 | @kindex no-catch |
| 620 | If no return point is in effect with tag @var{tag}, then a @code{no-catch} |
| 621 | error is signaled with data @code{(@var{tag} @var{value})}. |
| 622 | @end defun |
| 623 | |
| 624 | @node Examples of Catch |
| 625 | @subsection Examples of @code{catch} and @code{throw} |
| 626 | |
| 627 | One way to use @code{catch} and @code{throw} is to exit from a doubly |
| 628 | nested loop. (In most languages, this would be done with a ``go to''.) |
| 629 | Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j} |
| 630 | varying from 0 to 9: |
| 631 | |
| 632 | @example |
| 633 | @group |
| 634 | (defun search-foo () |
| 635 | (catch 'loop |
| 636 | (let ((i 0)) |
| 637 | (while (< i 10) |
| 638 | (let ((j 0)) |
| 639 | (while (< j 10) |
| 640 | (if (foo i j) |
| 641 | (throw 'loop (list i j))) |
| 642 | (setq j (1+ j)))) |
| 643 | (setq i (1+ i)))))) |
| 644 | @end group |
| 645 | @end example |
| 646 | |
| 647 | @noindent |
| 648 | If @code{foo} ever returns non-@code{nil}, we stop immediately and return a |
| 649 | list of @var{i} and @var{j}. If @code{foo} always returns @code{nil}, the |
| 650 | @code{catch} returns normally, and the value is @code{nil}, since that |
| 651 | is the result of the @code{while}. |
| 652 | |
| 653 | Here are two tricky examples, slightly different, showing two |
| 654 | return points at once. First, two return points with the same tag, |
| 655 | @code{hack}: |
| 656 | |
| 657 | @example |
| 658 | @group |
| 659 | (defun catch2 (tag) |
| 660 | (catch tag |
| 661 | (throw 'hack 'yes))) |
| 662 | @result{} catch2 |
| 663 | @end group |
| 664 | |
| 665 | @group |
| 666 | (catch 'hack |
| 667 | (print (catch2 'hack)) |
| 668 | 'no) |
| 669 | @print{} yes |
| 670 | @result{} no |
| 671 | @end group |
| 672 | @end example |
| 673 | |
| 674 | @noindent |
| 675 | Since both return points have tags that match the @code{throw}, it goes to |
| 676 | the inner one, the one established in @code{catch2}. Therefore, |
| 677 | @code{catch2} returns normally with value @code{yes}, and this value is |
| 678 | printed. Finally the second body form in the outer @code{catch}, which is |
| 679 | @code{'no}, is evaluated and returned from the outer @code{catch}. |
| 680 | |
| 681 | Now let's change the argument given to @code{catch2}: |
| 682 | |
| 683 | @example |
| 684 | @group |
| 685 | (catch 'hack |
| 686 | (print (catch2 'quux)) |
| 687 | 'no) |
| 688 | @result{} yes |
| 689 | @end group |
| 690 | @end example |
| 691 | |
| 692 | @noindent |
| 693 | We still have two return points, but this time only the outer one has |
| 694 | the tag @code{hack}; the inner one has the tag @code{quux} instead. |
| 695 | Therefore, @code{throw} makes the outer @code{catch} return the value |
| 696 | @code{yes}. The function @code{print} is never called, and the |
| 697 | body-form @code{'no} is never evaluated. |
| 698 | |
| 699 | @node Errors |
| 700 | @subsection Errors |
| 701 | @cindex errors |
| 702 | |
| 703 | When Emacs Lisp attempts to evaluate a form that, for some reason, |
| 704 | cannot be evaluated, it @dfn{signals} an @dfn{error}. |
| 705 | |
| 706 | When an error is signaled, Emacs's default reaction is to print an |
| 707 | error message and terminate execution of the current command. This is |
| 708 | the right thing to do in most cases, such as if you type @kbd{C-f} at |
| 709 | the end of the buffer. |
| 710 | |
| 711 | In complicated programs, simple termination may not be what you want. |
| 712 | For example, the program may have made temporary changes in data |
| 713 | structures, or created temporary buffers that should be deleted before |
| 714 | the program is finished. In such cases, you would use |
| 715 | @code{unwind-protect} to establish @dfn{cleanup expressions} to be |
| 716 | evaluated in case of error. (@xref{Cleanups}.) Occasionally, you may |
| 717 | wish the program to continue execution despite an error in a subroutine. |
| 718 | In these cases, you would use @code{condition-case} to establish |
| 719 | @dfn{error handlers} to recover control in case of error. |
| 720 | |
| 721 | Resist the temptation to use error handling to transfer control from |
| 722 | one part of the program to another; use @code{catch} and @code{throw} |
| 723 | instead. @xref{Catch and Throw}. |
| 724 | |
| 725 | @menu |
| 726 | * Signaling Errors:: How to report an error. |
| 727 | * Processing of Errors:: What Emacs does when you report an error. |
| 728 | * Handling Errors:: How you can trap errors and continue execution. |
| 729 | * Error Symbols:: How errors are classified for trapping them. |
| 730 | @end menu |
| 731 | |
| 732 | @node Signaling Errors |
| 733 | @subsubsection How to Signal an Error |
| 734 | @cindex signaling errors |
| 735 | |
| 736 | Most errors are signaled ``automatically'' within Lisp primitives |
| 737 | which you call for other purposes, such as if you try to take the |
| 738 | @sc{car} of an integer or move forward a character at the end of the |
| 739 | buffer. You can also signal errors explicitly with the functions |
| 740 | @code{error} and @code{signal}. |
| 741 | |
| 742 | Quitting, which happens when the user types @kbd{C-g}, is not |
| 743 | considered an error, but it is handled almost like an error. |
| 744 | @xref{Quitting}. |
| 745 | |
| 746 | The error message should state what is wrong (``File does not |
| 747 | exist''), not how things ought to be (``File must exist''). The |
| 748 | convention in Emacs Lisp is that error messages should start with a |
| 749 | capital letter, but should not end with any sort of punctuation. |
| 750 | |
| 751 | @defun error format-string &rest args |
| 752 | This function signals an error with an error message constructed by |
| 753 | applying @code{format} (@pxref{String Conversion}) to |
| 754 | @var{format-string} and @var{args}. |
| 755 | |
| 756 | These examples show typical uses of @code{error}: |
| 757 | |
| 758 | @example |
| 759 | @group |
| 760 | (error "That is an error -- try something else") |
| 761 | @error{} That is an error -- try something else |
| 762 | @end group |
| 763 | |
| 764 | @group |
| 765 | (error "You have committed %d errors" 10) |
| 766 | @error{} You have committed 10 errors |
| 767 | @end group |
| 768 | @end example |
| 769 | |
| 770 | @code{error} works by calling @code{signal} with two arguments: the |
| 771 | error symbol @code{error}, and a list containing the string returned by |
| 772 | @code{format}. |
| 773 | |
| 774 | @strong{Warning:} If you want to use your own string as an error message |
| 775 | verbatim, don't just write @code{(error @var{string})}. If @var{string} |
| 776 | contains @samp{%}, it will be interpreted as a format specifier, with |
| 777 | undesirable results. Instead, use @code{(error "%s" @var{string})}. |
| 778 | @end defun |
| 779 | |
| 780 | @defun signal error-symbol data |
| 781 | This function signals an error named by @var{error-symbol}. The |
| 782 | argument @var{data} is a list of additional Lisp objects relevant to the |
| 783 | circumstances of the error. |
| 784 | |
| 785 | The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol |
| 786 | bearing a property @code{error-conditions} whose value is a list of |
| 787 | condition names. This is how Emacs Lisp classifies different sorts of |
| 788 | errors. |
| 789 | |
| 790 | The number and significance of the objects in @var{data} depends on |
| 791 | @var{error-symbol}. For example, with a @code{wrong-type-arg} error, |
| 792 | there should be two objects in the list: a predicate that describes the type |
| 793 | that was expected, and the object that failed to fit that type. |
| 794 | @xref{Error Symbols}, for a description of error symbols. |
| 795 | |
| 796 | Both @var{error-symbol} and @var{data} are available to any error |
| 797 | handlers that handle the error: @code{condition-case} binds a local |
| 798 | variable to a list of the form @code{(@var{error-symbol} .@: |
| 799 | @var{data})} (@pxref{Handling Errors}). If the error is not handled, |
| 800 | these two values are used in printing the error message. |
| 801 | |
| 802 | The function @code{signal} never returns (though in older Emacs versions |
| 803 | it could sometimes return). |
| 804 | |
| 805 | @smallexample |
| 806 | @group |
| 807 | (signal 'wrong-number-of-arguments '(x y)) |
| 808 | @error{} Wrong number of arguments: x, y |
| 809 | @end group |
| 810 | |
| 811 | @group |
| 812 | (signal 'no-such-error '("My unknown error condition")) |
| 813 | @error{} peculiar error: "My unknown error condition" |
| 814 | @end group |
| 815 | @end smallexample |
| 816 | @end defun |
| 817 | |
| 818 | @cindex CL note---no continuable errors |
| 819 | @quotation |
| 820 | @b{Common Lisp note:} Emacs Lisp has nothing like the Common Lisp |
| 821 | concept of continuable errors. |
| 822 | @end quotation |
| 823 | |
| 824 | @node Processing of Errors |
| 825 | @subsubsection How Emacs Processes Errors |
| 826 | |
| 827 | When an error is signaled, @code{signal} searches for an active |
| 828 | @dfn{handler} for the error. A handler is a sequence of Lisp |
| 829 | expressions designated to be executed if an error happens in part of the |
| 830 | Lisp program. If the error has an applicable handler, the handler is |
| 831 | executed, and control resumes following the handler. The handler |
| 832 | executes in the environment of the @code{condition-case} that |
| 833 | established it; all functions called within that @code{condition-case} |
| 834 | have already been exited, and the handler cannot return to them. |
| 835 | |
| 836 | If there is no applicable handler for the error, the current command is |
| 837 | terminated and control returns to the editor command loop, because the |
| 838 | command loop has an implicit handler for all kinds of errors. The |
| 839 | command loop's handler uses the error symbol and associated data to |
| 840 | print an error message. |
| 841 | |
| 842 | @cindex @code{debug-on-error} use |
| 843 | An error that has no explicit handler may call the Lisp debugger. The |
| 844 | debugger is enabled if the variable @code{debug-on-error} (@pxref{Error |
| 845 | Debugging}) is non-@code{nil}. Unlike error handlers, the debugger runs |
| 846 | in the environment of the error, so that you can examine values of |
| 847 | variables precisely as they were at the time of the error. |
| 848 | |
| 849 | @node Handling Errors |
| 850 | @subsubsection Writing Code to Handle Errors |
| 851 | @cindex error handler |
| 852 | @cindex handling errors |
| 853 | |
| 854 | The usual effect of signaling an error is to terminate the command |
| 855 | that is running and return immediately to the Emacs editor command loop. |
| 856 | You can arrange to trap errors occurring in a part of your program by |
| 857 | establishing an error handler, with the special form |
| 858 | @code{condition-case}. A simple example looks like this: |
| 859 | |
| 860 | @example |
| 861 | @group |
| 862 | (condition-case nil |
| 863 | (delete-file filename) |
| 864 | (error nil)) |
| 865 | @end group |
| 866 | @end example |
| 867 | |
| 868 | @noindent |
| 869 | This deletes the file named @var{filename}, catching any error and |
| 870 | returning @code{nil} if an error occurs. |
| 871 | |
| 872 | The second argument of @code{condition-case} is called the |
| 873 | @dfn{protected form}. (In the example above, the protected form is a |
| 874 | call to @code{delete-file}.) The error handlers go into effect when |
| 875 | this form begins execution and are deactivated when this form returns. |
| 876 | They remain in effect for all the intervening time. In particular, they |
| 877 | are in effect during the execution of functions called by this form, in |
| 878 | their subroutines, and so on. This is a good thing, since, strictly |
| 879 | speaking, errors can be signaled only by Lisp primitives (including |
| 880 | @code{signal} and @code{error}) called by the protected form, not by the |
| 881 | protected form itself. |
| 882 | |
| 883 | The arguments after the protected form are handlers. Each handler |
| 884 | lists one or more @dfn{condition names} (which are symbols) to specify |
| 885 | which errors it will handle. The error symbol specified when an error |
| 886 | is signaled also defines a list of condition names. A handler applies |
| 887 | to an error if they have any condition names in common. In the example |
| 888 | above, there is one handler, and it specifies one condition name, |
| 889 | @code{error}, which covers all errors. |
| 890 | |
| 891 | The search for an applicable handler checks all the established handlers |
| 892 | starting with the most recently established one. Thus, if two nested |
| 893 | @code{condition-case} forms offer to handle the same error, the inner of |
| 894 | the two gets to handle it. |
| 895 | |
| 896 | If an error is handled by some @code{condition-case} form, this |
| 897 | ordinarily prevents the debugger from being run, even if |
| 898 | @code{debug-on-error} says this error should invoke the debugger. |
| 899 | @xref{Error Debugging}. If you want to be able to debug errors that are |
| 900 | caught by a @code{condition-case}, set the variable |
| 901 | @code{debug-on-signal} to a non-@code{nil} value. |
| 902 | |
| 903 | When an error is handled, control returns to the handler. Before this |
| 904 | happens, Emacs unbinds all variable bindings made by binding constructs |
| 905 | that are being exited and executes the cleanups of all |
| 906 | @code{unwind-protect} forms that are exited. Once control arrives at |
| 907 | the handler, the body of the handler is executed. |
| 908 | |
| 909 | After execution of the handler body, execution returns from the |
| 910 | @code{condition-case} form. Because the protected form is exited |
| 911 | completely before execution of the handler, the handler cannot resume |
| 912 | execution at the point of the error, nor can it examine variable |
| 913 | bindings that were made within the protected form. All it can do is |
| 914 | clean up and proceed. |
| 915 | |
| 916 | The @code{condition-case} construct is often used to trap errors that |
| 917 | are predictable, such as failure to open a file in a call to |
| 918 | @code{insert-file-contents}. It is also used to trap errors that are |
| 919 | totally unpredictable, such as when the program evaluates an expression |
| 920 | read from the user. |
| 921 | |
| 922 | Error signaling and handling have some resemblance to @code{throw} and |
| 923 | @code{catch} (@pxref{Catch and Throw}), but they are entirely separate |
| 924 | facilities. An error cannot be caught by a @code{catch}, and a |
| 925 | @code{throw} cannot be handled by an error handler (though using |
| 926 | @code{throw} when there is no suitable @code{catch} signals an error |
| 927 | that can be handled). |
| 928 | |
| 929 | @defspec condition-case var protected-form handlers@dots{} |
| 930 | This special form establishes the error handlers @var{handlers} around |
| 931 | the execution of @var{protected-form}. If @var{protected-form} executes |
| 932 | without error, the value it returns becomes the value of the |
| 933 | @code{condition-case} form; in this case, the @code{condition-case} has |
| 934 | no effect. The @code{condition-case} form makes a difference when an |
| 935 | error occurs during @var{protected-form}. |
| 936 | |
| 937 | Each of the @var{handlers} is a list of the form @code{(@var{conditions} |
| 938 | @var{body}@dots{})}. Here @var{conditions} is an error condition name |
| 939 | to be handled, or a list of condition names; @var{body} is one or more |
| 940 | Lisp expressions to be executed when this handler handles an error. |
| 941 | Here are examples of handlers: |
| 942 | |
| 943 | @smallexample |
| 944 | @group |
| 945 | (error nil) |
| 946 | |
| 947 | (arith-error (message "Division by zero")) |
| 948 | |
| 949 | ((arith-error file-error) |
| 950 | (message |
| 951 | "Either division by zero or failure to open a file")) |
| 952 | @end group |
| 953 | @end smallexample |
| 954 | |
| 955 | Each error that occurs has an @dfn{error symbol} that describes what |
| 956 | kind of error it is. The @code{error-conditions} property of this |
| 957 | symbol is a list of condition names (@pxref{Error Symbols}). Emacs |
| 958 | searches all the active @code{condition-case} forms for a handler that |
| 959 | specifies one or more of these condition names; the innermost matching |
| 960 | @code{condition-case} handles the error. Within this |
| 961 | @code{condition-case}, the first applicable handler handles the error. |
| 962 | |
| 963 | After executing the body of the handler, the @code{condition-case} |
| 964 | returns normally, using the value of the last form in the handler body |
| 965 | as the overall value. |
| 966 | |
| 967 | @cindex error description |
| 968 | The argument @var{var} is a variable. @code{condition-case} does not |
| 969 | bind this variable when executing the @var{protected-form}, only when it |
| 970 | handles an error. At that time, it binds @var{var} locally to an |
| 971 | @dfn{error description}, which is a list giving the particulars of the |
| 972 | error. The error description has the form @code{(@var{error-symbol} |
| 973 | . @var{data})}. The handler can refer to this list to decide what to |
| 974 | do. For example, if the error is for failure opening a file, the file |
| 975 | name is the second element of @var{data}---the third element of the |
| 976 | error description. |
| 977 | |
| 978 | If @var{var} is @code{nil}, that means no variable is bound. Then the |
| 979 | error symbol and associated data are not available to the handler. |
| 980 | @end defspec |
| 981 | |
| 982 | @defun error-message-string error-description |
| 983 | This function returns the error message string for a given error |
| 984 | descriptor. It is useful if you want to handle an error by printing the |
| 985 | usual error message for that error. |
| 986 | @end defun |
| 987 | |
| 988 | @cindex @code{arith-error} example |
| 989 | Here is an example of using @code{condition-case} to handle the error |
| 990 | that results from dividing by zero. The handler displays the error |
| 991 | message (but without a beep), then returns a very large number. |
| 992 | |
| 993 | @smallexample |
| 994 | @group |
| 995 | (defun safe-divide (dividend divisor) |
| 996 | (condition-case err |
| 997 | ;; @r{Protected form.} |
| 998 | (/ dividend divisor) |
| 999 | @end group |
| 1000 | @group |
| 1001 | ;; @r{The handler.} |
| 1002 | (arith-error ; @r{Condition.} |
| 1003 | ;; @r{Display the usual message for this error.} |
| 1004 | (message "%s" (error-message-string err)) |
| 1005 | 1000000))) |
| 1006 | @result{} safe-divide |
| 1007 | @end group |
| 1008 | |
| 1009 | @group |
| 1010 | (safe-divide 5 0) |
| 1011 | @print{} Arithmetic error: (arith-error) |
| 1012 | @result{} 1000000 |
| 1013 | @end group |
| 1014 | @end smallexample |
| 1015 | |
| 1016 | @noindent |
| 1017 | The handler specifies condition name @code{arith-error} so that it will handle only division-by-zero errors. Other kinds of errors will not be handled, at least not by this @code{condition-case}. Thus, |
| 1018 | |
| 1019 | @smallexample |
| 1020 | @group |
| 1021 | (safe-divide nil 3) |
| 1022 | @error{} Wrong type argument: number-or-marker-p, nil |
| 1023 | @end group |
| 1024 | @end smallexample |
| 1025 | |
| 1026 | Here is a @code{condition-case} that catches all kinds of errors, |
| 1027 | including those signaled with @code{error}: |
| 1028 | |
| 1029 | @smallexample |
| 1030 | @group |
| 1031 | (setq baz 34) |
| 1032 | @result{} 34 |
| 1033 | @end group |
| 1034 | |
| 1035 | @group |
| 1036 | (condition-case err |
| 1037 | (if (eq baz 35) |
| 1038 | t |
| 1039 | ;; @r{This is a call to the function @code{error}.} |
| 1040 | (error "Rats! The variable %s was %s, not 35" 'baz baz)) |
| 1041 | ;; @r{This is the handler; it is not a form.} |
| 1042 | (error (princ (format "The error was: %s" err)) |
| 1043 | 2)) |
| 1044 | @print{} The error was: (error "Rats! The variable baz was 34, not 35") |
| 1045 | @result{} 2 |
| 1046 | @end group |
| 1047 | @end smallexample |
| 1048 | |
| 1049 | @node Error Symbols |
| 1050 | @subsubsection Error Symbols and Condition Names |
| 1051 | @cindex error symbol |
| 1052 | @cindex error name |
| 1053 | @cindex condition name |
| 1054 | @cindex user-defined error |
| 1055 | @kindex error-conditions |
| 1056 | |
| 1057 | When you signal an error, you specify an @dfn{error symbol} to specify |
| 1058 | the kind of error you have in mind. Each error has one and only one |
| 1059 | error symbol to categorize it. This is the finest classification of |
| 1060 | errors defined by the Emacs Lisp language. |
| 1061 | |
| 1062 | These narrow classifications are grouped into a hierarchy of wider |
| 1063 | classes called @dfn{error conditions}, identified by @dfn{condition |
| 1064 | names}. The narrowest such classes belong to the error symbols |
| 1065 | themselves: each error symbol is also a condition name. There are also |
| 1066 | condition names for more extensive classes, up to the condition name |
| 1067 | @code{error} which takes in all kinds of errors. Thus, each error has |
| 1068 | one or more condition names: @code{error}, the error symbol if that |
| 1069 | is distinct from @code{error}, and perhaps some intermediate |
| 1070 | classifications. |
| 1071 | |
| 1072 | In order for a symbol to be an error symbol, it must have an |
| 1073 | @code{error-conditions} property which gives a list of condition names. |
| 1074 | This list defines the conditions that this kind of error belongs to. |
| 1075 | (The error symbol itself, and the symbol @code{error}, should always be |
| 1076 | members of this list.) Thus, the hierarchy of condition names is |
| 1077 | defined by the @code{error-conditions} properties of the error symbols. |
| 1078 | |
| 1079 | In addition to the @code{error-conditions} list, the error symbol |
| 1080 | should have an @code{error-message} property whose value is a string to |
| 1081 | be printed when that error is signaled but not handled. If the |
| 1082 | @code{error-message} property exists, but is not a string, the error |
| 1083 | message @samp{peculiar error} is used. |
| 1084 | @cindex peculiar error |
| 1085 | |
| 1086 | Here is how we define a new error symbol, @code{new-error}: |
| 1087 | |
| 1088 | @example |
| 1089 | @group |
| 1090 | (put 'new-error |
| 1091 | 'error-conditions |
| 1092 | '(error my-own-errors new-error)) |
| 1093 | @result{} (error my-own-errors new-error) |
| 1094 | @end group |
| 1095 | @group |
| 1096 | (put 'new-error 'error-message "A new error") |
| 1097 | @result{} "A new error" |
| 1098 | @end group |
| 1099 | @end example |
| 1100 | |
| 1101 | @noindent |
| 1102 | This error has three condition names: @code{new-error}, the narrowest |
| 1103 | classification; @code{my-own-errors}, which we imagine is a wider |
| 1104 | classification; and @code{error}, which is the widest of all. |
| 1105 | |
| 1106 | The error string should start with a capital letter but it should |
| 1107 | not end with a period. This is for consistency with the rest of Emacs. |
| 1108 | |
| 1109 | Naturally, Emacs will never signal @code{new-error} on its own; only |
| 1110 | an explicit call to @code{signal} (@pxref{Signaling Errors}) in your |
| 1111 | code can do this: |
| 1112 | |
| 1113 | @example |
| 1114 | @group |
| 1115 | (signal 'new-error '(x y)) |
| 1116 | @error{} A new error: x, y |
| 1117 | @end group |
| 1118 | @end example |
| 1119 | |
| 1120 | This error can be handled through any of the three condition names. |
| 1121 | This example handles @code{new-error} and any other errors in the class |
| 1122 | @code{my-own-errors}: |
| 1123 | |
| 1124 | @example |
| 1125 | @group |
| 1126 | (condition-case foo |
| 1127 | (bar nil t) |
| 1128 | (my-own-errors nil)) |
| 1129 | @end group |
| 1130 | @end example |
| 1131 | |
| 1132 | The significant way that errors are classified is by their condition |
| 1133 | names---the names used to match errors with handlers. An error symbol |
| 1134 | serves only as a convenient way to specify the intended error message |
| 1135 | and list of condition names. It would be cumbersome to give |
| 1136 | @code{signal} a list of condition names rather than one error symbol. |
| 1137 | |
| 1138 | By contrast, using only error symbols without condition names would |
| 1139 | seriously decrease the power of @code{condition-case}. Condition names |
| 1140 | make it possible to categorize errors at various levels of generality |
| 1141 | when you write an error handler. Using error symbols alone would |
| 1142 | eliminate all but the narrowest level of classification. |
| 1143 | |
| 1144 | @xref{Standard Errors}, for a list of all the standard error symbols |
| 1145 | and their conditions. |
| 1146 | |
| 1147 | @node Cleanups |
| 1148 | @subsection Cleaning Up from Nonlocal Exits |
| 1149 | |
| 1150 | The @code{unwind-protect} construct is essential whenever you |
| 1151 | temporarily put a data structure in an inconsistent state; it permits |
| 1152 | you to make the data consistent again in the event of an error or throw. |
| 1153 | |
| 1154 | @defspec unwind-protect body cleanup-forms@dots{} |
| 1155 | @cindex cleanup forms |
| 1156 | @cindex protected forms |
| 1157 | @cindex error cleanup |
| 1158 | @cindex unwinding |
| 1159 | @code{unwind-protect} executes the @var{body} with a guarantee that the |
| 1160 | @var{cleanup-forms} will be evaluated if control leaves @var{body}, no |
| 1161 | matter how that happens. The @var{body} may complete normally, or |
| 1162 | execute a @code{throw} out of the @code{unwind-protect}, or cause an |
| 1163 | error; in all cases, the @var{cleanup-forms} will be evaluated. |
| 1164 | |
| 1165 | If the @var{body} forms finish normally, @code{unwind-protect} returns |
| 1166 | the value of the last @var{body} form, after it evaluates the |
| 1167 | @var{cleanup-forms}. If the @var{body} forms do not finish, |
| 1168 | @code{unwind-protect} does not return any value in the normal sense. |
| 1169 | |
| 1170 | Only the @var{body} is protected by the @code{unwind-protect}. If any |
| 1171 | of the @var{cleanup-forms} themselves exits nonlocally (via a |
| 1172 | @code{throw} or an error), @code{unwind-protect} is @emph{not} |
| 1173 | guaranteed to evaluate the rest of them. If the failure of one of the |
| 1174 | @var{cleanup-forms} has the potential to cause trouble, then protect it |
| 1175 | with another @code{unwind-protect} around that form. |
| 1176 | |
| 1177 | The number of currently active @code{unwind-protect} forms counts, |
| 1178 | together with the number of local variable bindings, against the limit |
| 1179 | @code{max-specpdl-size} (@pxref{Local Variables}). |
| 1180 | @end defspec |
| 1181 | |
| 1182 | For example, here we make an invisible buffer for temporary use, and |
| 1183 | make sure to kill it before finishing: |
| 1184 | |
| 1185 | @smallexample |
| 1186 | @group |
| 1187 | (save-excursion |
| 1188 | (let ((buffer (get-buffer-create " *temp*"))) |
| 1189 | (set-buffer buffer) |
| 1190 | (unwind-protect |
| 1191 | @var{body} |
| 1192 | (kill-buffer buffer)))) |
| 1193 | @end group |
| 1194 | @end smallexample |
| 1195 | |
| 1196 | @noindent |
| 1197 | You might think that we could just as well write @code{(kill-buffer |
| 1198 | (current-buffer))} and dispense with the variable @code{buffer}. |
| 1199 | However, the way shown above is safer, if @var{body} happens to get an |
| 1200 | error after switching to a different buffer! (Alternatively, you could |
| 1201 | write another @code{save-excursion} around the body, to ensure that the |
| 1202 | temporary buffer becomes current again in time to kill it.) |
| 1203 | |
| 1204 | Emacs includes a standard macro called @code{with-temp-buffer} which |
| 1205 | expands into more or less the code shown above (@pxref{Current Buffer}). |
| 1206 | Several of the macros defined in this manual use @code{unwind-protect} |
| 1207 | in this way. |
| 1208 | |
| 1209 | @findex ftp-login |
| 1210 | Here is an actual example derived from an FTP package. It creates a |
| 1211 | process (@pxref{Processes}) to try to establish a connection to a remote |
| 1212 | machine. As the function @code{ftp-login} is highly susceptible to |
| 1213 | numerous problems that the writer of the function cannot anticipate, it |
| 1214 | is protected with a form that guarantees deletion of the process in the |
| 1215 | event of failure. Otherwise, Emacs might fill up with useless |
| 1216 | subprocesses. |
| 1217 | |
| 1218 | @smallexample |
| 1219 | @group |
| 1220 | (let ((win nil)) |
| 1221 | (unwind-protect |
| 1222 | (progn |
| 1223 | (setq process (ftp-setup-buffer host file)) |
| 1224 | (if (setq win (ftp-login process host user password)) |
| 1225 | (message "Logged in") |
| 1226 | (error "Ftp login failed"))) |
| 1227 | (or win (and process (delete-process process))))) |
| 1228 | @end group |
| 1229 | @end smallexample |
| 1230 | |
| 1231 | This example has a small bug: if the user types @kbd{C-g} to |
| 1232 | quit, and the quit happens immediately after the function |
| 1233 | @code{ftp-setup-buffer} returns but before the variable @code{process} is |
| 1234 | set, the process will not be killed. There is no easy way to fix this bug, |
| 1235 | but at least it is very unlikely. |