mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-24 10:38:38 +00:00
Various small changes in addition to the following.
(Signaling Errors): Provide some more details on how `signal' constructs the error message. Add anchor to the definition of `signal'. (Error Symbols): Describe special treatment of `quit'. (Cleanups): Rename BODY argument of `unwind-protect' to BODY-FORM to emphasize that it has to be a single form.
This commit is contained in:
parent
33dfaf11e0
commit
a8d6af5812
@ -496,7 +496,7 @@ 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
|
||||
of evaluating @var{result}, or @code{nil} if @var{result} is omitted.
|
||||
Here is an example of using @code{dotimes} do something 100 times:
|
||||
Here is an example of using @code{dotimes} to do something 100 times:
|
||||
|
||||
@example
|
||||
(dotimes (i 100)
|
||||
@ -757,7 +757,7 @@ 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}:
|
||||
@ -784,6 +784,7 @@ contains @samp{%}, it will be interpreted as a format specifier, with
|
||||
undesirable results. Instead, use @code{(error "%s" @var{string})}.
|
||||
@end defun
|
||||
|
||||
@anchor{Definition of signal}
|
||||
@defun signal error-symbol data
|
||||
This function signals an error named by @var{error-symbol}. The
|
||||
argument @var{data} is a list of additional Lisp objects relevant to the
|
||||
@ -792,19 +793,26 @@ 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).
|
||||
@ -989,7 +997,7 @@ error symbol and associated data are not available to the handler.
|
||||
@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
|
||||
@ -1071,10 +1079,10 @@ classes called @dfn{error conditions}, identified by @dfn{condition
|
||||
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.
|
||||
@ -1082,13 +1090,16 @@ This list defines the conditions that this kind of error belongs to.
|
||||
(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}:
|
||||
|
||||
@ -1114,8 +1125,8 @@ classification; and @code{error}, which is the widest of all.
|
||||
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
|
||||
@ -1158,32 +1169,34 @@ and their conditions.
|
||||
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.
|
||||
|
||||
@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.
|
||||
@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 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.
|
||||
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 the @var{body} is protected by the @code{unwind-protect}. If any
|
||||
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
|
||||
@ -1195,7 +1208,7 @@ make sure to kill it before finishing:
|
||||
(let ((buffer (get-buffer-create " *temp*")))
|
||||
(set-buffer buffer)
|
||||
(unwind-protect
|
||||
@var{body}
|
||||
@var{body-form}
|
||||
(kill-buffer buffer))))
|
||||
@end group
|
||||
@end smallexample
|
||||
@ -1203,15 +1216,16 @@ make sure to kill it before finishing:
|
||||
@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
|
||||
|
Loading…
Reference in New Issue
Block a user