From: Richard M. Stallman Date: Mon, 20 Apr 1998 17:37:53 +0000 (+0000) Subject: Initial revision X-Git-Tag: emacs-20.3~1395 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=b933f645ac70a31659f364cabf7da730d27eb244;p=emacs.git Initial revision --- diff --git a/lispref/advice.texi b/lispref/advice.texi new file mode 100644 index 00000000000..ffa6606f874 --- /dev/null +++ b/lispref/advice.texi @@ -0,0 +1,544 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1998 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/advising +@node Advising Functions, Debugging, Byte Compilation, Top +@chapter Advising Emacs Lisp Functions +@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 +library to customize functions defined by other parts of Emacs---cleaner +than redefining the function in the usual way. + + 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. + +@menu +* Defining Advice:: +* Computed Advice:: +* Activation of Advice:: +* Enabling Advice:: +* Preactivation:: +* Argument Access in Advice:: +* Combined Definition:: +@end menu + +@node Defining Advice +@section Defining Advice + + To define a piece of advice, use the macro @code{defadvice}. A call +to @code{defadvice} has the following syntax, which is based on the +syntax of @code{defun}/@code{defmacro} but adds more: + +@findex defadvice +@example +(defadvice @var{function} (@var{class} @var{name} + @r{[}@var{position}@r{]} @r{[}@var{arglist}@r{]} + @var{flags}...) + @r{[}@var{documentation-string}@r{]} + @r{[}@var{interactive-form}@r{]} + @var{body-forms}...) +@end example + +@noindent +Here, @var{function} is the name of the function (or macro or special +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}, +@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 +around-advice can override the return value by setting +@code{ad-return-value}. + +Around-advice specifies where the ``original'' function definition +should go by means of the special symbol @code{ad-do-it}. Where this +symbol occurs inside the around-advice body, it is replaced with a +@code{progn} containing the forms of the surrounded code. If the +around-advice does not use @code{ad-do-it}, then the original function +definition is never run. This provides a way to override the original +definition completely. (It also overrides lower-positioned pieces of +around-advice). + +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 +specifies a zero-based position (@code{first} is equivalent to 0). If +no position is specified, the default is @code{first}. The +@var{position} value is ignored when redefining an existing piece of +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 +list, then the first one (the one with the smallest position) found in +the list of all classes of advice will be used. + +@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}). + +@item protect +Protect this piece of advice against non-local exits and errors in +preceding code and advice. + +@item compile +Says that the combined definition which implements advice should be +byte-compiled. This flag is ignored unless @code{activate} is also +specified. + +@item disable +Disable this piece of advice, so that it will not be used +unless subsequently explicitly enabled. + +@item preactivate +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. + +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. + +The optional @var{interactive-form} form can be supplied to change the +interactive behavior of the original function. If more than one piece +of advice has an @var{interactive-form}, then the first one (the one +with the smallest position) found among all the advice takes precedence. + +The possibly empty list of @var{body-forms} specifies the body of the +advice. The body of an advice can access or change the arguments, the +return value, the binding environment, and perform any other kind of +side effect. + +@strong{Warning:} When you advise a macro, keep in mind that macros are +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. + +@node Computed Advice +@section Computed Advice + +The macro @code{defadvice} resembles @code{defun} in that the code for +the advice, and all other information about it, are explicitly stated in +the source code. You can also create advice whose details are computed, +using the function @code{ad-add-advice}. + +@defun ad-add-advice function advice class position +Calling @code{ad-add-advice} adds @var{advice} as a piece of advice to +@var{function} in class @var{class}. The argument @var{advice} has +this form: + +@example +(@var{name} @var{protected} @var{enabled} @var{definition}) +@end example + +Here @var{protected} and @var{enabled} are flags, and @var{definition} +is an expression that says what the advice should do. + +If @var{function} already has one or more pieces of advice in the +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. + +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 +replaced with the new one. +@end defun + +@node Activation of Advice +@section Activation of Advice +@cindex activating advice + +By default, advice does not take effect when you define it---only when +you @dfn{activate} advice for the function that was advised. You can +request the activation of advice for a function when you define the +advice, by specifying the @code{activate} flag in the @code{defadvice}. +But normally you activate the advice for a function by calling the +function @code{ad-activate} or one of the other activation commands +listed below. + +Separating the activation of advice from the act of defining it permits +you to add several pieces of advice to one function efficiently, without +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. + +In all of the commands to activate advice, if @var{compile} is @code{t}, +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}. +@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. + +@deffn Command ad-deactivate function +This command deactivates the advice for @var{function}. +@end deffn + +@deffn Command ad-activate-all &optional compile +This command activates the advice for all functions. +@end deffn + +@deffn Command ad-deactivate-all +This command deactivates the advice for all 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 +which has at least one piece of advice that matches @var{regexp}. +@end deffn + +@deffn Command ad-deactivate-regexp regexp +This command deactivates the advice for all functions whose names match +@var{regexp}. More precisely, it deactivates all advice for any +function which has at least one piece of advice that matches +@var{regexp}. +@end deffn + +@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 + +@deffn Command ad-stop-advice +Turn off automatic advice activation when a function is defined or +redefined. +@end deffn + +@deffn Command ad-start-advice +Turn off automatic advice activation when a function is defined or +redefined. +@end deffn + +@defopt ad-default-compilation-action +This variable controls whether to compile the combined definition +that results from activating advice for a function. +@end defopt + + If the advised definition was constructed during ``preactivation'' (see +below), then that definition must already be compiled, because it was +constructed during byte-compilation of the file that contained the +@code{defadvice} with the @code{preactivate} flag. + +@node Enabling Advice +@section Enabling and Disabling Advice + + Each piece of advice has a flag that says whether it is enabled or +not. By enabling or disabling a piece of advice, you can turn it off +and on without having to undefine and redefine it. For example, here is +how to disable a particular piece of advice named @code{my-advice} for +the function @code{foo}: + +@example +(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 +must activate the advice for @code{foo} again: + +@example +(ad-activate 'foo) +@end example + +@deffn Command ad-disable-advice function class name +This command disables the piece of advice named @var{name} in class +@var{class} on @var{function}. +@end deffn + +@deffn Command ad-enable-advice function class name +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. + +@deffn Command ad-disable-regexp regexp +This command disables all pieces of advice whose names match +@var{regexp}, in all classes, on all functions. +@end deffn + +@deffn Command ad-enable-regexp regexp +This command enables all pieces of advice whose names match +@var{regexp}, in all classes, on all functions. +@end deffn + +@node Preactivation +@section Preactivation + + Constructing a combined definition to execute advice is moderately +expensive. When a library advises many functions, this can make loading +the library slow. In that case, you can use @dfn{preactivation} to +construct suitable combined definitions in advance. + + To use preactivation, specify the @code{preactivate} flag when you +define the advice with @code{defadvice}. This @code{defadvice} call +creates a combined definition which embodies this piece of advice +(whether enabled or not) plus any other currently enabled advice for the +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 +results---but it may fail to do any good, if the enabled advice at the +time of activation doesn't match. + + Here are some symptoms that can indicate that a preactivation did not +work properly, because of a mismatch. + +@itemize @bullet +@item +Activation of the advised +function takes longer than usual. +@item +The byte-compiler gets +loaded while an advised function gets activated. +@item +@code{byte-compile} is included in the value of @code{features} even +though you did not ever explicitly use the byte-compiler. +@end itemize + +Compiled preactivated advice works properly even if the function itself +is not defined until later; however, the function needs to be defined +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{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. + + @strong{Warning:} There is one known case that can make preactivation +fail, in that a preconstructed combined definition is used even though +it fails to match the current state of advice. This can happen when two +packages define different pieces of advice with the same name, in the +same class, for the same function. But you should avoid that anyway. + +@node Argument Access in Advice +@section Argument Access in Advice + + The simplest way to access the arguments of an advised function in the +body of a piece of advice is to use the same names that the function +definition uses. To do this, you need to know the names of the argument +variables of the original function. + + While this simple method is sufficient in many cases, it has a +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. + + 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 +regardless of how these actual argument get distributed onto the +argument variables of a function. This is robust because in Emacs Lisp +the meaning of an argument is strictly determined by its position in the +argument list. + +@defmac ad-get-arg position +This returns the actual argument that was supplied at @var{position}. +@end defmac + +@defmac ad-get-args position +This returns the list of actual arguments supplied starting at +@var{position}. +@end defmac + +@defmac ad-set-arg position value +This sets the value of the actual argument at @var{position} to +@var{value} +@end defmac + +@defmac ad-set-args position value-list +This sets the list of actual arguments starting at @var{position} to +@var{value-list}. +@end defmac + + Now an example. Suppose the function @code{foo} is defined as + +@example +(defun foo (x y &optional z &rest r) ...) +@end example + +@noindent +and is then called with + +@example +(foo 0 1 2 3 4 5 6) +@end example + +@noindent +which means that @var{x} is 0, @var{y} is 1, @var{z} is 2 and @var{r} is +@code{(3 4 5 6)} within the body of @code{foo}. Here is what +@code{ad-get-arg} and @code{ad-get-args} return in this case: + +@example +(ad-get-arg 0) @result{} 0 +(ad-get-arg 1) @result{} 1 +(ad-get-arg 2) @result{} 2 +(ad-get-arg 3) @result{} 3 +(ad-get-args 2) @result{} (2 3 4 5 6) +(ad-get-args 4) @result{} (4 5 6) +@end example + + Setting arguments also makes sense in this example: + +@example +(ad-set-arg 5 "five") +@end example + +@noindent +has the effect of changing the sixth argument to @code{"five"}. If this +happens in advice executed before the body of @code{foo} is run, then +@var{r} will be @code{(3 4 "five" 6)} within that body. + + Here is an example of setting a tail of the argument list: + +@example +(ad-set-args 0 '(5 4 3 2 1 0)) +@end example + +@noindent +If this happens in advice executed before the body of @code{foo} is run, +then within that body, @var{x} will be 5, @var{y} will be 4, @var{z} +will be 3, and @var{r} will be @code{(2 1 0)} inside the body of +@code{foo}. + + 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 + + When the advice facility constructs the combined definition, it needs +to know the argument list of the original function. This is not always +possible for primitive functions. When advice cannot determine the +argument list, it uses @code{(&rest ad-subr-args)}, which always works +but is inefficient because it constructs a list of the argument values. +You can use @code{ad-define-subr-args} to declare the proper argument +names for a primitive function: + +@defun ad-define-subr-args function arglist +This function specifies that @var{arglist} should be used as the +argument list for function @var{function}. +@end defun + +For example, + +@example +(ad-define-subr-args 'fset '(sym newdef)) +@end example + +@noindent +specifies the argument list for the function @code{fset}. + +@node Combined Definition +@section The Combined Definition + + Suppose that a function has @var{n} pieces of before-advice, @var{m} +pieces of around-advice and @var{k} pieces of after-advice. Assuming no +piece of advice is protected, the combined definition produced to +implement the advice for a function looks like this: + +@example +(lambda @var{arglist} + @r{[} @r{[}@var{advised-docstring}@r{]} @r{[}(interactive ...)@r{]} @r{]} + (let (ad-return-value) + @r{before-0-body-form}... + .... + @r{before-@var{n}-1-body-form}... + @r{around-0-body-form}... + @r{around-1-body-form}... + .... + @r{around-@var{m}-1-body-form}... + (setq ad-return-value + @r{apply original definition to @var{arglist}}) + @r{other-around-@var{m}-1-body-form}... + .... + @r{other-around-1-body-form}... + @r{other-around-0-body-form}... + @r{after-0-body-form}... + .... + @r{after-@var{k}-1-body-form}... + ad-return-value)) +@end example + +Macros are redefined as macros, which means adding @code{macro} to +the beginning of the combined definition. + +The interactive form is present if the original function or some piece +of advice specifies one. When an interactive primitive function is +advised, a special method is used: to call the primitive with +@code{call-interactively} so that it will read its own arguments. +In this case, the advice cannot access the arguments. + +The body forms of the various advice in each class are assembled +according to their specified order. The forms of around-advice @var{l} +are included in one of the forms of around-advice @var{l} @minus{} 1. + +The innermost part of the around advice onion is + +@display +apply original definition to @var{arglist} +@end display + +@noindent +whose form depends on the type of the original function. The variable +@code{ad-return-value} is set to whatever this returns. The variable is +visible to all pieces of advice, which can access and modify it before +it is actually returned from the advised function. + +The semantic structure of advised functions that contain protected +pieces of advice is the same. The only difference is that +@code{unwind-protect} forms ensure that the protected advice gets +executed even if some previous piece of advice had an error or a +non-local exit. If any around-advice is protected, then the whole +around-advice onion is protected as a result.