Merge from trunk.

8 files changed, 87 insertions, 37 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 490280dae29..acc334ea000 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,7 @@
+2011-10-26  Chong Yidong  <cyd@gnu.org>
+
+        * modes.texi (Running Hooks): Document with-wrapper-hook.
+
 2011-10-18  Chong Yidong  <cyd@gnu.org>
 
         * display.texi (Glyphless Chars): New node.
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index eb81ebc4acb..9d652901e53 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -84,8 +84,9 @@ its value is just a single function, not a list of functions.
 @node Running Hooks
 @subsection Running Hooks
 
-  At the appropriate times, Emacs uses the @code{run-hooks} function
-and the other functions below to run particular hooks.
+  In this section, we document the @code{run-hooks} function, which is
+used to run a normal hook.  We also document the functions for running
+various kinds of abnormal hooks.
 
 @defun run-hooks &rest hookvars
 This function takes one or more normal hook variable names as
@@ -108,28 +109,49 @@ be run as well.
 @end defun
 
 @defun run-hook-with-args hook &rest args
-This function is the way to run an abnormal hook and always call all
-of the hook functions.  It calls each of the hook functions one by
-one, passing each of them the arguments @var{args}.
+This function runs an abnormal hook by calling all the hook functions in
+@var{hook}, passing each one the arguments @var{args}.
 @end defun
 
 @defun run-hook-with-args-until-failure hook &rest args
-This function is the way to run an abnormal hook until one of the hook
-functions fails.  It calls each of the hook functions, passing each of
-them the arguments @var{args}, until some hook function returns
-@code{nil}.  It then stops and returns @code{nil}.  If none of the
-hook functions return @code{nil}, it returns a non-@code{nil} value.
+This function runs an abnormal hook by calling each hook function in
+turn, stopping if one of them ``fails'' by returning @code{nil}.  Each
+hook function is passed the arguments @var{args}.  If this function
+stops because one of the hook functions fails, it returns @code{nil};
+otherwise it returns a non-@code{nil} value.
 @end defun
 
 @defun run-hook-with-args-until-success hook &rest args
-This function is the way to run an abnormal hook until a hook function
-succeeds.  It calls each of the hook functions, passing each of them
-the arguments @var{args}, until some hook function returns
-non-@code{nil}.  Then it stops, and returns whatever was returned by
-the last hook function that was called.  If all hook functions return
-@code{nil}, it returns @code{nil} as well.
+This function runs an abnormal hook by calling each hook function,
+stopping if one of them ``succeeds'' by returning a non-@code{nil}
+value.  Each hook function is passed the arguments @var{args}.  If this
+function stops because one of the hook functions returns a
+non-@code{nil} value, it returns that value; otherwise it returns
+@code{nil}.
 @end defun
 
+@defmac with-wrapper-hook hook args &rest body
+This macro runs the abnormal hook @code{hook} as a series of nested
+``wrapper functions'' around the @var{body} forms.  The effect is
+similar to nested @code{around} advices (@pxref{Around-Advice}).
+
+Each hook function must accept an argument list consisting of a function
+@var{fun}, followed by the additional arguments listed in @var{args}.
+The function @var{fun} passed to the very first hook function in
+@var{hook} does the same as @var{body}, if it is called with arguments
+@var{args}.  The @var{fun} passed to each successive hook function is
+constructed from all the preceding hook functions (and @var{body}); if
+this @var{fun} is called with arguments @var{args}, it does what the
+@code{with-wrapper-hook} call would if the preceding hook functions were
+the only ones in @var{hook}.
+
+In the function definition of the hook function, @var{fun} can be called
+any number of times (including not calling it at all).  This function
+definition is then used to construct the @var{fun} passed to the next
+hook function in @var{hook}, if any.  The last or ``outermost''
+@var{fun} is called once to produce the effect.
+@end defmac
+
 @node Setting Hooks
 @subsection Setting Hooks
 
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..60f1db123cf 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,12 @@
+2011-10-26  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * progmodes/octave-mod.el:
+        * progmodes/octave-inf.el: Update maintainer.
+
+2011-10-26  Chong Yidong  <cyd@gnu.org>
+
+        * subr.el (with-wrapper-hook): Rewrite doc.
+
 2011-10-25  Michael Albinus  <michael.albinus@gmx.de>
 
         * net/tramp-sh.el (tramp-sh-handle-file-directory-p): Return t for
