comparison lispref/control.texi @ 21682:90da2489c498

*** empty log message ***

21681:11eafe90b842

@end group
@end example

@noindent
This moves forward one line and continues moving by lines until it
reaches an empty.  It is unusual in that the @code{while} has no body,
just the end test (which also does the real work of moving point).
@end defspec

@node Nonlocal Exits
@section Nonlocal Exits
@cindex nonlocal exits

These examples show typical uses of @code{error}:

@example
@group
(error "You have committed an error.  
        Try something else.")
     @error{} You have committed an error.  
        Try something else.
@end group

@group
(error "You have committed %d errors." 10)
     @error{} You have committed 10 errors.  
@end group
@end example

@code{error} works by calling @code{signal} with two arguments: the
error symbol @code{error}, and a list containing the string returned by

condition names.  This is how Emacs Lisp classifies different sorts of
errors.

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 are 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

(signal 'wrong-number-of-arguments '(x y))
     @error{} Wrong number of arguments: x, y
@end group

@group
(signal 'no-such-error '("My unknown error condition."))
     @error{} peculiar error: "My unknown error condition."
@end group
@end smallexample
@end defun

@cindex CL note---no continuable errors

completely before execution of the handler, the handler cannot resume
execution at the point of the error, nor can it examine variable
bindings that were made within the protected form.  All it can do is
clean up and proceed.

  @code{condition-case} 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

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 in time to kill it.)

@findex ftp-login
  Here is an actual example taken from the file @file{ftp.el}.  It
creates a process (@pxref{Processes}) to try to establish a connection
to a remote machine.  As the function @code{ftp-login} is highly

  This example actually has a small bug: if the user types @kbd{C-g} to
quit, and the quit happens immediately after the function
@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.

  Here is another example which uses @code{unwind-protect} to make sure
to kill a temporary buffer.  In this example, the value returned by
@code{unwind-protect} is used.

@smallexample
(defun shell-command-string (cmd)
  "Return the output of the shell command CMD, as a string."
  (save-excursion
    (set-buffer (generate-new-buffer " OS*cmd"))
    (shell-command cmd t)
    (unwind-protect
        (buffer-string)
      (kill-buffer (current-buffer)))))
@end smallexample

21682:90da2489c498

@end group
@end example

@noindent
This moves forward one line and continues moving by lines until it
reaches an empty line.  It is peculiar in that the @code{while} has no
body, just the end test (which also does the real work of moving point).
@end defspec

@node Nonlocal Exits
@section Nonlocal Exits
@cindex nonlocal exits

These examples show typical uses of @code{error}:

@example
@group
(error "That is an error -- try something else")
     @error{} That is an error -- try something else
@end group

@group
(error "You have committed %d errors" 10)
     @error{} You have committed 10 errors
@end group
@end example

@code{error} works by calling @code{signal} with two arguments: the
error symbol @code{error}, and a list containing the string returned by

condition names.  This is how Emacs Lisp classifies different sorts of
errors.

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

(signal 'wrong-number-of-arguments '(x y))
     @error{} Wrong number of arguments: x, y
@end group

@group
(signal 'no-such-error '("My unknown error condition"))
     @error{} peculiar error: "My unknown error condition"
@end group
@end smallexample
@end defun

@cindex CL note---no continuable errors

completely before execution of the handler, the handler cannot resume
execution at the point of the error, nor can it examine variable
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

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.)

  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.

@findex ftp-login
  Here is an actual example taken from the file @file{ftp.el}.  It
creates a process (@pxref{Processes}) to try to establish a connection
to a remote machine.  As the function @code{ftp-login} is highly

  This example actually has a small bug: if the user types @kbd{C-g} to
quit, and the quit happens immediately after the function
@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.