@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, 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
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
@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
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
@var{conditions} turned out @code{nil}. (Think about it; which one
did not?)
-For example, this expression tests whether @code{x} is either
+For example, this expression tests whether @code{x} is either
@code{nil} or the integer zero:
@example
@example
@group
(if @var{arg1} @var{arg1}
- (if @var{arg2} @var{arg2}
+ (if @var{arg2} @var{arg2}
@var{arg3}))
@end group
@end example
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
@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
@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
@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}.
- The error 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.
+ 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
-This function signals an error named by @var{error-symbol}. The
+This
+@anchor{Definition of signal}
+@c unfortunately, a page break is allowed if the anchor immediately
+@c follows the @defun, due to hard-to-fix TeXnicalities.
+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 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
@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.}
;; @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 protected by the @code{unwind-protect}. If any
+@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 derived from an FTP package. It creates a
@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