Commit | Line | Data |
---|---|---|
b933f645 RS |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
651f374c TTN |
3 | @c Copyright (C) 1998, 1999, 2002, 2003, 2004, |
4 | @c 2005 Free Software Foundation, Inc. | |
b933f645 RS |
5 | @c See the file elisp.texi for copying conditions. |
6 | @setfilename ../info/advising | |
7 | @node Advising Functions, Debugging, Byte Compilation, Top | |
8 | @chapter Advising Emacs Lisp Functions | |
9 | @cindex advising functions | |
10 | ||
8389b33f | 11 | The @dfn{advice} feature lets you add to the existing definition of |
0e15f9b4 | 12 | a function, by @dfn{advising the function}. This is a cleaner method |
8389b33f | 13 | for a library to customize functions defined within Emacs---cleaner |
a9f0a989 | 14 | than redefining the whole function. |
b933f645 | 15 | |
1911e6e5 RS |
16 | @cindex piece of advice |
17 | Each function can have multiple @dfn{pieces of advice}, separately | |
9012a201 | 18 | defined. Each defined piece of advice can be @dfn{enabled} or |
8389b33f | 19 | @dfn{disabled} explicitly. All the enabled pieces of advice for any given |
9012a201 RS |
20 | function actually take effect when you @dfn{activate} advice for that |
21 | function, or when you define or redefine the function. Note that | |
22 | enabling a piece of advice and activating advice for a function | |
23 | are not the same thing. | |
b933f645 | 24 | |
a9f0a989 RS |
25 | @strong{Usage Note:} Advice is useful for altering the behavior of |
26 | existing calls to an existing function. If you want the new behavior | |
0e15f9b4 RS |
27 | for new calls, or for key bindings, you should define a new function |
28 | (or a new command) which uses the existing function. | |
29 | ||
30 | @strong{Usage note:} Advising a function can cause confusion in | |
31 | debugging, since people who debug calls to the original function may | |
32 | not notice that it has been modified with advice. Therefore, if you | |
33 | have the possibility to change the code of that function (or ask | |
34 | someone to do so) to run a hook, please solve the problem that way. | |
35 | Advice should be reserved for the cases where you cannot get the | |
36 | function changed. | |
37 | ||
38 | In particular, this means that a file in Emacs should not put advice | |
39 | on a function in Emacs. There are currently a few exceptions to this | |
40 | convention, but we aim to correct them. | |
a9f0a989 | 41 | |
b933f645 | 42 | @menu |
a9f0a989 RS |
43 | * Simple Advice:: A simple example to explain the basics of advice. |
44 | * Defining Advice:: Detailed description of @code{defadvice}. | |
1911e6e5 | 45 | * Around-Advice:: Wrapping advice around a function's definition. |
a9f0a989 RS |
46 | * Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. |
47 | * Activation of Advice:: Advice doesn't do anything until you activate it. | |
48 | * Enabling Advice:: You can enable or disable each piece of advice. | |
49 | * Preactivation:: Preactivation is a way of speeding up the | |
50 | loading of compiled advice. | |
1911e6e5 | 51 | * Argument Access in Advice:: How advice can access the function's arguments. |
7a010076 | 52 | * Advising Primitives:: Accessing arguments when advising a primitive. |
a9f0a989 | 53 | * Combined Definition:: How advice is implemented. |
b933f645 RS |
54 | @end menu |
55 | ||
a9f0a989 RS |
56 | @node Simple Advice |
57 | @section A Simple Advice Example | |
58 | ||
59 | The command @code{next-line} moves point down vertically one or more | |
60 | lines; it is the standard binding of @kbd{C-n}. When used on the last | |
61 | line of the buffer, this command inserts a newline to create a line to | |
1636ca09 GM |
62 | move to if @code{next-line-add-newlines} is non-@code{nil} (its default |
63 | is @code{nil}.) | |
a9f0a989 RS |
64 | |
65 | Suppose you wanted to add a similar feature to @code{previous-line}, | |
66 | which would insert a new line at the beginning of the buffer for the | |
f91f2dcc RS |
67 | command to move to (when @code{next-line-add-newlines} is |
68 | non-@code{nil}). How could you do this? | |
a9f0a989 RS |
69 | |
70 | You could do it by redefining the whole function, but that is not | |
71 | modular. The advice feature provides a cleaner alternative: you can | |
72 | effectively add your code to the existing function definition, without | |
73 | actually changing or even seeing that definition. Here is how to do | |
74 | this: | |
75 | ||
76 | @example | |
77 | (defadvice previous-line (before next-line-at-end (arg)) | |
78 | "Insert an empty line when moving up from the top line." | |
79 | (if (and next-line-add-newlines (= arg 1) | |
80 | (save-excursion (beginning-of-line) (bobp))) | |
81 | (progn | |
82 | (beginning-of-line) | |
83 | (newline)))) | |
84 | @end example | |
85 | ||
a9f0a989 RS |
86 | This expression defines a @dfn{piece of advice} for the function |
87 | @code{previous-line}. This piece of advice is named | |
88 | @code{next-line-at-end}, and the symbol @code{before} says that it is | |
89 | @dfn{before-advice} which should run before the regular definition of | |
90 | @code{previous-line}. @code{(arg)} specifies how the advice code can | |
91 | refer to the function's arguments. | |
92 | ||
93 | When this piece of advice runs, it creates an additional line, in the | |
94 | situation where that is appropriate, but does not move point to that | |
95 | line. This is the correct way to write the advice, because the normal | |
96 | definition will run afterward and will move back to the newly inserted | |
97 | line. | |
98 | ||
99 | Defining the advice doesn't immediately change the function | |
100 | @code{previous-line}. That happens when you @dfn{activate} the advice, | |
101 | like this: | |
102 | ||
103 | @example | |
104 | (ad-activate 'previous-line) | |
105 | @end example | |
106 | ||
107 | @noindent | |
108 | This is what actually begins to use the advice that has been defined so | |
109 | far for the function @code{previous-line}. Henceforth, whenever that | |
110 | function is run, whether invoked by the user with @kbd{C-p} or | |
111 | @kbd{M-x}, or called from Lisp, it runs the advice first, and its | |
112 | regular definition second. | |
113 | ||
114 | This example illustrates before-advice, which is one @dfn{class} of | |
115 | advice: it runs before the function's base definition. There are two | |
116 | other advice classes: @dfn{after-advice}, which runs after the base | |
117 | definition, and @dfn{around-advice}, which lets you specify an | |
118 | expression to wrap around the invocation of the base definition. | |
119 | ||
b933f645 RS |
120 | @node Defining Advice |
121 | @section Defining Advice | |
1911e6e5 RS |
122 | @cindex defining advice |
123 | @cindex advice, defining | |
b933f645 RS |
124 | |
125 | To define a piece of advice, use the macro @code{defadvice}. A call | |
126 | to @code{defadvice} has the following syntax, which is based on the | |
1911e6e5 | 127 | syntax of @code{defun} and @code{defmacro}, but adds more: |
b933f645 RS |
128 | |
129 | @findex defadvice | |
130 | @example | |
131 | (defadvice @var{function} (@var{class} @var{name} | |
132 | @r{[}@var{position}@r{]} @r{[}@var{arglist}@r{]} | |
133 | @var{flags}...) | |
134 | @r{[}@var{documentation-string}@r{]} | |
135 | @r{[}@var{interactive-form}@r{]} | |
136 | @var{body-forms}...) | |
137 | @end example | |
138 | ||
139 | @noindent | |
140 | Here, @var{function} is the name of the function (or macro or special | |
141 | form) to be advised. From now on, we will write just ``function'' when | |
142 | describing the entity being advised, but this always includes macros and | |
143 | special forms. | |
144 | ||
8389b33f RS |
145 | In place of the argument list in an ordinary definition, an advice |
146 | definition calls for several different pieces of information. | |
147 | ||
a9f0a989 RS |
148 | @cindex class of advice |
149 | @cindex before-advice | |
150 | @cindex after-advice | |
151 | @cindex around-advice | |
152 | @var{class} specifies the @dfn{class} of the advice---one of @code{before}, | |
b933f645 RS |
153 | @code{after}, or @code{around}. Before-advice runs before the function |
154 | itself; after-advice runs after the function itself; around-advice is | |
155 | wrapped around the execution of the function itself. After-advice and | |
156 | around-advice can override the return value by setting | |
157 | @code{ad-return-value}. | |
158 | ||
1911e6e5 RS |
159 | @defvar ad-return-value |
160 | While advice is executing, after the function's original definition has | |
161 | been executed, this variable holds its return value, which will | |
162 | ultimately be returned to the caller after finishing all the advice. | |
163 | After-advice and around-advice can arrange to return some other value | |
164 | by storing it in this variable. | |
165 | @end defvar | |
b933f645 | 166 | |
a9f0a989 RS |
167 | The argument @var{name} is the name of the advice, a non-@code{nil} |
168 | symbol. The advice name uniquely identifies one piece of advice, within all | |
169 | the pieces of advice in a particular class for a particular | |
170 | @var{function}. The name allows you to refer to the piece of | |
171 | advice---to redefine it, or to enable or disable it. | |
172 | ||
b933f645 RS |
173 | The optional @var{position} specifies where, in the current list of |
174 | advice of the specified @var{class}, this new advice should be placed. | |
1911e6e5 RS |
175 | It should be either @code{first}, @code{last} or a number that specifies |
176 | a zero-based position (@code{first} is equivalent to 0). If no position | |
177 | is specified, the default is @code{first}. Position values outside the | |
178 | range of existing positions in this class are mapped to the beginning or | |
179 | the end of the range, whichever is closer. The @var{position} value is | |
180 | ignored when redefining an existing piece of advice. | |
b933f645 RS |
181 | |
182 | The optional @var{arglist} can be used to define the argument list for | |
a9f0a989 RS |
183 | the sake of advice. This becomes the argument list of the combined |
184 | definition that is generated in order to run the advice (@pxref{Combined | |
185 | Definition}). Therefore, the advice expressions can use the argument | |
186 | variables in this list to access argument values. | |
187 | ||
a40d4712 PR |
188 | The argument list used in advice need not be the same as the argument |
189 | list used in the original function, but must be compatible with it, so | |
190 | that it can handle the ways the function is actually called. If two | |
191 | pieces of advice for a function both specify an argument list, they must | |
192 | specify the same argument list. | |
b933f645 | 193 | |
8241495d | 194 | @xref{Argument Access in Advice}, for more information about argument |
a40d4712 PR |
195 | lists and advice, and a more flexible way for advice to access the |
196 | arguments. | |
8241495d | 197 | |
1911e6e5 RS |
198 | The remaining elements, @var{flags}, are symbols that specify further |
199 | information about how to use this piece of advice. Here are the valid | |
200 | symbols and their meanings: | |
b933f645 RS |
201 | |
202 | @table @code | |
203 | @item activate | |
a9f0a989 RS |
204 | Activate the advice for @var{function} now. Changes in a function's |
205 | advice always take effect the next time you activate advice for the | |
206 | function; this flag says to do so, for @var{function}, immediately after | |
207 | defining this piece of advice. | |
208 | ||
209 | @cindex forward advice | |
9012a201 | 210 | This flag has no immediate effect if @var{function} itself is not defined yet (a |
a9f0a989 RS |
211 | situation known as @dfn{forward advice}), because it is impossible to |
212 | activate an undefined function's advice. However, defining | |
213 | @var{function} will automatically activate its advice. | |
b933f645 RS |
214 | |
215 | @item protect | |
216 | Protect this piece of advice against non-local exits and errors in | |
1911e6e5 RS |
217 | preceding code and advice. Protecting advice places it as a cleanup in |
218 | an @code{unwind-protect} form, so that it will execute even if the | |
a9f0a989 | 219 | previous code gets an error or uses @code{throw}. @xref{Cleanups}. |
b933f645 RS |
220 | |
221 | @item compile | |
a9f0a989 RS |
222 | Compile the combined definition that is used to run the advice. This |
223 | flag is ignored unless @code{activate} is also specified. | |
224 | @xref{Combined Definition}. | |
b933f645 RS |
225 | |
226 | @item disable | |
a9f0a989 RS |
227 | Initially disable this piece of advice, so that it will not be used |
228 | unless subsequently explicitly enabled. @xref{Enabling Advice}. | |
b933f645 RS |
229 | |
230 | @item preactivate | |
231 | Activate advice for @var{function} when this @code{defadvice} is | |
232 | compiled or macroexpanded. This generates a compiled advised definition | |
233 | according to the current advice state, which will be used during | |
8241495d | 234 | activation if appropriate. @xref{Preactivation}. |
b933f645 RS |
235 | |
236 | This is useful only if this @code{defadvice} is byte-compiled. | |
237 | @end table | |
238 | ||
239 | The optional @var{documentation-string} serves to document this piece of | |
a9f0a989 RS |
240 | advice. When advice is active for @var{function}, the documentation for |
241 | @var{function} (as returned by @code{documentation}) combines the | |
242 | documentation strings of all the advice for @var{function} with the | |
243 | documentation string of its original function definition. | |
b933f645 RS |
244 | |
245 | The optional @var{interactive-form} form can be supplied to change the | |
246 | interactive behavior of the original function. If more than one piece | |
247 | of advice has an @var{interactive-form}, then the first one (the one | |
248 | with the smallest position) found among all the advice takes precedence. | |
249 | ||
250 | The possibly empty list of @var{body-forms} specifies the body of the | |
251 | advice. The body of an advice can access or change the arguments, the | |
252 | return value, the binding environment, and perform any other kind of | |
253 | side effect. | |
254 | ||
255 | @strong{Warning:} When you advise a macro, keep in mind that macros are | |
256 | expanded when a program is compiled, not when a compiled program is run. | |
257 | All subroutines used by the advice need to be available when the byte | |
258 | compiler expands the macro. | |
259 | ||
41982e72 GM |
260 | @deffn Command ad-unadvise function |
261 | This command deletes the advice from @var{function}. | |
262 | @end deffn | |
263 | ||
264 | @deffn Command ad-unadvise-all | |
265 | This command deletes all pieces of advice from all functions. | |
266 | @end deffn | |
267 | ||
1911e6e5 RS |
268 | @node Around-Advice |
269 | @section Around-Advice | |
270 | ||
271 | Around-advice lets you ``wrap'' a Lisp expression ``around'' the | |
272 | original function definition. You specify where the original function | |
273 | definition should go by means of the special symbol @code{ad-do-it}. | |
274 | Where this symbol occurs inside the around-advice body, it is replaced | |
275 | with a @code{progn} containing the forms of the surrounded code. Here | |
276 | is an example: | |
277 | ||
278 | @example | |
279 | (defadvice foo (around foo-around) | |
280 | "Ignore case in `foo'." | |
281 | (let ((case-fold-search t)) | |
282 | ad-do-it)) | |
283 | @end example | |
284 | ||
285 | @noindent | |
286 | Its effect is to make sure that case is ignored in | |
287 | searches when the original definition of @code{foo} is run. | |
288 | ||
289 | @defvar ad-do-it | |
f91f2dcc RS |
290 | This is not really a variable, rather a place-holder that looks like a |
291 | variable. You use it in around-advice to specify the place to run the | |
292 | function's original definition and other ``earlier'' around-advice. | |
1911e6e5 RS |
293 | @end defvar |
294 | ||
295 | If the around-advice does not use @code{ad-do-it}, then it does not run | |
296 | the original function definition. This provides a way to override the | |
297 | original definition completely. (It also overrides lower-positioned | |
298 | pieces of around-advice). | |
299 | ||
bbf6f18c KH |
300 | If the around-advice uses @code{ad-do-it} more than once, the original |
301 | definition is run at each place. In this way, around-advice can execute | |
302 | the original definition (and lower-positioned pieces of around-advice) | |
303 | several times. Another way to do that is by using @code{ad-do-it} | |
304 | inside of a loop. | |
305 | ||
b933f645 RS |
306 | @node Computed Advice |
307 | @section Computed Advice | |
308 | ||
309 | The macro @code{defadvice} resembles @code{defun} in that the code for | |
310 | the advice, and all other information about it, are explicitly stated in | |
311 | the source code. You can also create advice whose details are computed, | |
312 | using the function @code{ad-add-advice}. | |
313 | ||
314 | @defun ad-add-advice function advice class position | |
315 | Calling @code{ad-add-advice} adds @var{advice} as a piece of advice to | |
316 | @var{function} in class @var{class}. The argument @var{advice} has | |
317 | this form: | |
318 | ||
319 | @example | |
320 | (@var{name} @var{protected} @var{enabled} @var{definition}) | |
321 | @end example | |
322 | ||
323 | Here @var{protected} and @var{enabled} are flags, and @var{definition} | |
a9f0a989 RS |
324 | is the expression that says what the advice should do. If @var{enabled} |
325 | is @code{nil}, this piece of advice is initially disabled | |
326 | (@pxref{Enabling Advice}). | |
b933f645 RS |
327 | |
328 | If @var{function} already has one or more pieces of advice in the | |
329 | specified @var{class}, then @var{position} specifies where in the list | |
330 | to put the new piece of advice. The value of @var{position} can either | |
331 | be @code{first}, @code{last}, or a number (counting from 0 at the | |
332 | beginning of the list). Numbers outside the range are mapped to the | |
8241495d RS |
333 | beginning or the end of the range, whichever is closer. The |
334 | @var{position} value is ignored when redefining an existing piece of | |
335 | advice. | |
b933f645 RS |
336 | |
337 | If @var{function} already has a piece of @var{advice} with the same | |
338 | name, then the position argument is ignored and the old advice is | |
339 | replaced with the new one. | |
340 | @end defun | |
341 | ||
342 | @node Activation of Advice | |
343 | @section Activation of Advice | |
344 | @cindex activating advice | |
1911e6e5 | 345 | @cindex advice, activating |
b933f645 RS |
346 | |
347 | By default, advice does not take effect when you define it---only when | |
8389b33f RS |
348 | you @dfn{activate} advice for the function that was advised. However, |
349 | the advice will be activated automatically if you define or redefine | |
350 | the function later. You can request the activation of advice for a | |
20853e2f RS |
351 | function when you define the advice, by specifying the @code{activate} |
352 | flag in the @code{defadvice}. But normally you activate the advice | |
353 | for a function by calling the function @code{ad-activate} or one of | |
354 | the other activation commands listed below. | |
b933f645 RS |
355 | |
356 | Separating the activation of advice from the act of defining it permits | |
357 | you to add several pieces of advice to one function efficiently, without | |
358 | redefining the function over and over as each advice is added. More | |
359 | importantly, it permits defining advice for a function before that | |
360 | function is actually defined. | |
361 | ||
a9f0a989 RS |
362 | When a function's advice is first activated, the function's original |
363 | definition is saved, and all enabled pieces of advice for that function | |
364 | are combined with the original definition to make a new definition. | |
365 | (Pieces of advice that are currently disabled are not used; see | |
366 | @ref{Enabling Advice}.) This definition is installed, and optionally | |
367 | byte-compiled as well, depending on conditions described below. | |
b933f645 | 368 | |
8389b33f RS |
369 | In all of the commands to activate advice, if @var{compile} is |
370 | @code{t} (or anything but @code{nil} or a negative number), the | |
371 | command also compiles the combined definition which implements the | |
372 | advice. If it is @code{nil} or a negative number, what happens | |
373 | depends on @code{ad-default-compilation-action} as described below. | |
b933f645 RS |
374 | |
375 | @deffn Command ad-activate function &optional compile | |
8241495d | 376 | This command activates all the advice defined for @var{function}. |
b933f645 RS |
377 | @end deffn |
378 | ||
f91f2dcc RS |
379 | Activating advice does nothing if @var{function}'s advice is already |
380 | active. But if there is new advice, added since the previous time you | |
381 | activated advice for @var{function}, it activates the new advice. | |
b933f645 RS |
382 | |
383 | @deffn Command ad-deactivate function | |
384 | This command deactivates the advice for @var{function}. | |
1911e6e5 RS |
385 | @cindex deactivating advice |
386 | @cindex advice, deactivating | |
b933f645 RS |
387 | @end deffn |
388 | ||
41982e72 GM |
389 | @deffn Command ad-update function &optional compile |
390 | This command activates the advice for @var{function} | |
391 | if its advice is already activated. This is useful | |
392 | if you change the advice. | |
393 | @end deffn | |
394 | ||
b933f645 RS |
395 | @deffn Command ad-activate-all &optional compile |
396 | This command activates the advice for all functions. | |
397 | @end deffn | |
398 | ||
399 | @deffn Command ad-deactivate-all | |
400 | This command deactivates the advice for all functions. | |
401 | @end deffn | |
402 | ||
41982e72 GM |
403 | @deffn Command ad-update-all &optional compile |
404 | This command activates the advice for all functions | |
405 | whose advice is already activated. This is useful | |
406 | if you change the advice of some functions. | |
407 | @end deffn | |
408 | ||
b933f645 RS |
409 | @deffn Command ad-activate-regexp regexp &optional compile |
410 | This command activates all pieces of advice whose names match | |
411 | @var{regexp}. More precisely, it activates all advice for any function | |
412 | which has at least one piece of advice that matches @var{regexp}. | |
413 | @end deffn | |
414 | ||
415 | @deffn Command ad-deactivate-regexp regexp | |
1911e6e5 | 416 | This command deactivates all pieces of advice whose names match |
b933f645 RS |
417 | @var{regexp}. More precisely, it deactivates all advice for any |
418 | function which has at least one piece of advice that matches | |
419 | @var{regexp}. | |
420 | @end deffn | |
421 | ||
422 | @deffn Command ad-update-regexp regexp &optional compile | |
423 | This command activates pieces of advice whose names match @var{regexp}, | |
a9f0a989 | 424 | but only those for functions whose advice is already activated. |
1911e6e5 | 425 | @cindex reactivating advice |
b933f645 | 426 | |
a9f0a989 RS |
427 | Reactivating a function's advice is useful for putting into effect all |
428 | the changes that have been made in its advice (including enabling and | |
429 | disabling specific pieces of advice; @pxref{Enabling Advice}) since the | |
430 | last time it was activated. | |
b933f645 RS |
431 | @end deffn |
432 | ||
433 | @deffn Command ad-start-advice | |
a9f0a989 | 434 | Turn on automatic advice activation when a function is defined or |
20853e2f | 435 | redefined. This is the default mode. |
a9f0a989 RS |
436 | @end deffn |
437 | ||
438 | @deffn Command ad-stop-advice | |
b933f645 RS |
439 | Turn off automatic advice activation when a function is defined or |
440 | redefined. | |
441 | @end deffn | |
442 | ||
443 | @defopt ad-default-compilation-action | |
444 | This variable controls whether to compile the combined definition | |
445 | that results from activating advice for a function. | |
41982e72 | 446 | |
080a57ba | 447 | A value of @code{always} specifies to compile unconditionally. |
f91f2dcc | 448 | A value of @code{never} specifies never compile the advice. |
41982e72 GM |
449 | |
450 | A value of @code{maybe} specifies to compile if the byte-compiler is | |
451 | already loaded. A value of @code{like-original} specifies to compile | |
080a57ba | 452 | the advice if the original definition of the advised function is |
41982e72 GM |
453 | compiled or a built-in function. |
454 | ||
455 | This variable takes effect only if the @var{compile} argument of | |
8389b33f RS |
456 | @code{ad-activate} (or any of the above functions) did not force |
457 | compilation. | |
b933f645 RS |
458 | @end defopt |
459 | ||
1911e6e5 RS |
460 | If the advised definition was constructed during ``preactivation'' |
461 | (@pxref{Preactivation}), then that definition must already be compiled, | |
462 | because it was constructed during byte-compilation of the file that | |
463 | contained the @code{defadvice} with the @code{preactivate} flag. | |
b933f645 RS |
464 | |
465 | @node Enabling Advice | |
466 | @section Enabling and Disabling Advice | |
1911e6e5 RS |
467 | @cindex enabling advice |
468 | @cindex advice, enabling and disabling | |
469 | @cindex disabling advice | |
b933f645 RS |
470 | |
471 | Each piece of advice has a flag that says whether it is enabled or | |
1911e6e5 RS |
472 | not. By enabling or disabling a piece of advice, you can turn it on |
473 | and off without having to undefine and redefine it. For example, here is | |
b933f645 RS |
474 | how to disable a particular piece of advice named @code{my-advice} for |
475 | the function @code{foo}: | |
476 | ||
477 | @example | |
478 | (ad-disable-advice 'foo 'before 'my-advice) | |
479 | @end example | |
480 | ||
1911e6e5 | 481 | This function by itself only changes the enable flag for a piece of |
a9f0a989 | 482 | advice. To make the change take effect in the advised definition, you |
b933f645 RS |
483 | must activate the advice for @code{foo} again: |
484 | ||
485 | @example | |
486 | (ad-activate 'foo) | |
487 | @end example | |
488 | ||
489 | @deffn Command ad-disable-advice function class name | |
490 | This command disables the piece of advice named @var{name} in class | |
491 | @var{class} on @var{function}. | |
492 | @end deffn | |
493 | ||
494 | @deffn Command ad-enable-advice function class name | |
495 | This command enables the piece of advice named @var{name} in class | |
496 | @var{class} on @var{function}. | |
497 | @end deffn | |
498 | ||
a9f0a989 RS |
499 | You can also disable many pieces of advice at once, for various |
500 | functions, using a regular expression. As always, the changes take real | |
501 | effect only when you next reactivate advice for the functions in | |
502 | question. | |
b933f645 RS |
503 | |
504 | @deffn Command ad-disable-regexp regexp | |
505 | This command disables all pieces of advice whose names match | |
506 | @var{regexp}, in all classes, on all functions. | |
507 | @end deffn | |
508 | ||
509 | @deffn Command ad-enable-regexp regexp | |
510 | This command enables all pieces of advice whose names match | |
511 | @var{regexp}, in all classes, on all functions. | |
512 | @end deffn | |
513 | ||
514 | @node Preactivation | |
515 | @section Preactivation | |
1911e6e5 RS |
516 | @cindex preactivating advice |
517 | @cindex advice, preactivating | |
b933f645 RS |
518 | |
519 | Constructing a combined definition to execute advice is moderately | |
520 | expensive. When a library advises many functions, this can make loading | |
521 | the library slow. In that case, you can use @dfn{preactivation} to | |
522 | construct suitable combined definitions in advance. | |
523 | ||
524 | To use preactivation, specify the @code{preactivate} flag when you | |
525 | define the advice with @code{defadvice}. This @code{defadvice} call | |
526 | creates a combined definition which embodies this piece of advice | |
527 | (whether enabled or not) plus any other currently enabled advice for the | |
528 | same function, and the function's own definition. If the | |
529 | @code{defadvice} is compiled, that compiles the combined definition | |
530 | also. | |
531 | ||
a9f0a989 RS |
532 | When the function's advice is subsequently activated, if the enabled |
533 | advice for the function matches what was used to make this combined | |
534 | definition, then the existing combined definition is used, thus avoiding | |
535 | the need to construct one. Thus, preactivation never causes wrong | |
b933f645 | 536 | results---but it may fail to do any good, if the enabled advice at the |
a9f0a989 | 537 | time of activation doesn't match what was used for preactivation. |
b933f645 RS |
538 | |
539 | Here are some symptoms that can indicate that a preactivation did not | |
540 | work properly, because of a mismatch. | |
541 | ||
542 | @itemize @bullet | |
543 | @item | |
544 | Activation of the advised | |
545 | function takes longer than usual. | |
546 | @item | |
547 | The byte-compiler gets | |
548 | loaded while an advised function gets activated. | |
549 | @item | |
550 | @code{byte-compile} is included in the value of @code{features} even | |
551 | though you did not ever explicitly use the byte-compiler. | |
552 | @end itemize | |
553 | ||
554 | Compiled preactivated advice works properly even if the function itself | |
555 | is not defined until later; however, the function needs to be defined | |
556 | when you @emph{compile} the preactivated advice. | |
557 | ||
558 | There is no elegant way to find out why preactivated advice is not being | |
559 | used. What you can do is to trace the function | |
560 | @code{ad-cache-id-verification-code} (with the function | |
a9f0a989 RS |
561 | @code{trace-function-background}) before the advised function's advice |
562 | is activated. After activation, check the value returned by | |
b933f645 RS |
563 | @code{ad-cache-id-verification-code} for that function: @code{verified} |
564 | means that the preactivated advice was used, while other values give | |
565 | some information about why they were considered inappropriate. | |
566 | ||
567 | @strong{Warning:} There is one known case that can make preactivation | |
568 | fail, in that a preconstructed combined definition is used even though | |
569 | it fails to match the current state of advice. This can happen when two | |
570 | packages define different pieces of advice with the same name, in the | |
571 | same class, for the same function. But you should avoid that anyway. | |
572 | ||
573 | @node Argument Access in Advice | |
574 | @section Argument Access in Advice | |
575 | ||
576 | The simplest way to access the arguments of an advised function in the | |
577 | body of a piece of advice is to use the same names that the function | |
578 | definition uses. To do this, you need to know the names of the argument | |
579 | variables of the original function. | |
580 | ||
581 | While this simple method is sufficient in many cases, it has a | |
582 | disadvantage: it is not robust, because it hard-codes the argument names | |
583 | into the advice. If the definition of the original function changes, | |
584 | the advice might break. | |
585 | ||
a9f0a989 RS |
586 | Another method is to specify an argument list in the advice itself. |
587 | This avoids the need to know the original function definition's argument | |
588 | names, but it has a limitation: all the advice on any particular | |
589 | function must use the same argument list, because the argument list | |
590 | actually used for all the advice comes from the first piece of advice | |
591 | for that function. | |
592 | ||
b933f645 RS |
593 | A more robust method is to use macros that are translated into the |
594 | proper access forms at activation time, i.e., when constructing the | |
595 | advised definition. Access macros access actual arguments by position | |
1911e6e5 | 596 | regardless of how these actual arguments get distributed onto the |
b933f645 RS |
597 | argument variables of a function. This is robust because in Emacs Lisp |
598 | the meaning of an argument is strictly determined by its position in the | |
599 | argument list. | |
600 | ||
601 | @defmac ad-get-arg position | |
602 | This returns the actual argument that was supplied at @var{position}. | |
603 | @end defmac | |
604 | ||
605 | @defmac ad-get-args position | |
606 | This returns the list of actual arguments supplied starting at | |
607 | @var{position}. | |
608 | @end defmac | |
609 | ||
610 | @defmac ad-set-arg position value | |
611 | This sets the value of the actual argument at @var{position} to | |
612 | @var{value} | |
613 | @end defmac | |
614 | ||
615 | @defmac ad-set-args position value-list | |
616 | This sets the list of actual arguments starting at @var{position} to | |
617 | @var{value-list}. | |
618 | @end defmac | |
619 | ||
620 | Now an example. Suppose the function @code{foo} is defined as | |
621 | ||
622 | @example | |
623 | (defun foo (x y &optional z &rest r) ...) | |
624 | @end example | |
625 | ||
626 | @noindent | |
627 | and is then called with | |
628 | ||
629 | @example | |
630 | (foo 0 1 2 3 4 5 6) | |
631 | @end example | |
632 | ||
633 | @noindent | |
634 | which means that @var{x} is 0, @var{y} is 1, @var{z} is 2 and @var{r} is | |
635 | @code{(3 4 5 6)} within the body of @code{foo}. Here is what | |
636 | @code{ad-get-arg} and @code{ad-get-args} return in this case: | |
637 | ||
638 | @example | |
639 | (ad-get-arg 0) @result{} 0 | |
640 | (ad-get-arg 1) @result{} 1 | |
641 | (ad-get-arg 2) @result{} 2 | |
642 | (ad-get-arg 3) @result{} 3 | |
643 | (ad-get-args 2) @result{} (2 3 4 5 6) | |
644 | (ad-get-args 4) @result{} (4 5 6) | |
645 | @end example | |
646 | ||
647 | Setting arguments also makes sense in this example: | |
648 | ||
649 | @example | |
650 | (ad-set-arg 5 "five") | |
651 | @end example | |
652 | ||
653 | @noindent | |
654 | has the effect of changing the sixth argument to @code{"five"}. If this | |
655 | happens in advice executed before the body of @code{foo} is run, then | |
656 | @var{r} will be @code{(3 4 "five" 6)} within that body. | |
657 | ||
658 | Here is an example of setting a tail of the argument list: | |
659 | ||
660 | @example | |
661 | (ad-set-args 0 '(5 4 3 2 1 0)) | |
662 | @end example | |
663 | ||
664 | @noindent | |
665 | If this happens in advice executed before the body of @code{foo} is run, | |
666 | then within that body, @var{x} will be 5, @var{y} will be 4, @var{z} | |
667 | will be 3, and @var{r} will be @code{(2 1 0)} inside the body of | |
668 | @code{foo}. | |
669 | ||
670 | These argument constructs are not really implemented as Lisp macros. | |
671 | Instead they are implemented specially by the advice mechanism. | |
672 | ||
7a010076 RS |
673 | @node Advising Primitives |
674 | @section Advising Primitives | |
675 | ||
676 | Advising a primitive function (also called a ``subr'') is risky. | |
677 | Some primitive functions are used by the advice mechanism; advising | |
678 | them could cause an infinite recursion. Also, many primitive | |
679 | functions are called directly from C code. Calls to the primitive | |
680 | from Lisp code will take note of the advice, but calls from C code | |
681 | will ignore the advice. | |
682 | ||
683 | When the advice facility constructs the combined definition, it needs | |
684 | to know the argument list of the original function. This is not | |
685 | always possible for primitive functions. When advice cannot determine | |
686 | the argument list, it uses @code{(&rest ad-subr-args)}, which always | |
687 | works but is inefficient because it constructs a list of the argument | |
688 | values. You can use @code{ad-define-subr-args} to declare the proper | |
689 | argument names for a primitive function: | |
b933f645 RS |
690 | |
691 | @defun ad-define-subr-args function arglist | |
692 | This function specifies that @var{arglist} should be used as the | |
693 | argument list for function @var{function}. | |
694 | @end defun | |
695 | ||
696 | For example, | |
697 | ||
698 | @example | |
699 | (ad-define-subr-args 'fset '(sym newdef)) | |
700 | @end example | |
701 | ||
702 | @noindent | |
703 | specifies the argument list for the function @code{fset}. | |
704 | ||
705 | @node Combined Definition | |
706 | @section The Combined Definition | |
707 | ||
e5446586 RS |
708 | Suppose that a function has @var{n} pieces of before-advice |
709 | (numbered from 0 through @var{n}@minus{}1), @var{m} pieces of | |
710 | around-advice and @var{k} pieces of after-advice. Assuming no piece | |
711 | of advice is protected, the combined definition produced to implement | |
712 | the advice for a function looks like this: | |
b933f645 RS |
713 | |
714 | @example | |
715 | (lambda @var{arglist} | |
716 | @r{[} @r{[}@var{advised-docstring}@r{]} @r{[}(interactive ...)@r{]} @r{]} | |
717 | (let (ad-return-value) | |
718 | @r{before-0-body-form}... | |
719 | .... | |
e5446586 | 720 | @r{before-@var{n}@minus{}1-body-form}... |
b933f645 RS |
721 | @r{around-0-body-form}... |
722 | @r{around-1-body-form}... | |
723 | .... | |
e5446586 | 724 | @r{around-@var{m}@minus{}1-body-form}... |
b933f645 RS |
725 | (setq ad-return-value |
726 | @r{apply original definition to @var{arglist}}) | |
e5446586 | 727 | @r{end-of-around-@var{m}@minus{}1-body-form}... |
b933f645 | 728 | .... |
e5446586 RS |
729 | @r{end-of-around-1-body-form}... |
730 | @r{end-of-around-0-body-form}... | |
b933f645 RS |
731 | @r{after-0-body-form}... |
732 | .... | |
e5446586 | 733 | @r{after-@var{k}@minus{}1-body-form}... |
b933f645 RS |
734 | ad-return-value)) |
735 | @end example | |
736 | ||
737 | Macros are redefined as macros, which means adding @code{macro} to | |
738 | the beginning of the combined definition. | |
739 | ||
740 | The interactive form is present if the original function or some piece | |
741 | of advice specifies one. When an interactive primitive function is | |
59a53efd | 742 | advised, advice uses a special method: it calls the primitive with |
b933f645 RS |
743 | @code{call-interactively} so that it will read its own arguments. |
744 | In this case, the advice cannot access the arguments. | |
745 | ||
746 | The body forms of the various advice in each class are assembled | |
747 | according to their specified order. The forms of around-advice @var{l} | |
748 | are included in one of the forms of around-advice @var{l} @minus{} 1. | |
749 | ||
177c0ea7 | 750 | The innermost part of the around advice onion is |
b933f645 RS |
751 | |
752 | @display | |
753 | apply original definition to @var{arglist} | |
754 | @end display | |
755 | ||
756 | @noindent | |
757 | whose form depends on the type of the original function. The variable | |
758 | @code{ad-return-value} is set to whatever this returns. The variable is | |
759 | visible to all pieces of advice, which can access and modify it before | |
760 | it is actually returned from the advised function. | |
761 | ||
762 | The semantic structure of advised functions that contain protected | |
763 | pieces of advice is the same. The only difference is that | |
764 | @code{unwind-protect} forms ensure that the protected advice gets | |
765 | executed even if some previous piece of advice had an error or a | |
766 | non-local exit. If any around-advice is protected, then the whole | |
767 | around-advice onion is protected as a result. | |
ab5796a9 MB |
768 | |
769 | @ignore | |
770 | arch-tag: 80c135c2-f1c3-4f8d-aa85-f8d8770d307f | |
771 | @end ignore |