@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003
-@c 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
@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}.
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
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},
-using the variable @var{var} 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:
+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)
@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), using the variable @var{var} to
-hold the integer for the current iteration. Then it returns the value
+(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:
@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:
@subsubsection How to Signal an Error
@cindex signaling errors
- @dfn{Signalling} an error means beginning error processing. Error
+ @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
@end defun
@defun signal error-symbol data
+This
@anchor{Definition of signal}
-This function signals an error named by @var{error-symbol}. The
+@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.
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 @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-form cleanup-forms@dots{}
@cindex cleanup forms