diff options
Diffstat (limited to 'lispref/advice.texi')
| -rw-r--r-- | lispref/advice.texi | 240 |
1 files changed, 174 insertions, 66 deletions
diff --git a/lispref/advice.texi b/lispref/advice.texi index ffa6606f874..3d61ae41c38 100644 --- a/lispref/advice.texi +++ b/lispref/advice.texi @@ -8,25 +8,96 @@ @cindex advising functions The @dfn{advice} feature lets you add to the existing definition of a -function, by @dfn{advising the function}. This a clean method for a +function, by @dfn{advising the function}. This is a clean method for a library to customize functions defined by other parts of Emacs---cleaner -than redefining the function in the usual way. +than redefining the whole function. Each piece of advice can be enabled or disabled explicitly. The enabled pieces of advice for any given function actually take effect when you activate advice for that function, or when that function is subsequently defined or redefined. + @strong{Usage Note:} Advice is useful for altering the behavior of +existing calls to an existing function. If you want the new behavior +for new calls, or for key bindings, it is cleaner to define a new +function (or a new command) which uses the existing function. + @menu -* Defining Advice:: -* Computed Advice:: -* Activation of Advice:: -* Enabling Advice:: -* Preactivation:: -* Argument Access in Advice:: -* Combined Definition:: +* Simple Advice:: A simple example to explain the basics of advice. +* Defining Advice:: Detailed description of @code{defadvice}. +* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. +* Activation of Advice:: Advice doesn't do anything until you activate it. +* Enabling Advice:: You can enable or disable each piece of advice. +* Preactivation:: Preactivation is a way of speeding up the + loading of compiled advice. +* Argument Access:: How advice can access the function's arguments. +* Subr Arguments:: Accessing arguments when advising a primitive. +* Combined Definition:: How advice is implemented. @end menu +@node Simple Advice +@section A Simple Advice Example + + The command @code{next-line} moves point down vertically one or more +lines; it is the standard binding of @kbd{C-n}. When used on the last +line of the buffer, this command inserts a newline to create a line to +move to (if @code{next-line-add-newlines} is non-@code{nil}). + + Suppose you wanted to add a similar feature to @code{previous-line}, +which would insert a new line at the beginning of the buffer for the +command to move to. How could you do this? + + You could do it by redefining the whole function, but that is not +modular. The advice feature provides a cleaner alternative: you can +effectively add your code to the existing function definition, without +actually changing or even seeing that definition. Here is how to do +this: + +@example +(defadvice previous-line (before next-line-at-end (arg)) + "Insert an empty line when moving up from the top line." + (if (and next-line-add-newlines (= arg 1) + (save-excursion (beginning-of-line) (bobp))) + (progn + (beginning-of-line) + (newline)))) +@end example + +@cindex piece of advice + This expression defines a @dfn{piece of advice} for the function +@code{previous-line}. This piece of advice is named +@code{next-line-at-end}, and the symbol @code{before} says that it is +@dfn{before-advice} which should run before the regular definition of +@code{previous-line}. @code{(arg)} specifies how the advice code can +refer to the function's arguments. + + When this piece of advice runs, it creates an additional line, in the +situation where that is appropriate, but does not move point to that +line. This is the correct way to write the advice, because the normal +definition will run afterward and will move back to the newly inserted +line. + + Defining the advice doesn't immediately change the function +@code{previous-line}. That happens when you @dfn{activate} the advice, +like this: + +@example +(ad-activate 'previous-line) +@end example + +@noindent +This is what actually begins to use the advice that has been defined so +far for the function @code{previous-line}. Henceforth, whenever that +function is run, whether invoked by the user with @kbd{C-p} or +@kbd{M-x}, or called from Lisp, it runs the advice first, and its +regular definition second. + + This example illustrates before-advice, which is one @dfn{class} of +advice: it runs before the function's base definition. There are two +other advice classes: @dfn{after-advice}, which runs after the base +definition, and @dfn{around-advice}, which lets you specify an +expression to wrap around the invocation of the base definition. + @node Defining Advice @section Defining Advice @@ -50,16 +121,11 @@ form) to be advised. From now on, we will write just ``function'' when describing the entity being advised, but this always includes macros and special forms. -The argument @var{name} is the name of the advice, a non-@code{nil} -symbol. The advice name uniquely identifies one piece of advice, within all -the pieces of advice in a particular class for a particular -@var{function}. The name allows you to refer to the piece of -advice---to redefine it, or to enable or disable it. - -Where an ordinary definition has an argument list, an advice definition -needs several kinds of information. - -@var{class} specifies the class of the advice---one of @code{before}, +@cindex class of advice +@cindex before-advice +@cindex after-advice +@cindex around-advice +@var{class} specifies the @dfn{class} of the advice---one of @code{before}, @code{after}, or @code{around}. Before-advice runs before the function itself; after-advice runs after the function itself; around-advice is wrapped around the execution of the function itself. After-advice and @@ -75,6 +141,15 @@ definition is never run. This provides a way to override the original definition completely. (It also overrides lower-positioned pieces of around-advice). +The argument @var{name} is the name of the advice, a non-@code{nil} +symbol. The advice name uniquely identifies one piece of advice, within all +the pieces of advice in a particular class for a particular +@var{function}. The name allows you to refer to the piece of +advice---to redefine it, or to enable or disable it. + +In place of the argument list in an ordinary definition, an advice +definition calls for several different pieces of information. + The optional @var{position} specifies where, in the current list of advice of the specified @var{class}, this new advice should be placed. It should be either @code{first}, @code{last} or a number that @@ -84,35 +159,49 @@ no position is specified, the default is @code{first}. The advice. The optional @var{arglist} can be used to define the argument list for -the sake of advice. This argument list should of course be compatible -with the argument list of the original function, otherwise functions -that call the advised function with the original argument list in mind -will break. If more than one piece of advice specifies an argument +the sake of advice. This becomes the argument list of the combined +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 will be used. +the list of all classes of advice is used. Numbers outside the range +are mapped to the beginning or the end, whichever is closer. -@var{flags} is a list of symbols that specify further information about -how to use this piece of advice. Here are the valid symbols and their -meanings: +The remaining elements, @var{flags}, is a list of symbols that specify +further information about how to use this piece of advice. Here are the +valid symbols and their meanings: @table @code @item activate -Activate all the advice for @var{function} after making this definition. -This is ignored when @var{function} itself is not defined yet (which is -known as @dfn{forward advice}). +Activate the advice for @var{function} now. Changes in a function's +advice always take effect the next time you activate advice for the +function; this flag says to do so, for @var{function}, immediately after +defining this piece of advice. + +@cindex forward advice +This flag has no effect if @var{function} itself is not defined yet (a +situation known as @dfn{forward advice}), because it is impossible to +activate an undefined function's advice. However, defining +@var{function} will automatically activate its advice. @item protect Protect this piece of advice against non-local exits and errors in -preceding code and advice. +preceding code and advice. Protecting advice makes it a cleanup in an +@code{unwind-protect} form, so that it will execute even if the +previous code gets an error or uses @code{throw}. @xref{Cleanups}. @item compile -Says that the combined definition which implements advice should be -byte-compiled. This flag is ignored unless @code{activate} is also -specified. +Compile the combined definition that is used to run the advice. This +flag is ignored unless @code{activate} is also specified. +@xref{Combined Definition}. @item disable -Disable this piece of advice, so that it will not be used -unless subsequently explicitly enabled. +Initially disable this piece of advice, so that it will not be used +unless subsequently explicitly enabled. @xref{Enabling Advice}. @item preactivate Activate advice for @var{function} when this @code{defadvice} is @@ -124,10 +213,10 @@ This is useful only if this @code{defadvice} is byte-compiled. @end table The optional @var{documentation-string} serves to document this piece of -advice. If the @code{documentation} function gets the documentation -for @var{function} when its advice is active, the result will combine -the documentation strings of all the advice with that of the original -function. +advice. When advice is active for @var{function}, the documentation for +@var{function} (as returned by @code{documentation}) combines the +documentation strings of all the advice for @var{function} with the +documentation string of its original function definition. The optional @var{interactive-form} form can be supplied to change the interactive behavior of the original function. If more than one piece @@ -162,7 +251,9 @@ this form: @end example Here @var{protected} and @var{enabled} are flags, and @var{definition} -is an expression that says what the advice should do. +is the expression that says what the advice should do. If @var{enabled} +is @code{nil}, this piece of advice is initially disabled +(@pxref{Enabling Advice}). If @var{function} already has one or more pieces of advice in the specified @var{class}, then @var{position} specifies where in the list @@ -194,11 +285,12 @@ redefining the function over and over as each advice is added. More importantly, it permits defining advice for a function before that function is actually defined. -When a function is first activated, its original definition is saved, -and all enabled pieces of advice for that function are combined with the -original definition to make a new definition. This definition is -installed, and optionally byte-compiled as well, depending on conditions -described below. +When a function's advice is first activated, the function's original +definition is saved, and all enabled pieces of advice for that function +are combined with the original definition to make a new definition. +(Pieces of advice that are currently disabled are not used; see +@ref{Enabling Advice}.) This definition is installed, and optionally +byte-compiled as well, depending on conditions described below. In all of the commands to activate advice, if @var{compile} is @code{t}, the command also compiles the combined definition which implements the @@ -208,9 +300,9 @@ advice. This command activates the advice for @var{function}. @end deffn -To activate a function whose advice is already active is not a no-op. -It is a useful operation which puts into effect any changes in advice -since the previous activation of the same function. +To activate advice for a function whose advice is already active is not +a no-op. It is a useful operation which puts into effect any changes in +advice since the previous activation of that function's advice. @deffn Command ad-deactivate function This command deactivates the advice for @var{function}. @@ -239,15 +331,21 @@ function which has at least one piece of advice that matches @deffn Command ad-update-regexp regexp &optional compile This command activates pieces of advice whose names match @var{regexp}, -but only those that are already activated. -@end deffn +but only those for functions whose advice is already activated. -@deffn Command ad-stop-advice -Turn off automatic advice activation when a function is defined or -redefined. +Reactivating a function's advice is useful for putting into effect all +the changes that have been made in its advice (including enabling and +disabling specific pieces of advice; @pxref{Enabling Advice}) since the +last time it was activated. @end deffn @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. +@end deffn + +@deffn Command ad-stop-advice Turn off automatic advice activation when a function is defined or redefined. @end deffn @@ -275,8 +373,8 @@ the function @code{foo}: (ad-disable-advice 'foo 'before 'my-advice) @end example - This call by itself only changes the enable flag for this piece of -advice. To make this change take effect in the advised definition, you +This function by itself only changes the enable flag for a piece of +advice. To make the change take effect in the advised definition, you must activate the advice for @code{foo} again: @example @@ -293,8 +391,10 @@ This command enables the piece of advice named @var{name} in class @var{class} on @var{function}. @end deffn - You can also disable many pieces of advice at once using a regular -expression. + You can also disable many pieces of advice at once, for various +functions, using a regular expression. As always, the changes take real +effect only when you next reactivate advice for the functions in +question. @deffn Command ad-disable-regexp regexp This command disables all pieces of advice whose names match @@ -322,12 +422,12 @@ same function, and the function's own definition. If the @code{defadvice} is compiled, that compiles the combined definition also. - When the function is subsequently activated, if the enabled advice for -the function matches what was used to make this combined -definition. then the existing combined definition is used, and there is -no need to construct one. Thus, preactivation never causes wrong + When the function's advice is subsequently activated, if the enabled +advice for the function matches what was used to make this combined +definition, then the existing combined definition is used, thus avoiding +the need to construct one. Thus, preactivation never causes wrong results---but it may fail to do any good, if the enabled advice at the -time of activation doesn't match. +time of activation doesn't match what was used for preactivation. Here are some symptoms that can indicate that a preactivation did not work properly, because of a mismatch. @@ -351,8 +451,8 @@ when you @emph{compile} the preactivated advice. There is no elegant way to find out why preactivated advice is not being used. What you can do is to trace the function @code{ad-cache-id-verification-code} (with the function -@code{trace-function-background}) before the advised function is -activated. After activation, check the value returned by +@code{trace-function-background}) before the advised function's advice +is activated. After activation, check the value returned by @code{ad-cache-id-verification-code} for that function: @code{verified} means that the preactivated advice was used, while other values give some information about why they were considered inappropriate. @@ -376,6 +476,13 @@ disadvantage: it is not robust, because it hard-codes the argument names into the advice. If the definition of the original function changes, the advice might break. + Another method is to specify an argument list in the advice itself. +This avoids the need to know the original function definition's argument +names, but it has a limitation: all the advice on any particular +function must use the same argument list, because the argument list +actually used for all the advice comes from the first piece of advice +for that function. + A more robust method is to use macros that are translated into the proper access forms at activation time, i.e., when constructing the advised definition. Access macros access actual arguments by position @@ -456,7 +563,8 @@ will be 3, and @var{r} will be @code{(2 1 0)} inside the body of These argument constructs are not really implemented as Lisp macros. Instead they are implemented specially by the advice mechanism. -@subsection Definition of Subr Argument Lists +@node Subr Arguments +@section Definition of Subr Argument Lists When the advice facility constructs the combined definition, it needs to know the argument list of the original function. This is not always |