[Emacs-diffs] /srv/bzr/emacs/trunk r106192: Document with-wrapper-hook.

[Chong Yidong]

------------------------------------------------------------
revno: 106192
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Wed 2011-10-26 08:44:06 +0800
message:
  Document with-wrapper-hook.
  
  * doc/emacs/modes.texi (Running Hooks): Document with-wrapper-hook.
  
  * lisp/subr.el (with-wrapper-hook): Rewrite doc.
modified:
  etc/NEWS
  lisp/ChangeLog
  lisp/subr.el

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2011-10-24 02:01:54 +0000
+++ b/etc/NEWS  2011-10-26 00:44:06 +0000
@@ -1169,7 +1169,13 @@
 ** 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.

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2011-10-25 12:50:03 +0000
+++ b/lisp/ChangeLog    2011-10-26 00:44:06 +0000
@@ -1,3 +1,7 @@
+2011-10-26  Chong Yidong  <address@hidden>
+
+       * subr.el (with-wrapper-hook): Rewrite doc.
+
 2011-10-25  Michael Albinus  <address@hidden>
 
        * net/tramp-sh.el (tramp-sh-handle-file-directory-p): Return t for

=== modified file 'lisp/subr.el'
--- a/lisp/subr.el      2011-10-24 02:03:24 +0000
+++ b/lisp/subr.el      2011-10-26 00:44:06 +0000
@@ -1364,18 +1364,26 @@
      ,@(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 @@
                    ;; 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)