@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
-@c 2004, 2005, 2006 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
+@c 2003, 2004, 2005, 2006, 2007 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}.
@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:
@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
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
This deletes the file named @var{filename}, catching any error and
returning @code{nil} if an error occurs.
+ 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.
+
The second argument of @code{condition-case} is called the
@dfn{protected form}. (In the example above, the protected form is a
call to @code{delete-file}.) The error handlers go into effect when
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
-that are being exited and executes the cleanups of all
-@code{unwind-protect} forms that are exited. Once control arrives at
-the handler, the body of the handler is executed.
+ 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. You can also specify that a particular handler
+should let the debugger run first, by writing @code{debug} among the
+conditions, like this:
+
+@example
+@group
+(condition-case nil
+ (delete-file filename)
+ ((debug error) nil))
+@end group
+@end example
+
+@noindent
+The effect of @code{debug} here is only to prevent
+@code{condition-case} from suppressing the call to the debugger. Any
+given error will invoke the debugger only if @code{debug-on-error} and
+the other usual filtering mechanisms say it should. @xref{Error Debugging}.
+
+ 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
+executes the cleanups of all @code{unwind-protect} forms that are
+being exited. Once control arrives at the handler, the body of the
+handler executes normally.
After execution of the handler body, execution returns from the
@code{condition-case} form. Because the protected form is exited
bindings that were made within the protected form. All it can do is
clean up and proceed.
- 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} (@pxref{Catch and Throw}), but they are entirely separate
facilities. An error cannot be caught by a @code{catch}, and a
Each of the @var{handlers} is a list of the form @code{(@var{conditions}
@var{body}@dots{})}. Here @var{conditions} is an error condition name
-to be handled, or a list of condition names; @var{body} is one or more
+to be handled, or a list of condition names (which can include @code{debug}
+to allow the debugger to run before the handler); @var{body} is one or more
Lisp expressions to be executed when this handler handles an error.
Here are examples of handlers:
HCoop / bpt / emacs.git / blobdiff