procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

"Advice" is a mass noun. Amend text accordingly.

Browse source 
functions.texi: (Advising Functions, Core Advising Primitives)
(Advising Named Functions, Advice combinators)
(Porting old advice): Replace, e.g., "an advice" with "advice".
This commit is contained in:
Alan Mackenzie 2014-12-15 11:54:42 +00:00
parent 3713931778
commit c3a2c35f1d
2 changed files with 47 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
doc/lispref/ChangeLog
View file

@ -1,3 +1,10 @@
2014-12-15 Alan Mackenzie <acm@muc.de>
"Advice" is a mass noun. Amend text accordingly.
* functions.texi: (Advising Functions, Core Advising Primitives)
(Advising Named Functions, Advice combinators)
(Porting old advice): Replace, e.g., "an advice" with "advice".
2014-12-13 Lars Magne Ingebrigtsen <larsi@gnus.org>
* files.texi (Relative File Names): Mention `directory-name-p'.

77
doc/lispref/functions.texi
View file

@ -1204,17 +1204,17 @@ behavior with:
The arguments @code{:before} and @code{:around} used in the above examples
specify how the two functions are composed, since there are many different
ways to do it. The added function is also called an @emph{advice}.
ways to do it. The added function is also called a piece of @emph{advice}.
@menu
* Core Advising Primitives:: Primitives to manipulate advice.
* Advising Named Functions:: Advising named functions.
* Advice combinators:: Ways to compose advice.
* Porting old advices:: Adapting code using the old defadvice.
* Porting old advice:: Adapting code using the old defadvice.
@end menu
@node Core Advising Primitives
@subsection Primitives to manipulate advices
@subsection Primitives to manipulate advice
@defmac add-function where place function &optional props
This macro is the handy way to add the advice @var{function} to the function
@ -1245,22 +1245,25 @@ identify which function to remove. Typically used when @var{function} is an
anonymous function.
@item depth
This specifies how to order the advices, in case several advices are present.
By default, the depth is 0. A depth of 100 indicates that this advice should
be kept as deep as possible, whereas a depth of -100 indicates that it
should stay as the outermost advice. When two advices specify the same depth,
the most recently added advice will be outermost.
This specifies how to order the advice, should several pieces of
advice be present. By default, the depth is 0. A depth of 100
indicates that this piece of advice should be kept as deep as
possible, whereas a depth of -100 indicates that it should stay as the
outermost piece. When two pieces of advice specify the same depth,
the most recently added one will be outermost.
For a @code{:before} advice, being outermost means that this advice will be run
first, before any other advice, whereas being innermost means that it will run
right before the original function, with no other advice run between itself and
the original function. Similarly, for an @code{:after} advice innermost means
that it will run right after the original function, with no other advice run in
between, whereas outermost means that it will be run very last after all
other advices. An innermost @code{:override} advice will only override the
original function and other advices will apply to it, whereas an outermost
@code{:override} advice will override not only the original function but all
other advices applied to it as well.
For @code{:before} advice, being outermost means that this advice will
be run first, before any other advice, whereas being innermost means
that it will run right before the original function, with no other
advice run between itself and the original function. Similarly, for
@code{:after} advice innermost means that it will run right after the
original function, with no other advice run in between, whereas
outermost means that it will be run right at the end after all other
advice. An innermost @code{:override} piece of advice will only
override the original function and other pieces of advice will apply
to it, whereas an outermost @code{:override} piece of advice will
override not only the original function but all other advice applied
to it as well.
@end table
If @var{function} is not interactive, then the combined function will inherit
@ -1298,7 +1301,7 @@ function, it can also be the @code{name} of the piece of advice.
@end defun
@defun advice-function-mapc f function-def
Call the function @var{f} for every advice that was added to
Call the function @var{f} for every piece of advice that was added to
@var{function-def}. @var{f} is called with two arguments: the advice function
and its properties.
@end defun
@ -1326,7 +1329,7 @@ instead. This separate set of functions to manipulate pieces of advice applied
to named functions, offers the following extra features compared to
@code{add-function}: they know how to deal with macros and autoloaded
functions, they let @code{describe-function} preserve the original docstring as
well as document the added advice, and they let you add and remove advices
well as document the added advice, and they let you add and remove advice
before a function is even defined.
@code{advice-add} can be useful for altering the behavior of existing calls
@ -1361,7 +1364,7 @@ up in a confusing situation where some calls (occurring from Lisp
code) obey the advice and other calls (from C code) do not.
@defmac define-advice symbol (where lambda-list &optional name depth) &rest body
This macro defines an advice and adds it to the function named
This macro defines a piece of advice and adds it to the function named
@var{symbol}. The advice is an anonymous function if @var{name} is
nil or a function named @code{symbol@@name}. See @code{advice-add}
for explanation of other arguments.
@ -1375,23 +1378,23 @@ Add the advice @var{function} to the named function @var{symbol}.
@defun advice-remove symbol function
Remove the advice @var{function} from the named function @var{symbol}.
@var{function} can also be the @code{name} of an advice.
@var{function} can also be the @code{name} of a piece of advice.
@end defun
@defun advice-member-p function symbol
Return non-@code{nil} if the advice @var{function} is already in the named
function @var{symbol}. @var{function} can also be the @code{name} of
an advice.
a piece of advice.
@end defun
@defun advice-mapc function symbol
Call @var{function} for every advice that was added to the named function
@var{symbol}. @var{function} is called with two arguments: the advice function
and its properties.
Call @var{function} for every piece of advice that was added to the
named function @var{symbol}. @var{function} is called with two
arguments: the advice function and its properties.
@end defun
@node Advice combinators
@subsection Ways to compose advices
@subsection Ways to compose advice
Here are the different possible values for the @var{where} argument of
@code{add-function} and @code{advice-add}, specifying how the advice
@ -1503,14 +1506,14 @@ More specifically, the composition of the two functions behaves like:
@end table
@node Porting old advices
@node Porting old advice
@subsection Adapting code using the old defadvice
A lot of code uses the old @code{defadvice} mechanism, which is largely made
obsolete by the new @code{advice-add}, whose implementation and semantics is
significantly simpler.
An old advice such as:
An old piece of advice such as:
@example
(defadvice previous-line (before next-line-at-end
@ -1547,11 +1550,11 @@ whereas the new advice mechanism needs:
Note that @code{ad-activate} had a global effect: it activated all pieces of
advice enabled for that specified function. If you wanted to only activate or
deactivate a particular advice, you needed to @emph{enable} or @emph{disable}
that advice with @code{ad-enable-advice} and @code{ad-disable-advice}.
deactivate a particular piece, you needed to @emph{enable} or @emph{disable}
it with @code{ad-enable-advice} and @code{ad-disable-advice}.
The new mechanism does away with this distinction.
An around advice such as:
Around advice such as:
@example
(defadvice foo (around foo-around)
@ -1577,12 +1580,12 @@ modify the function's arguments (e.g., with @code{ad-set-arg}), and that would
affect the argument values seen by the original function, whereas in the new
@code{:before}, modifying an argument via @code{setq} in the advice has no
effect on the arguments seen by the original function.
When porting a @code{before} advice which relied on this behavior, you'll need
to turn it into a new @code{:around} or @code{:filter-args} advice instead.
When porting @code{before} advice which relied on this behavior, you'll need
to turn it into new @code{:around} or @code{:filter-args} advice instead.
Similarly an old @code{after} advice could modify the returned value by
changing @code{ad-return-value}, whereas a new @code{:after} advice cannot, so
when porting such an old @code{after} advice, you'll need to turn it into a new
Similarly old @code{after} advice could modify the returned value by
changing @code{ad-return-value}, whereas new @code{:after} advice cannot, so
when porting such old @code{after} advice, you'll need to turn it into new
@code{:around} or @code{:filter-return} advice instead.
@node Obsolete Functions