bug#68075: 30.0.50; New special form `handler-bind`

[Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

> See patch below for my attempt to clarify.

Sigh!

Here it is,


        Stefan


diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 4107963eed5..e63660206d0 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -2311,24 +2311,100 @@ Handling Errors
 @code{(@var{conditions} @var{handler})} where @var{conditions} is an
 error condition name to be handled, or a list of condition names, and
 @var{handler} should be a form whose evaluation should return a function.
+As with @code{condition-case}, condition names are symbols.
 
 Before running @var{body}, @code{handler-bind} evaluates all the
 @var{handler} forms and installs those handlers to be active during
-the evaluation of @var{body}.  These handlers are searched together
-with those installed by @code{condition-case}.  When the innermost
+the evaluation of @var{body}.  When an error is signaled,
+Emacs searches all the active @code{condition-case} and
+@code{handler-bind} forms for a handler that
+specifies one or more of these condition names.  When the innermost
 matching handler is one installed by @code{handler-bind}, the
 @var{handler} function is called with a single argument holding the
 error description.
 
-@var{handler} is called in the dynamic context where the error
-happened, without first unwinding the stack, meaning that all the
-dynamic bindings are still in effect, except that all the error
-handlers between the code that signaled the error and the
-@code{handler-bind} are temporarily suspended.  Like any normal
-function, @var{handler} can exit non-locally, typically via
-@code{throw}, or it can return normally.  If @var{handler} returns
-normally, it means the handler @emph{declined} to handle the error and
-the search for an error handler is continued where it left off.
+Contrary to what happens with @code{condition-case}, @var{handler} is
+called in the dynamic context where the error happened, without
+unbinding any variable bindings or running any cleanups of
+@code{unwind-protect}, so that all those dynamic bindings are still in
+effect.  There is one exception: while running the @var{handler}
+function, all the error handlers between the code that signaled the
+error and the @code{handler-bind} are temporarily suspended, meaning
+that when an error is signaled, Emacs will only search the active
+@code{condition-case} and @code{handler-bind} forms that are inside
+the @var{handler} function or outside of the current
+@code{handler-bind}.
+
+Like any normal function, @var{handler} can exit non-locally,
+typically via @code{throw}, or it can return normally.
+If @var{handler} returns normally, it means the handler
+@emph{declined} to handle the error and the search for an error
+handler is continued where it left off.
+
+For example, if we wanted to keep a log of all the errors that occur
+during the execution of a particular piece of code together with the
+buffer that's current when the error is signaled, but without
+otherwise affecting the behavior of that code, we can do it with:
+
+@example
+@group
+(handler-bind
+    ((error
+      (lambda (err)
+        (push (cons err (current-buffer)) my-log-of-errors))))
+  @var{body-forms}@dots{})
+@end group
+@end example
+
+This will log only those errors that are not caught internally to
+@var{body-forms}@dots{}, in other words errors that ``escape'' from
+@var{body-forms}@dots{}, and it will not prevent those errors from
+being passed on to surrounding @code{condition-case} handlers (or
+@code{handler-bind} handlers for that matter) since the above handler
+returns normally.
+
+We can also use @code{handler-bind} to replace an error with another,
+as in the code below which turns all errors of type @code{user-error}
+that occur during the execution of @var{body-forms}@dots{} into plain
+@code{error}:
+
+@example
+@group
+(handler-bind
+    ((user-error
+      (lambda (err)
+        (signal 'error (cdr err)))))
+  @var{body-forms}@dots{})
+@end group
+@end example
+
+We can get almost the same result with @code{condition-case}:
+
+@example
+@group
+(condition-case err
+    (progn @var{body-forms}@dots{})
+  (user-error (signal 'error (cdr err))))
+@end group
+@end example
+
+But with the difference that when we (re)signal the new error in
+@code{handler-bind} the dynamic environment from the original error is
+still active, which means for example that if we were to enter the
+debugger at this point, it will show us a complete backtrace including
+the point where we signaled the original error:
+
+@example
+@group
+Debugger entered--Lisp error: (error "Oops")
+  signal(error ("Oops"))
+  (closure (t) (err) (signal 'error (cdr err)))((user-error "Oops"))
+  user-error("Oops")
+  @dots{}
+  eval((handler-bind ((user-error (lambda (err) @dots{}
+@end group
+@end example
+
 @end defmac
 
 @node Error Symbols
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index 45c892ad5a7..c3d980e1717 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -848,15 +848,17 @@ Eval
 @end defopt
 
 @defopt lisp-eval-depth-reserve
-In order to be able to debug infinite recursion errors, Entry to the
-Lisp debugger increases temporarily the value of
+In order to be able to debug infinite recursion errors, when invoking the
+Lisp debugger, Emacs increases temporarily the value of
 @code{max-lisp-eval-depth}, if there is little room left, to make sure
 the debugger itself has room to execute.  The same happens when
-running the handler of a @code{handler-bind}.
+running the handler of a @code{handler-bind}.  @xref{Handling Errors}.
 
 The variable @code{lisp-eval-depth-reserve} bounds the extra depth
 that Emacs can add to @code{max-lisp-eval-depth} for those
 exceptional circumstances.
+
+The default value of this variable is 200.
 @end defopt
 
 
diff --git a/etc/NEWS b/etc/NEWS
index 014c32b4d8e..e446f05190a 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1371,6 +1371,7 @@ It puts a limit to the amount by which Emacs can temporarily increase
 Provides a functionality similar to `condition-case` except it runs the
 handler code without unwinding the stack, such that we can record the
 backtrace and other dynamic state at the point of the error.
+See the Info node "(elisp) Handling Errors".
 
 +++
 ** New 'pop-up-frames' action alist entry for 'display-buffer'.
diff --git a/lisp/subr.el b/lisp/subr.el
index 600b4d27f18..57e2473c2bb 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -7501,13 +7501,13 @@ handler-bind
   "Setup error HANDLERS around execution of BODY.
 HANDLERS is a list of (CONDITIONS HANDLER) where
 CONDITIONS should be a list of condition names (symbols) or
-a single condition name and HANDLER is a form whose evaluation
+a single condition name, and HANDLER is a form whose evaluation
 returns a function.
 When an error is signaled during execution of BODY, if that
 error matches CONDITIONS, then the associated HANDLER
-function is called with the error as argument.
+function is called with the error object as argument.
 HANDLERs can either transfer the control via a non-local exit,
-or return normally.  If they return normally the search for an
+or return normally.  If a handler returns normally, the search for an
 error handler continues from where it left off."
   ;; FIXME: Completion support as in `condition-case'?
   (declare (indent 1) (debug ((&rest (sexp form)) body)))