[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r106193: * doc/emacs/modes.texi (Runn
From: |
Chong Yidong |
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r106193: * doc/emacs/modes.texi (Running Hooks): Document with-wrapper-hook. |
Date: |
Wed, 26 Oct 2011 08:47:58 +0800 |
User-agent: |
Bazaar (2.3.1) |
------------------------------------------------------------
revno: 106193
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Wed 2011-10-26 08:47:58 +0800
message:
* doc/emacs/modes.texi (Running Hooks): Document with-wrapper-hook.
modified:
doc/lispref/ChangeLog
doc/lispref/modes.texi
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog 2011-10-18 01:42:28 +0000
+++ b/doc/lispref/ChangeLog 2011-10-26 00:47:58 +0000
@@ -1,3 +1,7 @@
+2011-10-26 Chong Yidong <address@hidden>
+
+ * modes.texi (Running Hooks): Document with-wrapper-hook.
+
2011-10-18 Chong Yidong <address@hidden>
* display.texi (Glyphless Chars): New node.
=== modified file 'doc/lispref/modes.texi'
--- a/doc/lispref/modes.texi 2011-08-30 15:24:07 +0000
+++ b/doc/lispref/modes.texi 2011-10-26 00:47:58 +0000
@@ -84,8 +84,9 @@
@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 @@
@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
address@hidden, 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
address@hidden It then stops and returns @code{nil}. If none of the
-hook functions return @code{nil}, it returns a address@hidden 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 address@hidden 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
address@hidden Then it stops, and returns whatever was returned by
-the last hook function that was called. If all hook functions return
address@hidden, 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 address@hidden
+value. Each hook function is passed the arguments @var{args}. If this
+function stops because one of the hook functions returns a
address@hidden value, it returns that value; otherwise it returns
address@hidden
@end defun
address@hidden 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
address@hidden, followed by the additional arguments listed in @var{args}.
+The function @var{fun} passed to the very first hook function in
address@hidden does the same as @var{body}, if it is called with arguments
address@hidden 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
address@hidden 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''
address@hidden is called once to produce the effect.
address@hidden defmac
+
@node Setting Hooks
@subsection Setting Hooks
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r106193: * doc/emacs/modes.texi (Running Hooks): Document with-wrapper-hook.,
Chong Yidong <=