X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/1911e6e52c846c4a5bf744d850ec7061ff90c412..041470d2d9125f8459708b39da8e29c4c51fb70e:/lispref/advice.texi diff --git a/lispref/advice.texi b/lispref/advice.texi index 24ddb62894..567ea5f2ba 100644 --- a/lispref/advice.texi +++ b/lispref/advice.texi @@ -168,11 +168,15 @@ definition that is generated in order to run the advice (@pxref{Combined Definition}). Therefore, the advice expressions can use the argument variables in this list to access argument values. -This argument list must be compatible with the argument list of the -original function, so that it can handle the ways the function is -actually called. If more than one piece of advice specifies an argument -list, then the first one (the one with the smallest position) found in -the list of all classes of advice is used. +The argument list used in advice need not be the same as the argument +list used in the original function, but must be compatible with it, so +that it can handle the ways the function is actually called. If two +pieces of advice for a function both specify an argument list, they must +specify the same argument list. + +@xref{Argument Access in Advice}, for more information about argument +lists and advice, and a more flexible way for advice to access the +arguments. The remaining elements, @var{flags}, are symbols that specify further information about how to use this piece of advice. Here are the valid @@ -210,7 +214,7 @@ unless subsequently explicitly enabled. @xref{Enabling Advice}. Activate advice for @var{function} when this @code{defadvice} is compiled or macroexpanded. This generates a compiled advised definition according to the current advice state, which will be used during -activation if appropriate. +activation if appropriate. @xref{Preactivation}. This is useful only if this @code{defadvice} is byte-compiled. @end table @@ -236,6 +240,14 @@ expanded when a program is compiled, not when a compiled program is run. All subroutines used by the advice need to be available when the byte compiler expands the macro. +@deffn Command ad-unadvise function +This command deletes the advice from @var{function}. +@end deffn + +@deffn Command ad-unadvise-all +This command deletes all pieces of advice from all functions. +@end deffn + @node Around-Advice @section Around-Advice @@ -268,6 +280,12 @@ the original function definition. This provides a way to override the original definition completely. (It also overrides lower-positioned pieces of around-advice). +If the around-advice uses @code{ad-do-it} more than once, the original +definition is run at each place. In this way, around-advice can execute +the original definition (and lower-positioned pieces of around-advice) +several times. Another way to do that is by using @code{ad-do-it} +inside of a loop. + @node Computed Advice @section Computed Advice @@ -295,7 +313,9 @@ specified @var{class}, then @var{position} specifies where in the list to put the new piece of advice. The value of @var{position} can either be @code{first}, @code{last}, or a number (counting from 0 at the beginning of the list). Numbers outside the range are mapped to the -closest extreme position. +beginning or the end of the range, whichever is closer. The +@var{position} value is ignored when redefining an existing piece of +advice. If @var{function} already has a piece of @var{advice} with the same name, then the position argument is ignored and the old advice is @@ -333,7 +353,7 @@ the command also compiles the combined definition which implements the advice. @deffn Command ad-activate function &optional compile -This command activates the advice for @var{function}. +This command activates all the advice defined for @var{function}. @end deffn To activate advice for a function whose advice is already active is not @@ -347,6 +367,12 @@ This command deactivates the advice for @var{function}. @cindex advice, deactivating @end deffn +@deffn Command ad-update function &optional compile +This command activates the advice for @var{function} +if its advice is already activated. This is useful +if you change the advice. +@end deffn + @deffn Command ad-activate-all &optional compile This command activates the advice for all functions. @end deffn @@ -355,6 +381,12 @@ This command activates the advice for all functions. This command deactivates the advice for all functions. @end deffn +@deffn Command ad-update-all &optional compile +This command activates the advice for all functions +whose advice is already activated. This is useful +if you change the advice of some functions. +@end deffn + @deffn Command ad-activate-regexp regexp &optional compile This command activates all pieces of advice whose names match @var{regexp}. More precisely, it activates all advice for any function @@ -381,8 +413,8 @@ last time it was activated. @deffn Command ad-start-advice Turn on automatic advice activation when a function is defined or -redefined. If you turn on this mode, then advice really does -take effect immediately when defined. +redefined. If you turn on this mode, then advice takes effect +immediately when defined. @end deffn @deffn Command ad-stop-advice @@ -393,6 +425,19 @@ redefined. @defopt ad-default-compilation-action This variable controls whether to compile the combined definition that results from activating advice for a function. + +A value of @code{always} specifies to compile unconditionally +A value of @code{nil} specifies never compile the advice. + +A value of @code{maybe} specifies to compile if the byte-compiler is +already loaded. A value of @code{like-original} specifies to compile +the advice if the the original definition of the advised function is +compiled or a built-in function. + +This variable takes effect only if the @var{compile} argument of +@code{ad-activate} (or any of the above functions) was supplied as +@code{nil}. If that argument is non-@code{nil}, that means +to compile the advice regardless. @end defopt If the advised definition was constructed during ``preactivation''