7 |
@chapter Advising Emacs Lisp Functions |
@chapter Advising Emacs Lisp Functions |
8 |
@cindex advising functions |
@cindex advising functions |
9 |
|
|
10 |
The @dfn{advice} feature lets you add to the existing definition of a |
The @dfn{advice} feature lets you add to the existing definition of |
11 |
function, by @dfn{advising the function}. This is a clean method for a |
a function, by @dfn{advising the function}. This is a clean method |
12 |
library to customize functions defined by other parts of Emacs---cleaner |
for a library to customize functions defined within Emacs---cleaner |
13 |
than redefining the whole function. |
than redefining the whole function. |
14 |
|
|
15 |
@cindex piece of advice |
@cindex piece of advice |
16 |
Each function can have multiple @dfn{pieces of advice}, separately |
Each function can have multiple @dfn{pieces of advice}, separately |
17 |
defined. Each defined piece of advice can be @dfn{enabled} or |
defined. Each defined piece of advice can be @dfn{enabled} or |
18 |
disabled explicitly. All the enabled pieces of advice for any given |
@dfn{disabled} explicitly. All the enabled pieces of advice for any given |
19 |
function actually take effect when you @dfn{activate} advice for that |
function actually take effect when you @dfn{activate} advice for that |
20 |
function, or when you define or redefine the function. Note that |
function, or when you define or redefine the function. Note that |
21 |
enabling a piece of advice and activating advice for a function |
enabling a piece of advice and activating advice for a function |
129 |
describing the entity being advised, but this always includes macros and |
describing the entity being advised, but this always includes macros and |
130 |
special forms. |
special forms. |
131 |
|
|
132 |
|
In place of the argument list in an ordinary definition, an advice |
133 |
|
definition calls for several different pieces of information. |
134 |
|
|
135 |
@cindex class of advice |
@cindex class of advice |
136 |
@cindex before-advice |
@cindex before-advice |
137 |
@cindex after-advice |
@cindex after-advice |
157 |
@var{function}. The name allows you to refer to the piece of |
@var{function}. The name allows you to refer to the piece of |
158 |
advice---to redefine it, or to enable or disable it. |
advice---to redefine it, or to enable or disable it. |
159 |
|
|
|
In place of the argument list in an ordinary definition, an advice |
|
|
definition calls for several different pieces of information. |
|
|
|
|
160 |
The optional @var{position} specifies where, in the current list of |
The optional @var{position} specifies where, in the current list of |
161 |
advice of the specified @var{class}, this new advice should be placed. |
advice of the specified @var{class}, this new advice should be placed. |
162 |
It should be either @code{first}, @code{last} or a number that specifies |
It should be either @code{first}, @code{last} or a number that specifies |
332 |
@cindex advice, activating |
@cindex advice, activating |
333 |
|
|
334 |
By default, advice does not take effect when you define it---only when |
By default, advice does not take effect when you define it---only when |
335 |
you @dfn{activate} advice for the function that was advised. However |
you @dfn{activate} advice for the function that was advised. However, |
336 |
the advice will be automatically activated if the function is defined |
the advice will be activated automatically if you define or redefine |
337 |
or redefined later. You can request the activation of advice for a |
the function later. You can request the activation of advice for a |
338 |
function when you define the advice, by specifying the @code{activate} |
function when you define the advice, by specifying the @code{activate} |
339 |
flag in the @code{defadvice}. But normally you activate the advice |
flag in the @code{defadvice}. But normally you activate the advice |
340 |
for a function by calling the function @code{ad-activate} or one of |
for a function by calling the function @code{ad-activate} or one of |
353 |
@ref{Enabling Advice}.) This definition is installed, and optionally |
@ref{Enabling Advice}.) This definition is installed, and optionally |
354 |
byte-compiled as well, depending on conditions described below. |
byte-compiled as well, depending on conditions described below. |
355 |
|
|
356 |
In all of the commands to activate advice, if @var{compile} is @code{t}, |
In all of the commands to activate advice, if @var{compile} is |
357 |
the command also compiles the combined definition which implements the |
@code{t} (or anything but @code{nil} or a negative number), the |
358 |
advice. |
command also compiles the combined definition which implements the |
359 |
|
advice. If it is @code{nil} or a negative number, what happens |
360 |
|
depends on @code{ad-default-compilation-action} as described below. |
361 |
|
|
362 |
@deffn Command ad-activate function &optional compile |
@deffn Command ad-activate function &optional compile |
363 |
This command activates all the advice defined for @var{function}. |
This command activates all the advice defined for @var{function}. |
440 |
compiled or a built-in function. |
compiled or a built-in function. |
441 |
|
|
442 |
This variable takes effect only if the @var{compile} argument of |
This variable takes effect only if the @var{compile} argument of |
443 |
@code{ad-activate} (or any of the above functions) was supplied as |
@code{ad-activate} (or any of the above functions) did not force |
444 |
@code{nil}. If that argument is non-@code{nil}, that means |
compilation. |
|
to compile the advice regardless. |
|
445 |
@end defopt |
@end defopt |
446 |
|
|
447 |
If the advised definition was constructed during ``preactivation'' |
If the advised definition was constructed during ``preactivation'' |