diff --git a/lisp/progmodes/octave-inf.el b/lisp/progmodes/octave-inf.el
index e9d890c3f26..421f476016e 100644
--- a/lisp/progmodes/octave-inf.el
+++ b/lisp/progmodes/octave-inf.el
@@ -4,7 +4,7 @@
 
 ;; Author: Kurt Hornik <Kurt.Hornik@wu-wien.ac.at>
 ;; Author: John Eaton <jwe@bevo.che.wisc.edu>
-;; Maintainer: Kurt Hornik <Kurt.Hornik@wu-wien.ac.at>
+;; Maintainer: FSF
 ;; Keywords: languages
 ;; Package: octave-mod
 
@@ -68,6 +68,7 @@ mode, set this to (\"-q\" \"--traditional\")."
     (define-key map "\C-c\C-l" 'inferior-octave-dynamic-list-input-ring)
     (define-key map [menu-bar inout list-history]
       '("List Input History" . inferior-octave-dynamic-list-input-ring))
+    ;; FIXME: free C-h so it can do the describe-prefix-bindings.
     (define-key map "\C-c\C-h" 'info-lookup-symbol)
     map)
   "Keymap used in Inferior Octave mode.")
diff --git a/lisp/progmodes/octave-mod.el b/lisp/progmodes/octave-mod.el
index 5e13b8533e7..28e25a35c70 100644
--- a/lisp/progmodes/octave-mod.el
+++ b/lisp/progmodes/octave-mod.el
@@ -4,7 +4,7 @@
 
 ;; Author: Kurt Hornik <Kurt.Hornik@wu-wien.ac.at>
 ;; Author: John Eaton <jwe@octave.org>
-;; Maintainer: Kurt Hornik <Kurt.Hornik@wu-wien.ac.at>
+;; Maintainer: FSF
 ;; Keywords: languages
 
 ;; This file is part of GNU Emacs.
@@ -223,6 +223,7 @@ parenthetical grouping.")
     (define-key map "\C-c]" 'smie-close-block)
     (define-key map "\C-c/" 'smie-close-block)
     (define-key map "\C-c\C-f" 'octave-insert-defun)
+    ;; FIXME: free C-h so it can do the describe-prefix-bindings.
     (define-key map "\C-c\C-h" 'info-lookup-symbol)
     (define-key map "\C-c\C-il" 'octave-send-line)
     (define-key map "\C-c\C-ib" 'octave-send-block)
@@ -236,6 +237,7 @@ parenthetical grouping.")
     (define-key map "\C-c\C-i\C-f" 'octave-send-defun)
     (define-key map "\C-c\C-i\C-r" 'octave-send-region)
     (define-key map "\C-c\C-i\C-s" 'octave-show-process-buffer)
+    ;; FIXME: free C-h so it can do the describe-prefix-bindings.
     (define-key map "\C-c\C-i\C-h" 'octave-hide-process-buffer)
     (define-key map "\C-c\C-i\C-k" 'octave-kill-process)
     map)
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)
diff --git a/src/intervals.c b/src/intervals.c
index dd511252b28..e8ff5bce5b6 100644
--- a/src/intervals.c
+++ b/src/intervals.c
@@ -1723,8 +1723,6 @@ graft_intervals_into_buffer (INTERVAL source, ptrdiff_t position,
           BUF_INTERVALS (buffer)->position = BEG;
           BUF_INTERVALS (buffer)->up_obj = 1;
 
-          /* Explicitly free the old tree here?  */
-
           return;
         }