From b1f6fa2666442e27ae8ac3439fd1891c94fe36bc Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Wed, 26 Oct 2011 08:44:06 +0800 Subject: [PATCH] Document with-wrapper-hook. * doc/emacs/modes.texi (Running Hooks): Document with-wrapper-hook. * lisp/subr.el (with-wrapper-hook): Rewrite doc. --- etc/NEWS | 8 +++++++- lisp/ChangeLog | 4 ++++ lisp/subr.el | 40 ++++++++++++++++++++++++---------------- 3 files changed, 35 insertions(+), 17 deletions(-) diff --git a/etc/NEWS b/etc/NEWS index d6b0bdb484c..58f3fa492e2 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1169,7 +1169,13 @@ must also be supplied. ** pre/post-command-hook are not reset to nil upon error. Instead, the offending function is removed. -** New low-level function run-hook-wrapped. +** New hook types + +*** New function `run-hook-wrapped' for running an abnormal hook by +passing the hook functions as arguments to a "wrapping" function. ++++ +*** New macro `with-wrapper-hook' for running an abnormal hook as a +set of "wrapping" filters, similar to around advice. ** `server-eval-at' is provided to allow evaluating forms on different Emacs server instances. diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 95113007f27..b75d262a9b6 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,7 @@ +2011-10-26 Chong Yidong + + * subr.el (with-wrapper-hook): Rewrite doc. + 2011-10-25 Michael Albinus * net/tramp-sh.el (tramp-sh-handle-file-directory-p): Return t for diff --git a/lisp/subr.el b/lisp/subr.el index c88cef0ba0f..7ac287d2473 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -1364,18 +1364,26 @@ All symbols are bound before the VALUEFORMs are evalled." ,@(mapcar (lambda (binder) `(setq ,@binder)) binders) ,@body)) -(defmacro with-wrapper-hook (var args &rest body) - "Run BODY wrapped with the VAR hook. -VAR is a special hook: its functions are called with a first argument -which is the \"original\" code (the BODY), so the hook function can wrap -the original function, or call it any number of times (including not calling -it at all). This is similar to an `around' advice. -VAR is normally a symbol (a variable) in which case it is treated like -a hook, with a buffer-local and a global part. But it can also be an -arbitrary expression. -ARGS is a list of variables which will be passed as additional arguments -to each function, after the initial argument, and which the first argument -expects to receive when called." +(defmacro with-wrapper-hook (hook args &rest body) + "Run BODY, using wrapper functions from HOOK with additional ARGS. +HOOK is an abnormal hook. Each hook function in HOOK \"wraps\" +around the preceding ones, like a set of nested `around' advices. + +Each hook function should accept an argument list consisting of a +function FUN, followed by the additional arguments in ARGS. + +The FUN passed to the first hook function in HOOK performs BODY, +if it is called with arguments ARGS. The FUN passed to each +successive hook function is defined based on the preceding hook +functions; if called with arguments ARGS, it does what the +`with-wrapper-hook' call would do if the preceding hook functions +were the only ones present in HOOK. + +In the function definition of each hook function, FUN can be +called any number of times (including not calling it at all). +That function definition is then used to construct the FUN passed +to the next hook function, if any. The last (or \"outermost\") +FUN is then called once." (declare (indent 2) (debug (form sexp body))) ;; We need those two gensyms because CL's lexical scoping is not available ;; for function arguments :-( @@ -1404,11 +1412,11 @@ expects to receive when called." ;; Once there are no more functions on the hook, run ;; the original body. (apply (lambda ,args ,@body) ,argssym))))) - (funcall ,runrestofhook ,var + (funcall ,runrestofhook ,hook ;; The global part of the hook, if any. - ,(if (symbolp var) - `(if (local-variable-p ',var) - (default-value ',var))) + ,(if (symbolp hook) + `(if (local-variable-p ',hook) + (default-value ',hook))) (list ,@args))))) (defun add-to-list (list-var element &optional append compare-fn) -- 2.39.2