@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 is a clean method for a
-library to customize functions defined by other parts of Emacs---cleaner
+ The @dfn{advice} feature lets you add to the existing definition of
+a function, by @dfn{advising the function}. This is a clean method
+for a library to customize functions defined within Emacs---cleaner
than redefining the whole function.
@cindex piece of advice
Each function can have multiple @dfn{pieces of advice}, separately
defined. Each defined piece of advice can be @dfn{enabled} or
-disabled explicitly. All the enabled pieces of advice for any given
+@dfn{disabled} explicitly. All the enabled pieces of advice for any given
function actually take effect when you @dfn{activate} advice for that
function, or when you define or redefine the function. Note that
enabling a piece of advice and activating advice for a function
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?
+command to move to (when @code{next-line-add-newlines} is
+non-@code{nil}). 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
describing the entity being advised, but this always includes macros and
special forms.
+ In place of the argument list in an ordinary definition, an advice
+definition calls for several different pieces of information.
+
@cindex class of advice
@cindex before-advice
@cindex after-advice
@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 specifies
searches when the original definition of @code{foo} is run.
@defvar ad-do-it
-This is not really a variable, but it is somewhat used like one
-in around-advice. It specifies the place to run the function's
-original definition and other ``earlier'' around-advice.
+This is not really a variable, rather a place-holder that looks like a
+variable. You use it in around-advice to specify the place to run the
+function's original definition and other ``earlier'' around-advice.
@end defvar
If the around-advice does not use @code{ad-do-it}, then it does not run
@cindex advice, activating
By default, advice does not take effect when you define it---only when
-you @dfn{activate} advice for the function that was advised. However
-the advice will be automatically activated if the function is defined
-or redefined later. You can request the activation of advice for a
+you @dfn{activate} advice for the function that was advised. However,
+the advice will be activated automatically if you define or redefine
+the function later. 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
@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
-advice.
+In all of the commands to activate advice, if @var{compile} is
+@code{t} (or anything but @code{nil} or a negative number), the
+command also compiles the combined definition which implements the
+advice. If it is @code{nil} or a negative number, what happens
+depends on @code{ad-default-compilation-action} as described below.
@deffn Command ad-activate function &optional compile
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
-a no-op. It is a useful operation which puts into effect any changes in
-that function's advice since the previous activation of advice for that
-function.
+ Activating advice does nothing if @var{function}'s advice is already
+active. But if there is new advice, added since the previous time you
+activated advice for @var{function}, it activates the new advice.
@deffn Command ad-deactivate function
This command deactivates the advice for @var{function}.
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{never} 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
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.
+@code{ad-activate} (or any of the above functions) did not force
+compilation.
@end defopt
If the advised definition was constructed during ``preactivation''
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.
+
+@ignore
+ arch-tag: 80c135c2-f1c3-4f8d-aa85-f8d8770d307f
+@end ignore
HCoop / bpt / emacs.git / blobdiff