@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@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 Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/control
@node Control Structures, Variables, Evaluation, Top
@cindex special forms for control structures
@cindex control structures
- A Lisp program consists of expressions or @dfn{forms} (@pxref{Forms}).
-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.
+ A Lisp program consists of a set of @dfn{expressions}, or
+@dfn{forms} (@pxref{Forms}). 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.
+@cindex textual order
The simplest order of execution is sequential execution: first form
@var{a}, then form @var{b}, and so on. This is what happens when you
write several forms in succession in the body of a function, or at top
@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 ``goto.'')
Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j}
varying from 0 to 9:
@noindent
This deletes the file named @var{filename}, catching any error and
-returning @code{nil} if an error occurs@footnote{
-Actually, you should use @code{ignore-errors} in such a simple case;
-see below.}.
+returning @code{nil} if an error occurs. (You can use the macro
+@code{ignore-errors} for a simple case like this; see below.)
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
given error will invoke the debugger only if @code{debug-on-error} and
the other usual filtering mechanisms say it should. @xref{Error Debugging}.
+@defmac condition-case-unless-debug var protected-form handlers@dots{}
+The macro @code{condition-case-unless-debug} provides another way to
+handle debugging of such forms. It behaves exactly like
+@code{condition-case}, unless the variable @code{debug-on-error} is
+non-@code{nil}, in which case it does not handle any errors at all.
+@end defmac
+
Once Emacs decides that a certain handler handles the error, it
returns control to that handler. To do so, Emacs unbinds all variable
bindings made by binding constructs that are being exited, and
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.
+
+@cindex rethrow a signal
+Sometimes it is necessary to re-throw a signal caught by
+@code{condition-case}, for some outer-level handler to catch. Here's
+how to do that:
+
+@smallexample
+ (signal (car err) (cdr err))
+@end smallexample
+
+@noindent
+where @code{err} is the error description variable, the first argument
+to @code{condition-case} whose error condition you want to re-throw.
+@xref{Definition of signal}.
@end defspec
-@defun error-message-string error-description
+@defun error-message-string error-descriptor
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 smallexample
@end defmac
+@defmac with-demoted-errors body@dots{}
+This macro is like a milder version of @code{ignore-errors}. Rather
+than suppressing errors altogether, it converts them into messages.
+Use this form around code that is not expected to signal errors, but
+should be robust if one does occur. Note that this macro uses
+@code{condition-case-unless-debug} rather than @code{condition-case}.
+@end defmac
+
@node Error Symbols
@subsubsection Error Symbols and Condition Names
@cindex error symbol
@smallexample
@group
-(save-excursion
- (let ((buffer (get-buffer-create " *temp*")))
- (set-buffer buffer)
+(let ((buffer (get-buffer-create " *temp*")))
+ (with-current-buffer buffer
(unwind-protect
@var{body-form}
(kill-buffer buffer))))
(current-buffer))} and dispense with the variable @code{buffer}.
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},
+you could write a @code{save-current-buffer} around @var{body-form},
to ensure that the temporary buffer becomes current again in time to
kill it.)
@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