diff options
Diffstat (limited to 'doc/lispref/functions.texi')
| -rw-r--r-- | doc/lispref/functions.texi | 88 |
1 files changed, 51 insertions, 37 deletions
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index a92c29d6179..40b8322c73e 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -1204,13 +1204,13 @@ 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 advices. -* Porting old advices:: Adapting code using the old defadvice. +* Advice combinators:: Ways to compose advice. +* Porting old advice:: Adapting code using the old defadvice. @end menu @node Core Advising Primitives @@ -1246,22 +1246,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. - -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. +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 @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 @@ -1299,7 +1302,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 @@ -1328,7 +1331,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 @@ -1362,6 +1365,13 @@ called directly from C, and such calls ignore advice; hence, one ends 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 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. +@end defmac + @defun advice-add symbol where function &optional props Add the advice @var{function} to the named function @var{symbol}. @var{where} and @var{props} have the same meaning as for @code{add-function} @@ -1370,23 +1380,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 @@ -1498,7 +1508,7 @@ 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 @cindex old advices, porting @@ -1506,7 +1516,7 @@ 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 @@ -1543,11 +1553,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) @@ -1573,12 +1583,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 @@ -1752,6 +1762,10 @@ Indent calls to this function or macro according to @var{indent-spec}. This is typically used for macros, though it works for functions too. @xref{Indenting Macros}. +@item (interactive-only @var{value}) +Set the function's @code{interactive-only} property to @var{value}. +@xref{The interactive-only property}. + @item (obsolete @var{current-name} @var{when}) Mark the function or macro as obsolete, similar to a call to @code{make-obsolete} (@pxref{Obsolete Functions}). @var{current-name} |