@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
+@c 2003, 2004, 2005, 2006, 2007, 2008 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.
@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{}
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 defspec
@defmac when condition then-forms@dots{}
-@tindex when
This is a variant of @code{if} where there are no @var{else-forms},
and possibly several @var{then-forms}. In particular,
@end defmac
@defmac unless condition forms@dots{}
-@tindex condition
This is a variant of @code{if} where there is no @var{then-form}:
@example
@var{body-forms}, and the value of the last of @var{body-forms} becomes
the value of the @code{cond}. The remaining clauses are ignored.
-If the value of @var{condition} is @code{nil}, the clause ``fails'', so
+If the value of @var{condition} is @code{nil}, the clause ``fails,'' so
the @code{cond} moves on to the following clause, trying its
@var{condition}.
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 @code{hack}, 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
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{}
+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{}
+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
@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
@subsection Examples of @code{catch} and @code{throw}
One way to use @code{catch} and @code{throw} is to exit from a doubly
-nested loop. (In most languages, this would be done with a ``go to''.)
+nested loop. (In most languages, this would be done with a ``go to.'')
Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j}
varying from 0 to 9:
@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}:
@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.
+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 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).
established it; all functions called within that @code{condition-case}
have already been exited, and the handler cannot return to them.
-If there is no applicable handler for the error, the current command is
-terminated and control returns to the editor command loop, because the
-command loop has an implicit handler for all kinds of errors. The
+If there is no applicable handler for the error, it terminates the
+current command and returns control to the editor command loop. (The
+command loop has an implicit handler for all kinds of errors.) The
command loop's handler uses the error symbol and associated data to
-print an error message.
+print an error message. You can use the variable
+@code{command-error-function} to control how this is done:
+
+@defvar command-error-function
+This variable, if non-@code{nil}, specifies a function to use to
+handle errors that return control to the Emacs command loop. The
+function should take three arguments: @var{data}, a list of the same
+form that @code{condition-case} would bind to its variable;
+@var{context}, a string describing the situation in which the error
+occurred, or (more often) @code{nil}; and @var{caller}, the Lisp
+function which called the primitive that signaled the error.
+@end defvar
@cindex @code{debug-on-error} use
An error that has no explicit handler may call the Lisp debugger. The
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
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
@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.
+usual error message for that error. @xref{Definition of signal}.
@end defun
@cindex @code{arith-error} example
@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.}
;; @r{Display the usual message for this error.}
;; @r{This is a call to the function @code{error}.}
(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")
@result{} 2
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
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 make the data consistent again 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 again 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{Current Buffer}).
-Several of the macros defined in this manual use @code{unwind-protect}
-in this way.
+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.
+
+@ignore
+ arch-tag: 8abc30d4-4d3a-47f9-b908-e9e971c18c6d
+@end ignore