@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
+@c 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/control
@node Control Structures, Variables, Evaluation, Top
@cindex control structures
A Lisp program consists of expressions or @dfn{forms} (@pxref{Forms}).
-We control the order of execution of the forms by enclosing them in
+We control the order of execution of these forms by enclosing them in
@dfn{control structures}. Control structures are special forms which
control when, whether, or how many times to execute the forms they
contain.
level in a file of Lisp code---the forms are executed in the order
written. We call this @dfn{textual order}. For example, if a function
body consists of two forms @var{a} and @var{b}, evaluation of the
-function evaluates first @var{a} and then @var{b}, and the function's
-value is the value of @var{b}.
+function evaluates first @var{a} and then @var{b}. The result of
+evaluating @var{b} becomes the value of the function.
Explicit control structures make possible an order of execution other
than sequential.
@menu
* Sequencing:: Evaluation in textual order.
-* Conditionals:: @code{if}, @code{cond}.
+* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}.
* Combining Conditions:: @code{and}, @code{or}, @code{not}.
* Iteration:: @code{while} loops.
* Nonlocal Exits:: Jumping out of a sequence.
@end example
@noindent
-and it says to execute the forms @var{a}, @var{b}, @var{c} and so on, in
-that order. These forms are called the body of the @code{progn} form.
+and it says to execute the forms @var{a}, @var{b}, @var{c}, and so on, in
+that order. These forms are called the @dfn{body} of the @code{progn} form.
The value of the last form in the body becomes the value of the entire
-@code{progn}.
+@code{progn}. @code{(progn)} returns @code{nil}.
@cindex implicit @code{progn}
In the early days of Lisp, @code{progn} was the only way to execute
the body of a function was made into an ``implicit @code{progn}'':
several forms are allowed just as in the body of an actual @code{progn}.
Many other control structures likewise contain an implicit @code{progn}.
-As a result, @code{progn} is not used as often as it used to be. It is
-needed now most often inside an @code{unwind-protect}, @code{and},
+As a result, @code{progn} is not used as much as it was many years ago.
+It is needed now most often inside an @code{unwind-protect}, @code{and},
@code{or}, or in the @var{then}-part of an @code{if}.
@defspec progn forms@dots{}
@cindex conditional evaluation
Conditional control structures choose among alternatives. Emacs Lisp
-has two conditional forms: @code{if}, which is much the same as in other
-languages, and @code{cond}, which is a generalized case statement.
+has four conditional forms: @code{if}, which is much the same as in
+other languages; @code{when} and @code{unless}, which are variants of
+@code{if}; and @code{cond}, which is a generalized case statement.
@defspec if condition then-form else-forms@dots{}
@code{if} chooses between the @var{then-form} and the @var{else-forms}
non-@code{nil}, @var{then-form} is evaluated and the result returned.
Otherwise, the @var{else-forms} are evaluated in textual order, and the
value of the last one is returned. (The @var{else} part of @code{if} is
-an example of an implicit @code{progn}. @xref{Sequencing}.)
+an example of an implicit @code{progn}. @xref{Sequencing}.)
If @var{condition} has the value @code{nil}, and no @var{else-forms} are
given, @code{if} returns @code{nil}.
@example
@group
-(if nil
- (print 'true)
+(if nil
+ (print 'true)
'very-false)
@result{} very-false
@end group
@end example
@end defspec
+@defmac when condition then-forms@dots{}
+This is a variant of @code{if} where there are no @var{else-forms},
+and possibly several @var{then-forms}. In particular,
+
+@example
+(when @var{condition} @var{a} @var{b} @var{c})
+@end example
+
+@noindent
+is entirely equivalent to
+
+@example
+(if @var{condition} (progn @var{a} @var{b} @var{c}) nil)
+@end example
+@end defmac
+
+@defmac unless condition forms@dots{}
+This is a variant of @code{if} where there is no @var{then-form}:
+
+@example
+(unless @var{condition} @var{a} @var{b} @var{c})
+@end example
+
+@noindent
+is entirely equivalent to
+
+@example
+(if @var{condition} nil
+ @var{a} @var{b} @var{c})
+@end example
+@end defmac
+
@defspec cond clause@dots{}
@code{cond} chooses among an arbitrary number of alternatives. Each
@var{clause} in the @code{cond} must be a list. The @sc{car} of this
never @code{nil}, so this clause never fails, provided the @code{cond}
gets to it at all.
-For example,
+For example,
@example
@group
+(setq a 5)
(cond ((eq a 'hack) 'foo)
(t "default"))
@result{} "default"
@end example
@noindent
-This expression is a @code{cond} which returns @code{foo} if the value
-of @code{a} is 1, and returns the string @code{"default"} otherwise.
+This @code{cond} expression returns @code{foo} if the value of @code{a}
+is @code{hack}, and returns the string @code{"default"} otherwise.
@end defspec
Any conditional construct can be expressed with @code{cond} or with
If any of the @var{conditions} evaluates to @code{nil}, then the result
of the @code{and} must be @code{nil} regardless of the remaining
-@var{conditions}; so @code{and} returns right away, ignoring the
-remaining @var{conditions}.
+@var{conditions}; so @code{and} returns @code{nil} right away, ignoring
+the remaining @var{conditions}.
If all the @var{conditions} turn out non-@code{nil}, then the value of
-the last of them becomes the value of the @code{and} form.
+the last of them becomes the value of the @code{and} form. Just
+@code{(and)}, with no @var{conditions}, returns @code{t}, appropriate
+because all the @var{conditions} turned out non-@code{nil}. (Think
+about it; which one did not?)
Here is an example. The first condition returns the integer 1, which is
not @code{nil}. Similarly, the second condition returns the integer 2,
Note that @code{(car foo)} is not executed if @code{(consp foo)} returns
@code{nil}, thus avoiding an error.
-@code{and} can be expressed in terms of either @code{if} or @code{cond}.
-For example:
+@code{and} expressions can also be written using either @code{if} or
+@code{cond}. Here's how:
@example
@group
returns is the non-@code{nil} value of the condition just evaluated.
If all the @var{conditions} turn out @code{nil}, then the @code{or}
-expression returns @code{nil}.
+expression returns @code{nil}. Just @code{(or)}, with no
+@var{conditions}, returns @code{nil}, appropriate because all the
+@var{conditions} turned out @code{nil}. (Think about it; which one
+did not?)
-For example, this expression tests whether @code{x} is either 0 or
-@code{nil}:
+For example, this expression tests whether @code{x} is either
+@code{nil} or the integer zero:
@example
(or (eq x nil) (eq x 0))
@example
@group
(if @var{arg1} @var{arg1}
- (if @var{arg2} @var{arg2}
+ (if @var{arg2} @var{arg2}
@var{arg3}))
@end group
@end example
@end group
@end example
-If you would like to execute something on each iteration before the
-end-test, put it together with the end-test in a @code{progn} as the
-first argument of @code{while}, as shown here:
+To write a ``repeat...until'' loop, which will execute something on each
+iteration and then do the end-test, put the body followed by the
+end-test in a @code{progn} as the first argument of @code{while}, as
+shown here:
@example
@group
@noindent
This moves forward one line and continues moving by lines until it
-reaches an empty. It is unusual in that the @code{while} has no body,
-just the end test (which also does the real work of moving point).
+reaches an empty line. It is peculiar in that the @code{while} has no
+body, just the end test (which also does the real work of moving point).
@end defspec
+ The @code{dolist} and @code{dotimes} macros provide convenient ways to
+write two common kinds of loops.
+
+@defmac dolist (var list [result]) body@dots{}
+@tindex dolist
+This construct executes @var{body} once for each element of
+@var{list}, binding the variable @var{var} locally to hold the current
+element. Then it returns the value of evaluating @var{result}, or
+@code{nil} if @var{result} is omitted. For example, here is how you
+could use @code{dolist} to define the @code{reverse} function:
+
+@example
+(defun reverse (list)
+ (let (value)
+ (dolist (elt list value)
+ (setq value (cons elt value)))))
+@end example
+@end defmac
+
+@defmac dotimes (var count [result]) body@dots{}
+@tindex dotimes
+This construct executes @var{body} once for each integer from 0
+(inclusive) to @var{count} (exclusive), binding the variable @var{var}
+to the integer for the current iteration. Then it returns the value
+of evaluating @var{result}, or @code{nil} if @var{result} is omitted.
+Here is an example of using @code{dotimes} to do something 100 times:
+
+@example
+(dotimes (i 100)
+ (insert "I will not obey absurd orders\n"))
+@end example
+@end defmac
+
@node Nonlocal Exits
@section Nonlocal Exits
@cindex nonlocal exits
@example
@group
-(catch 'foo
- (progn
- @dots{}
- (throw 'foo t)
- @dots{}))
+(defun foo-outer ()
+ (catch 'foo
+ (foo-inner)))
+
+(defun foo-inner ()
+ @dots{}
+ (if x
+ (throw 'foo t))
+ @dots{})
@end group
@end example
@noindent
-The @code{throw} transfers control straight back to the corresponding
-@code{catch}, which returns immediately. The code following the
-@code{throw} is not executed. The second argument of @code{throw} is used
-as the return value of the @code{catch}.
-
- The @code{throw} and the @code{catch} are matched through the first
-argument: @code{throw} searches for a @code{catch} whose first argument
-is @code{eq} to the one specified. Thus, in the above example, the
-@code{throw} specifies @code{foo}, and the @code{catch} specifies the
-same symbol, so that @code{catch} is applicable. If there is more than
-one applicable @code{catch}, the innermost one takes precedence.
+The @code{throw} form, if executed, transfers control straight back to
+the corresponding @code{catch}, which returns immediately. The code
+following the @code{throw} is not executed. The second argument of
+@code{throw} is used as the return value of the @code{catch}.
+
+ The function @code{throw} finds the matching @code{catch} based on the
+first argument: it searches for a @code{catch} whose first argument is
+@code{eq} to the one specified in the @code{throw}. If there is more
+than one applicable @code{catch}, the innermost one takes precedence.
+Thus, in the above example, the @code{throw} specifies @code{foo}, and
+the @code{catch} in @code{foo-outer} specifies the same symbol, so that
+@code{catch} is the applicable one (assuming there is no other matching
+@code{catch} in between).
Executing @code{throw} exits all Lisp constructs up to the matching
@code{catch}, including function calls. When binding constructs such as
@defspec catch tag body@dots{}
@cindex tag on run time stack
-@code{catch} establishes a return point for the @code{throw} function. The
-return point is distinguished from other such return points by @var{tag},
-which may be any Lisp object. The argument @var{tag} is evaluated normally
-before the return point is established.
+@code{catch} establishes a return point for the @code{throw} function.
+The return point is distinguished from other such return points by
+@var{tag}, which may be any Lisp object except @code{nil}. The argument
+@var{tag} is evaluated normally before the return point is established.
With the return point in effect, @code{catch} evaluates the forms of the
-@var{body} in textual order. If the forms execute normally, without
-error or nonlocal exit, the value of the last body form is returned from
+@var{body} in textual order. If the forms execute normally (without
+error or nonlocal exit) the value of the last body form is returned from
the @code{catch}.
-If a @code{throw} is done within @var{body} specifying the same value
-@var{tag}, the @code{catch} exits immediately; the value it returns is
-whatever was specified as the second argument of @code{throw}.
+If a @code{throw} is executed during the execution of @var{body},
+specifying the same value @var{tag}, the @code{catch} form exits
+immediately; the value it returns is whatever was specified as the
+second argument of @code{throw}.
@end defspec
@defun throw tag value
@end group
@group
-(catch 'hack
+(catch 'hack
(print (catch2 'hack))
'no)
@print{} yes
Now let's change the argument given to @code{catch2}:
@example
-@group
-(defun catch2 (tag)
- (catch tag
- (throw 'hack 'yes)))
-@result{} catch2
-@end group
-
@group
(catch 'hack
(print (catch2 'quux))
@subsubsection How to Signal an Error
@cindex signaling errors
+ @dfn{Signaling} an error means beginning error processing. Error
+processing normally aborts all or part of the running program and
+returns to a point that is set up to handle the error
+(@pxref{Processing of Errors}). Here we describe how to signal an
+error.
+
Most errors are signaled ``automatically'' within Lisp primitives
which you call for other purposes, such as if you try to take the
@sc{car} of an integer or move forward a character at the end of the
-buffer; you can also signal errors explicitly with the functions
+buffer. You can also signal errors explicitly with the functions
@code{error} and @code{signal}.
- Quitting, which happens when the user types @kbd{C-g}, is not
+ Quitting, which happens when the user types @kbd{C-g}, is not
considered an error, but it is handled almost like an error.
@xref{Quitting}.
+ Every error specifies an error message, one way or another. The
+message should state what is wrong (``File does not exist''), not how
+things ought to be (``File must exist''). The convention in Emacs
+Lisp is that error messages should start with a capital letter, but
+should not end with any sort of punctuation.
+
@defun error format-string &rest args
This function signals an error with an error message constructed by
-applying @code{format} (@pxref{String Conversion}) to
+applying @code{format} (@pxref{Formatting Strings}) to
@var{format-string} and @var{args}.
These examples show typical uses of @code{error}:
@example
@group
-(error "You have committed an error.
- Try something else.")
- @error{} You have committed an error.
- Try something else.
+(error "That is an error -- try something else")
+ @error{} That is an error -- try something else
@end group
@group
-(error "You have committed %d errors." 10)
- @error{} You have committed 10 errors.
+(error "You have committed %d errors" 10)
+ @error{} You have committed 10 errors
@end group
@end example
error symbol @code{error}, and a list containing the string returned by
@code{format}.
-If you want to use your own string as an error message verbatim, don't
-just write @code{(error @var{string})}. If @var{string} contains
-@samp{%}, it will be interpreted as a format specifier, with undesirable
-results. Instead, use @code{(error "%s" @var{string})}.
+@strong{Warning:} If you want to use your own string as an error message
+verbatim, don't just write @code{(error @var{string})}. If @var{string}
+contains @samp{%}, it will be interpreted as a format specifier, with
+undesirable results. Instead, use @code{(error "%s" @var{string})}.
@end defun
@defun signal error-symbol data
+@anchor{Definition of signal}
This function signals an error named by @var{error-symbol}. The
argument @var{data} is a list of additional Lisp objects relevant to the
circumstances of the error.
The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol
bearing a property @code{error-conditions} whose value is a list of
condition names. This is how Emacs Lisp classifies different sorts of
-errors.
+errors. @xref{Error Symbols}, for a description of error symbols,
+error conditions and condition names.
+
+If the error is not handled, the two arguments are used in printing
+the error message. Normally, this error message is provided by the
+@code{error-message} property of @var{error-symbol}. If @var{data} is
+non-@code{nil}, this is followed by a colon and a comma separated list
+of the unevaluated elements of @var{data}. For @code{error}, the
+error message is the @sc{car} of @var{data} (that must be a string).
+Subcategories of @code{file-error} are handled specially.
The number and significance of the objects in @var{data} depends on
@var{error-symbol}. For example, with a @code{wrong-type-arg} error,
-there are two objects in the list: a predicate that describes the type
+there should be two objects in the list: a predicate that describes the type
that was expected, and the object that failed to fit that type.
-@xref{Error Symbols}, for a description of error symbols.
Both @var{error-symbol} and @var{data} are available to any error
handlers that handle the error: @code{condition-case} binds a local
variable to a list of the form @code{(@var{error-symbol} .@:
-@var{data})} (@pxref{Handling Errors}). If the error is not handled,
-these two values are used in printing the error message.
+@var{data})} (@pxref{Handling Errors}).
The function @code{signal} never returns (though in older Emacs versions
it could sometimes return).
@end group
@group
-(signal 'no-such-error '("My unknown error condition."))
- @error{} peculiar error: "My unknown error condition."
+(signal 'no-such-error '("My unknown error condition"))
+ @error{} peculiar error: "My unknown error condition"
@end group
@end smallexample
@end defun
The search for an applicable handler checks all the established handlers
starting with the most recently established one. Thus, if two nested
@code{condition-case} forms offer to handle the same error, the inner of
-the two will actually handle it.
+the two gets to handle it.
+
+ If an error is handled by some @code{condition-case} form, this
+ordinarily prevents the debugger from being run, even if
+@code{debug-on-error} says this error should invoke the debugger.
+@xref{Error Debugging}. If you want to be able to debug errors that are
+caught by a @code{condition-case}, set the variable
+@code{debug-on-signal} to a non-@code{nil} value.
When an error is handled, control returns to the handler. Before this
happens, Emacs unbinds all variable bindings made by binding constructs
@code{unwind-protect} forms that are exited. Once control arrives at
the handler, the body of the handler is executed.
- After execution of the handler body, execution continues by returning
-from the @code{condition-case} form. Because the protected form is
-exited completely before execution of the handler, the handler cannot
-resume execution at the point of the error, nor can it examine variable
+ After execution of the handler body, execution returns from the
+@code{condition-case} form. Because the protected form is exited
+completely before execution of the handler, the handler cannot resume
+execution at the point of the error, nor can it examine variable
bindings that were made within the protected form. All it can do is
clean up and proceed.
- @code{condition-case} is often used to trap errors that are
-predictable, such as failure to open a file in a call to
+ The @code{condition-case} construct is often used to trap errors that
+are predictable, such as failure to open a file in a call to
@code{insert-file-contents}. It is also used to trap errors that are
totally unpredictable, such as when the program evaluates an expression
read from the user.
Error signaling and handling have some resemblance to @code{throw} and
-@code{catch}, but they are entirely separate facilities. An error
-cannot be caught by a @code{catch}, and a @code{throw} cannot be handled
-by an error handler (though using @code{throw} when there is no suitable
-@code{catch} signals an error that can be handled).
+@code{catch} (@pxref{Catch and Throw}), but they are entirely separate
+facilities. An error cannot be caught by a @code{catch}, and a
+@code{throw} cannot be handled by an error handler (though using
+@code{throw} when there is no suitable @code{catch} signals an error
+that can be handled).
@defspec condition-case var protected-form handlers@dots{}
This special form establishes the error handlers @var{handlers} around
returns normally, using the value of the last form in the handler body
as the overall value.
+@cindex error description
The argument @var{var} is a variable. @code{condition-case} does not
bind this variable when executing the @var{protected-form}, only when it
-handles an error. At that time, it binds @var{var} locally to a list of
-the form @code{(@var{error-symbol} . @var{data})}, giving the
-particulars of the error. The handler can refer to this list to decide
-what to do. For example, if the error is for failure opening a file,
-the file name is the second element of @var{data}---the third element of
-@var{var}.
+handles an error. At that time, it binds @var{var} locally to an
+@dfn{error description}, which is a list giving the particulars of the
+error. The error description has the form @code{(@var{error-symbol}
+. @var{data})}. The handler can refer to this list to decide what to
+do. For example, if the error is for failure opening a file, the file
+name is the second element of @var{data}---the third element of the
+error description.
If @var{var} is @code{nil}, that means no variable is bound. Then the
error symbol and associated data are not available to the handler.
@end defspec
+@defun error-message-string error-description
+This function returns the error message string for a given error
+descriptor. It is useful if you want to handle an error by printing the
+usual error message for that error. @xref{Definition of signal}.
+@end defun
+
@cindex @code{arith-error} example
Here is an example of using @code{condition-case} to handle the error
-that results from dividing by zero. The handler prints out a warning
-message and returns a very large number.
+that results from dividing by zero. The handler displays the error
+message (but without a beep), then returns a very large number.
@smallexample
@group
(defun safe-divide (dividend divisor)
- (condition-case err
+ (condition-case err
;; @r{Protected form.}
- (/ dividend divisor)
+ (/ dividend divisor)
+@end group
+@group
;; @r{The handler.}
(arith-error ; @r{Condition.}
- (princ (format "Arithmetic error: %s" err))
+ ;; @r{Display the usual message for this error.}
+ (message "%s" (error-message-string err))
1000000)))
@result{} safe-divide
@end group
@smallexample
@group
(safe-divide nil 3)
- @error{} Wrong type argument: integer-or-marker-p, nil
+ @error{} Wrong type argument: number-or-marker-p, nil
@end group
@end smallexample
(if (eq baz 35)
t
;; @r{This is a call to the function @code{error}.}
- (error "Rats! The variable %s was %s, not 35." 'baz baz))
+ (error "Rats! The variable %s was %s, not 35" 'baz baz))
;; @r{This is the handler; it is not a form.}
- (error (princ (format "The error was: %s" err))
+ (error (princ (format "The error was: %s" err))
2))
-@print{} The error was: (error "Rats! The variable baz was 34, not 35.")
+@print{} The error was: (error "Rats! The variable baz was 34, not 35")
@result{} 2
@end group
@end smallexample
names}. The narrowest such classes belong to the error symbols
themselves: each error symbol is also a condition name. There are also
condition names for more extensive classes, up to the condition name
-@code{error} which takes in all kinds of errors. Thus, each error has
-one or more condition names: @code{error}, the error symbol if that
-is distinct from @code{error}, and perhaps some intermediate
-classifications.
+@code{error} which takes in all kinds of errors (but not @code{quit}).
+Thus, each error has one or more condition names: @code{error}, the
+error symbol if that is distinct from @code{error}, and perhaps some
+intermediate classifications.
In order for a symbol to be an error symbol, it must have an
@code{error-conditions} property which gives a list of condition names.
(The error symbol itself, and the symbol @code{error}, should always be
members of this list.) Thus, the hierarchy of condition names is
defined by the @code{error-conditions} properties of the error symbols.
+Because quitting is not considered an error, the value of the
+@code{error-conditions} property of @code{quit} is just @code{(quit)}.
+@cindex peculiar error
In addition to the @code{error-conditions} list, the error symbol
should have an @code{error-message} property whose value is a string to
be printed when that error is signaled but not handled. If the
+error symbol has no @code{error-message} property or if the
@code{error-message} property exists, but is not a string, the error
-message @samp{peculiar error} is used.
-@cindex peculiar error
+message @samp{peculiar error} is used. @xref{Definition of signal}.
Here is how we define a new error symbol, @code{new-error}:
@group
(put 'new-error
'error-conditions
- '(error my-own-errors new-error))
+ '(error my-own-errors new-error))
@result{} (error my-own-errors new-error)
@end group
@group
This error has three condition names: @code{new-error}, the narrowest
classification; @code{my-own-errors}, which we imagine is a wider
classification; and @code{error}, which is the widest of all.
-
+
+ The error string should start with a capital letter but it should
+not end with a period. This is for consistency with the rest of Emacs.
+
Naturally, Emacs will never signal @code{new-error} on its own; only
-an explicit call to @code{signal} (@pxref{Signaling Errors}) in your
-code can do this:
+an explicit call to @code{signal} (@pxref{Definition of signal}) in
+your code can do this:
@example
@group
The @code{unwind-protect} construct is essential whenever you
temporarily put a data structure in an inconsistent state; it permits
-you to ensure the data are consistent in the event of an error or throw.
+you to make the data consistent again in the event of an error or
+throw. (Another more specific cleanup construct that is used only for
+changes in buffer contents is the atomic change group; @ref{Atomic
+Changes}.)
-@defspec unwind-protect body cleanup-forms@dots{}
+@defspec unwind-protect body-form cleanup-forms@dots{}
@cindex cleanup forms
@cindex protected forms
@cindex error cleanup
@cindex unwinding
-@code{unwind-protect} executes the @var{body} with a guarantee that the
-@var{cleanup-forms} will be evaluated if control leaves @var{body}, no
-matter how that happens. The @var{body} may complete normally, or
-execute a @code{throw} out of the @code{unwind-protect}, or cause an
-error; in all cases, the @var{cleanup-forms} will be evaluated.
-
-If the @var{body} forms finish normally, @code{unwind-protect} returns
-the value of the last @var{body} form, after it evaluates the
-@var{cleanup-forms}. If the @var{body} forms do not finish,
-@code{unwind-protect} does not return any value in the normal sense.
-
-Only the @var{body} is actually protected by the @code{unwind-protect}.
-If any of the @var{cleanup-forms} themselves exits nonlocally (e.g., via
-a @code{throw} or an error), @code{unwind-protect} is @emph{not}
+@code{unwind-protect} executes @var{body-form} with a guarantee that
+the @var{cleanup-forms} will be evaluated if control leaves
+@var{body-form}, no matter how that happens. @var{body-form} may
+complete normally, or execute a @code{throw} out of the
+@code{unwind-protect}, or cause an error; in all cases, the
+@var{cleanup-forms} will be evaluated.
+
+If @var{body-form} finishes normally, @code{unwind-protect} returns the
+value of @var{body-form}, after it evaluates the @var{cleanup-forms}.
+If @var{body-form} does not finish, @code{unwind-protect} does not
+return any value in the normal sense.
+
+Only @var{body-form} is protected by the @code{unwind-protect}. If any
+of the @var{cleanup-forms} themselves exits nonlocally (via a
+@code{throw} or an error), @code{unwind-protect} is @emph{not}
guaranteed to evaluate the rest of them. If the failure of one of the
-@var{cleanup-forms} has the potential to cause trouble, then protect it
-with another @code{unwind-protect} around that form.
+@var{cleanup-forms} has the potential to cause trouble, then protect
+it with another @code{unwind-protect} around that form.
The number of currently active @code{unwind-protect} forms counts,
together with the number of local variable bindings, against the limit
-@code{max-specpdl-size} (@pxref{Local Variables}).
+@code{max-specpdl-size} (@pxref{Definition of max-specpdl-size,, Local
+Variables}).
@end defspec
For example, here we make an invisible buffer for temporary use, and
(let ((buffer (get-buffer-create " *temp*")))
(set-buffer buffer)
(unwind-protect
- @var{body}
+ @var{body-form}
(kill-buffer buffer))))
@end group
@end smallexample
@noindent
You might think that we could just as well write @code{(kill-buffer
(current-buffer))} and dispense with the variable @code{buffer}.
-However, the way shown above is safer, if @var{body} happens to get an
-error after switching to a different buffer! (Alternatively, you could
-write another @code{save-excursion} around the body, to ensure that the
-temporary buffer becomes current in time to kill it.)
+However, the way shown above is safer, if @var{body-form} happens to
+get an error after switching to a different buffer! (Alternatively,
+you could write another @code{save-excursion} around @var{body-form},
+to ensure that the temporary buffer becomes current again in time to
+kill it.)
+
+ Emacs includes a standard macro called @code{with-temp-buffer} which
+expands into more or less the code shown above (@pxref{Definition of
+with-temp-buffer,, Current Buffer}). Several of the macros defined in
+this manual use @code{unwind-protect} in this way.
@findex ftp-login
- Here is an actual example taken from the file @file{ftp.el}. It
-creates a process (@pxref{Processes}) to try to establish a connection
-to a remote machine. As the function @code{ftp-login} is highly
-susceptible to numerous problems that the writer of the function cannot
-anticipate, it is protected with a form that guarantees deletion of the
-process in the event of failure. Otherwise, Emacs might fill up with
-useless subprocesses.
+ Here is an actual example derived from an FTP package. It creates a
+process (@pxref{Processes}) to try to establish a connection to a remote
+machine. As the function @code{ftp-login} is highly susceptible to
+numerous problems that the writer of the function cannot anticipate, it
+is protected with a form that guarantees deletion of the process in the
+event of failure. Otherwise, Emacs might fill up with useless
+subprocesses.
@smallexample
@group
@end group
@end smallexample
- This example actually has a small bug: if the user types @kbd{C-g} to
+ This example has a small bug: if the user types @kbd{C-g} to
quit, and the quit happens immediately after the function
@code{ftp-setup-buffer} returns but before the variable @code{process} is
set, the process will not be killed. There is no easy way to fix this bug,
but at least it is very unlikely.
- Here is another example which uses @code{unwind-protect} to make sure
-to kill a temporary buffer. In this example, the value returned by
-@code{unwind-protect} is used.
-
-@example
-(defun shell-command-string (cmd)
- "Return the output of the shell command CMD, as a string."
- (save-excursion
- (set-buffer (generate-new-buffer " OS*cmd"))
- (shell-command cmd t)
- (unwind-protect
- (buffer-string)
- (kill-buffer (current-buffer)))))
-@end example
+@ignore
+ arch-tag: 8abc30d4-4d3a-47f9-b908-e9e971c18c6d
+@end ignore