Function: handler-bind

handler-bind is a macro defined in subr.el.gz.

Signature

(handler-bind HANDLERS &rest BODY)

Documentation

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 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 object as argument. HANDLERs can either transfer the control via a non-local exit, or return normally. If a handler returns normally, the search for an error handler continues from where it left off.

View in manual

Probably introduced at or before Emacs version 30.1.

Source Code

;; Defined in /usr/src/emacs/lisp/subr.el.gz
(defmacro handler-bind (handlers &rest body)
  "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
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 object as argument.
HANDLERs can either transfer the control via a non-local exit,
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)))
  (let ((args '()))
    (dolist (cond+handler handlers)
      (let ((handler (car (cdr cond+handler)))
            (conds (car cond+handler)))
        (push `',(ensure-list conds) args)
        (push handler args)))
    `(handler-bind-1 (lambda () ,@body) ,@(nreverse args))))