Mercurial > emacs
comparison lispref/advice.texi @ 21681:11eafe90b842
Initial revision
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Mon, 20 Apr 1998 17:37:53 +0000 |
parents | |
children | d4ac295a98b3 |
comparison
equal
deleted
inserted
replaced
21680:c744d468bfb6 | 21681:11eafe90b842 |
---|---|
1 @c -*-texinfo-*- | |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1998 Free Software Foundation, Inc. | |
4 @c See the file elisp.texi for copying conditions. | |
5 @setfilename ../info/advising | |
6 @node Advising Functions, Debugging, Byte Compilation, Top | |
7 @chapter Advising Emacs Lisp Functions | |
8 @cindex advising functions | |
9 | |
10 The @dfn{advice} feature lets you add to the existing definition of a | |
11 function, by @dfn{advising the function}. This a clean method for a | |
12 library to customize functions defined by other parts of Emacs---cleaner | |
13 than redefining the function in the usual way. | |
14 | |
15 Each piece of advice can be enabled or disabled explicitly. The | |
16 enabled pieces of advice for any given function actually take effect | |
17 when you activate advice for that function, or when that function is | |
18 subsequently defined or redefined. | |
19 | |
20 @menu | |
21 * Defining Advice:: | |
22 * Computed Advice:: | |
23 * Activation of Advice:: | |
24 * Enabling Advice:: | |
25 * Preactivation:: | |
26 * Argument Access in Advice:: | |
27 * Combined Definition:: | |
28 @end menu | |
29 | |
30 @node Defining Advice | |
31 @section Defining Advice | |
32 | |
33 To define a piece of advice, use the macro @code{defadvice}. A call | |
34 to @code{defadvice} has the following syntax, which is based on the | |
35 syntax of @code{defun}/@code{defmacro} but adds more: | |
36 | |
37 @findex defadvice | |
38 @example | |
39 (defadvice @var{function} (@var{class} @var{name} | |
40 @r{[}@var{position}@r{]} @r{[}@var{arglist}@r{]} | |
41 @var{flags}...) | |
42 @r{[}@var{documentation-string}@r{]} | |
43 @r{[}@var{interactive-form}@r{]} | |
44 @var{body-forms}...) | |
45 @end example | |
46 | |
47 @noindent | |
48 Here, @var{function} is the name of the function (or macro or special | |
49 form) to be advised. From now on, we will write just ``function'' when | |
50 describing the entity being advised, but this always includes macros and | |
51 special forms. | |
52 | |
53 The argument @var{name} is the name of the advice, a non-@code{nil} | |
54 symbol. The advice name uniquely identifies one piece of advice, within all | |
55 the pieces of advice in a particular class for a particular | |
56 @var{function}. The name allows you to refer to the piece of | |
57 advice---to redefine it, or to enable or disable it. | |
58 | |
59 Where an ordinary definition has an argument list, an advice definition | |
60 needs several kinds of information. | |
61 | |
62 @var{class} specifies the class of the advice---one of @code{before}, | |
63 @code{after}, or @code{around}. Before-advice runs before the function | |
64 itself; after-advice runs after the function itself; around-advice is | |
65 wrapped around the execution of the function itself. After-advice and | |
66 around-advice can override the return value by setting | |
67 @code{ad-return-value}. | |
68 | |
69 Around-advice specifies where the ``original'' function definition | |
70 should go by means of the special symbol @code{ad-do-it}. Where this | |
71 symbol occurs inside the around-advice body, it is replaced with a | |
72 @code{progn} containing the forms of the surrounded code. If the | |
73 around-advice does not use @code{ad-do-it}, then the original function | |
74 definition is never run. This provides a way to override the original | |
75 definition completely. (It also overrides lower-positioned pieces of | |
76 around-advice). | |
77 | |
78 The optional @var{position} specifies where, in the current list of | |
79 advice of the specified @var{class}, this new advice should be placed. | |
80 It should be either @code{first}, @code{last} or a number that | |
81 specifies a zero-based position (@code{first} is equivalent to 0). If | |
82 no position is specified, the default is @code{first}. The | |
83 @var{position} value is ignored when redefining an existing piece of | |
84 advice. | |
85 | |
86 The optional @var{arglist} can be used to define the argument list for | |
87 the sake of advice. This argument list should of course be compatible | |
88 with the argument list of the original function, otherwise functions | |
89 that call the advised function with the original argument list in mind | |
90 will break. If more than one piece of advice specifies an argument | |
91 list, then the first one (the one with the smallest position) found in | |
92 the list of all classes of advice will be used. | |
93 | |
94 @var{flags} is a list of symbols that specify further information about | |
95 how to use this piece of advice. Here are the valid symbols and their | |
96 meanings: | |
97 | |
98 @table @code | |
99 @item activate | |
100 Activate all the advice for @var{function} after making this definition. | |
101 This is ignored when @var{function} itself is not defined yet (which is | |
102 known as @dfn{forward advice}). | |
103 | |
104 @item protect | |
105 Protect this piece of advice against non-local exits and errors in | |
106 preceding code and advice. | |
107 | |
108 @item compile | |
109 Says that the combined definition which implements advice should be | |
110 byte-compiled. This flag is ignored unless @code{activate} is also | |
111 specified. | |
112 | |
113 @item disable | |
114 Disable this piece of advice, so that it will not be used | |
115 unless subsequently explicitly enabled. | |
116 | |
117 @item preactivate | |
118 Activate advice for @var{function} when this @code{defadvice} is | |
119 compiled or macroexpanded. This generates a compiled advised definition | |
120 according to the current advice state, which will be used during | |
121 activation if appropriate. | |
122 | |
123 This is useful only if this @code{defadvice} is byte-compiled. | |
124 @end table | |
125 | |
126 The optional @var{documentation-string} serves to document this piece of | |
127 advice. If the @code{documentation} function gets the documentation | |
128 for @var{function} when its advice is active, the result will combine | |
129 the documentation strings of all the advice with that of the original | |
130 function. | |
131 | |
132 The optional @var{interactive-form} form can be supplied to change the | |
133 interactive behavior of the original function. If more than one piece | |
134 of advice has an @var{interactive-form}, then the first one (the one | |
135 with the smallest position) found among all the advice takes precedence. | |
136 | |
137 The possibly empty list of @var{body-forms} specifies the body of the | |
138 advice. The body of an advice can access or change the arguments, the | |
139 return value, the binding environment, and perform any other kind of | |
140 side effect. | |
141 | |
142 @strong{Warning:} When you advise a macro, keep in mind that macros are | |
143 expanded when a program is compiled, not when a compiled program is run. | |
144 All subroutines used by the advice need to be available when the byte | |
145 compiler expands the macro. | |
146 | |
147 @node Computed Advice | |
148 @section Computed Advice | |
149 | |
150 The macro @code{defadvice} resembles @code{defun} in that the code for | |
151 the advice, and all other information about it, are explicitly stated in | |
152 the source code. You can also create advice whose details are computed, | |
153 using the function @code{ad-add-advice}. | |
154 | |
155 @defun ad-add-advice function advice class position | |
156 Calling @code{ad-add-advice} adds @var{advice} as a piece of advice to | |
157 @var{function} in class @var{class}. The argument @var{advice} has | |
158 this form: | |
159 | |
160 @example | |
161 (@var{name} @var{protected} @var{enabled} @var{definition}) | |
162 @end example | |
163 | |
164 Here @var{protected} and @var{enabled} are flags, and @var{definition} | |
165 is an expression that says what the advice should do. | |
166 | |
167 If @var{function} already has one or more pieces of advice in the | |
168 specified @var{class}, then @var{position} specifies where in the list | |
169 to put the new piece of advice. The value of @var{position} can either | |
170 be @code{first}, @code{last}, or a number (counting from 0 at the | |
171 beginning of the list). Numbers outside the range are mapped to the | |
172 closest extreme position. | |
173 | |
174 If @var{function} already has a piece of @var{advice} with the same | |
175 name, then the position argument is ignored and the old advice is | |
176 replaced with the new one. | |
177 @end defun | |
178 | |
179 @node Activation of Advice | |
180 @section Activation of Advice | |
181 @cindex activating advice | |
182 | |
183 By default, advice does not take effect when you define it---only when | |
184 you @dfn{activate} advice for the function that was advised. You can | |
185 request the activation of advice for a function when you define the | |
186 advice, by specifying the @code{activate} flag in the @code{defadvice}. | |
187 But normally you activate the advice for a function by calling the | |
188 function @code{ad-activate} or one of the other activation commands | |
189 listed below. | |
190 | |
191 Separating the activation of advice from the act of defining it permits | |
192 you to add several pieces of advice to one function efficiently, without | |
193 redefining the function over and over as each advice is added. More | |
194 importantly, it permits defining advice for a function before that | |
195 function is actually defined. | |
196 | |
197 When a function is first activated, its original definition is saved, | |
198 and all enabled pieces of advice for that function are combined with the | |
199 original definition to make a new definition. This definition is | |
200 installed, and optionally byte-compiled as well, depending on conditions | |
201 described below. | |
202 | |
203 In all of the commands to activate advice, if @var{compile} is @code{t}, | |
204 the command also compiles the combined definition which implements the | |
205 advice. | |
206 | |
207 @deffn Command ad-activate function &optional compile | |
208 This command activates the advice for @var{function}. | |
209 @end deffn | |
210 | |
211 To activate a function whose advice is already active is not a no-op. | |
212 It is a useful operation which puts into effect any changes in advice | |
213 since the previous activation of the same function. | |
214 | |
215 @deffn Command ad-deactivate function | |
216 This command deactivates the advice for @var{function}. | |
217 @end deffn | |
218 | |
219 @deffn Command ad-activate-all &optional compile | |
220 This command activates the advice for all functions. | |
221 @end deffn | |
222 | |
223 @deffn Command ad-deactivate-all | |
224 This command deactivates the advice for all functions. | |
225 @end deffn | |
226 | |
227 @deffn Command ad-activate-regexp regexp &optional compile | |
228 This command activates all pieces of advice whose names match | |
229 @var{regexp}. More precisely, it activates all advice for any function | |
230 which has at least one piece of advice that matches @var{regexp}. | |
231 @end deffn | |
232 | |
233 @deffn Command ad-deactivate-regexp regexp | |
234 This command deactivates the advice for all functions whose names match | |
235 @var{regexp}. More precisely, it deactivates all advice for any | |
236 function which has at least one piece of advice that matches | |
237 @var{regexp}. | |
238 @end deffn | |
239 | |
240 @deffn Command ad-update-regexp regexp &optional compile | |
241 This command activates pieces of advice whose names match @var{regexp}, | |
242 but only those that are already activated. | |
243 @end deffn | |
244 | |
245 @deffn Command ad-stop-advice | |
246 Turn off automatic advice activation when a function is defined or | |
247 redefined. | |
248 @end deffn | |
249 | |
250 @deffn Command ad-start-advice | |
251 Turn off automatic advice activation when a function is defined or | |
252 redefined. | |
253 @end deffn | |
254 | |
255 @defopt ad-default-compilation-action | |
256 This variable controls whether to compile the combined definition | |
257 that results from activating advice for a function. | |
258 @end defopt | |
259 | |
260 If the advised definition was constructed during ``preactivation'' (see | |
261 below), then that definition must already be compiled, because it was | |
262 constructed during byte-compilation of the file that contained the | |
263 @code{defadvice} with the @code{preactivate} flag. | |
264 | |
265 @node Enabling Advice | |
266 @section Enabling and Disabling Advice | |
267 | |
268 Each piece of advice has a flag that says whether it is enabled or | |
269 not. By enabling or disabling a piece of advice, you can turn it off | |
270 and on without having to undefine and redefine it. For example, here is | |
271 how to disable a particular piece of advice named @code{my-advice} for | |
272 the function @code{foo}: | |
273 | |
274 @example | |
275 (ad-disable-advice 'foo 'before 'my-advice) | |
276 @end example | |
277 | |
278 This call by itself only changes the enable flag for this piece of | |
279 advice. To make this change take effect in the advised definition, you | |
280 must activate the advice for @code{foo} again: | |
281 | |
282 @example | |
283 (ad-activate 'foo) | |
284 @end example | |
285 | |
286 @deffn Command ad-disable-advice function class name | |
287 This command disables the piece of advice named @var{name} in class | |
288 @var{class} on @var{function}. | |
289 @end deffn | |
290 | |
291 @deffn Command ad-enable-advice function class name | |
292 This command enables the piece of advice named @var{name} in class | |
293 @var{class} on @var{function}. | |
294 @end deffn | |
295 | |
296 You can also disable many pieces of advice at once using a regular | |
297 expression. | |
298 | |
299 @deffn Command ad-disable-regexp regexp | |
300 This command disables all pieces of advice whose names match | |
301 @var{regexp}, in all classes, on all functions. | |
302 @end deffn | |
303 | |
304 @deffn Command ad-enable-regexp regexp | |
305 This command enables all pieces of advice whose names match | |
306 @var{regexp}, in all classes, on all functions. | |
307 @end deffn | |
308 | |
309 @node Preactivation | |
310 @section Preactivation | |
311 | |
312 Constructing a combined definition to execute advice is moderately | |
313 expensive. When a library advises many functions, this can make loading | |
314 the library slow. In that case, you can use @dfn{preactivation} to | |
315 construct suitable combined definitions in advance. | |
316 | |
317 To use preactivation, specify the @code{preactivate} flag when you | |
318 define the advice with @code{defadvice}. This @code{defadvice} call | |
319 creates a combined definition which embodies this piece of advice | |
320 (whether enabled or not) plus any other currently enabled advice for the | |
321 same function, and the function's own definition. If the | |
322 @code{defadvice} is compiled, that compiles the combined definition | |
323 also. | |
324 | |
325 When the function is subsequently activated, if the enabled advice for | |
326 the function matches what was used to make this combined | |
327 definition. then the existing combined definition is used, and there is | |
328 no need to construct one. Thus, preactivation never causes wrong | |
329 results---but it may fail to do any good, if the enabled advice at the | |
330 time of activation doesn't match. | |
331 | |
332 Here are some symptoms that can indicate that a preactivation did not | |
333 work properly, because of a mismatch. | |
334 | |
335 @itemize @bullet | |
336 @item | |
337 Activation of the advised | |
338 function takes longer than usual. | |
339 @item | |
340 The byte-compiler gets | |
341 loaded while an advised function gets activated. | |
342 @item | |
343 @code{byte-compile} is included in the value of @code{features} even | |
344 though you did not ever explicitly use the byte-compiler. | |
345 @end itemize | |
346 | |
347 Compiled preactivated advice works properly even if the function itself | |
348 is not defined until later; however, the function needs to be defined | |
349 when you @emph{compile} the preactivated advice. | |
350 | |
351 There is no elegant way to find out why preactivated advice is not being | |
352 used. What you can do is to trace the function | |
353 @code{ad-cache-id-verification-code} (with the function | |
354 @code{trace-function-background}) before the advised function is | |
355 activated. After activation, check the value returned by | |
356 @code{ad-cache-id-verification-code} for that function: @code{verified} | |
357 means that the preactivated advice was used, while other values give | |
358 some information about why they were considered inappropriate. | |
359 | |
360 @strong{Warning:} There is one known case that can make preactivation | |
361 fail, in that a preconstructed combined definition is used even though | |
362 it fails to match the current state of advice. This can happen when two | |
363 packages define different pieces of advice with the same name, in the | |
364 same class, for the same function. But you should avoid that anyway. | |
365 | |
366 @node Argument Access in Advice | |
367 @section Argument Access in Advice | |
368 | |
369 The simplest way to access the arguments of an advised function in the | |
370 body of a piece of advice is to use the same names that the function | |
371 definition uses. To do this, you need to know the names of the argument | |
372 variables of the original function. | |
373 | |
374 While this simple method is sufficient in many cases, it has a | |
375 disadvantage: it is not robust, because it hard-codes the argument names | |
376 into the advice. If the definition of the original function changes, | |
377 the advice might break. | |
378 | |
379 A more robust method is to use macros that are translated into the | |
380 proper access forms at activation time, i.e., when constructing the | |
381 advised definition. Access macros access actual arguments by position | |
382 regardless of how these actual argument get distributed onto the | |
383 argument variables of a function. This is robust because in Emacs Lisp | |
384 the meaning of an argument is strictly determined by its position in the | |
385 argument list. | |
386 | |
387 @defmac ad-get-arg position | |
388 This returns the actual argument that was supplied at @var{position}. | |
389 @end defmac | |
390 | |
391 @defmac ad-get-args position | |
392 This returns the list of actual arguments supplied starting at | |
393 @var{position}. | |
394 @end defmac | |
395 | |
396 @defmac ad-set-arg position value | |
397 This sets the value of the actual argument at @var{position} to | |
398 @var{value} | |
399 @end defmac | |
400 | |
401 @defmac ad-set-args position value-list | |
402 This sets the list of actual arguments starting at @var{position} to | |
403 @var{value-list}. | |
404 @end defmac | |
405 | |
406 Now an example. Suppose the function @code{foo} is defined as | |
407 | |
408 @example | |
409 (defun foo (x y &optional z &rest r) ...) | |
410 @end example | |
411 | |
412 @noindent | |
413 and is then called with | |
414 | |
415 @example | |
416 (foo 0 1 2 3 4 5 6) | |
417 @end example | |
418 | |
419 @noindent | |
420 which means that @var{x} is 0, @var{y} is 1, @var{z} is 2 and @var{r} is | |
421 @code{(3 4 5 6)} within the body of @code{foo}. Here is what | |
422 @code{ad-get-arg} and @code{ad-get-args} return in this case: | |
423 | |
424 @example | |
425 (ad-get-arg 0) @result{} 0 | |
426 (ad-get-arg 1) @result{} 1 | |
427 (ad-get-arg 2) @result{} 2 | |
428 (ad-get-arg 3) @result{} 3 | |
429 (ad-get-args 2) @result{} (2 3 4 5 6) | |
430 (ad-get-args 4) @result{} (4 5 6) | |
431 @end example | |
432 | |
433 Setting arguments also makes sense in this example: | |
434 | |
435 @example | |
436 (ad-set-arg 5 "five") | |
437 @end example | |
438 | |
439 @noindent | |
440 has the effect of changing the sixth argument to @code{"five"}. If this | |
441 happens in advice executed before the body of @code{foo} is run, then | |
442 @var{r} will be @code{(3 4 "five" 6)} within that body. | |
443 | |
444 Here is an example of setting a tail of the argument list: | |
445 | |
446 @example | |
447 (ad-set-args 0 '(5 4 3 2 1 0)) | |
448 @end example | |
449 | |
450 @noindent | |
451 If this happens in advice executed before the body of @code{foo} is run, | |
452 then within that body, @var{x} will be 5, @var{y} will be 4, @var{z} | |
453 will be 3, and @var{r} will be @code{(2 1 0)} inside the body of | |
454 @code{foo}. | |
455 | |
456 These argument constructs are not really implemented as Lisp macros. | |
457 Instead they are implemented specially by the advice mechanism. | |
458 | |
459 @subsection Definition of Subr Argument Lists | |
460 | |
461 When the advice facility constructs the combined definition, it needs | |
462 to know the argument list of the original function. This is not always | |
463 possible for primitive functions. When advice cannot determine the | |
464 argument list, it uses @code{(&rest ad-subr-args)}, which always works | |
465 but is inefficient because it constructs a list of the argument values. | |
466 You can use @code{ad-define-subr-args} to declare the proper argument | |
467 names for a primitive function: | |
468 | |
469 @defun ad-define-subr-args function arglist | |
470 This function specifies that @var{arglist} should be used as the | |
471 argument list for function @var{function}. | |
472 @end defun | |
473 | |
474 For example, | |
475 | |
476 @example | |
477 (ad-define-subr-args 'fset '(sym newdef)) | |
478 @end example | |
479 | |
480 @noindent | |
481 specifies the argument list for the function @code{fset}. | |
482 | |
483 @node Combined Definition | |
484 @section The Combined Definition | |
485 | |
486 Suppose that a function has @var{n} pieces of before-advice, @var{m} | |
487 pieces of around-advice and @var{k} pieces of after-advice. Assuming no | |
488 piece of advice is protected, the combined definition produced to | |
489 implement the advice for a function looks like this: | |
490 | |
491 @example | |
492 (lambda @var{arglist} | |
493 @r{[} @r{[}@var{advised-docstring}@r{]} @r{[}(interactive ...)@r{]} @r{]} | |
494 (let (ad-return-value) | |
495 @r{before-0-body-form}... | |
496 .... | |
497 @r{before-@var{n}-1-body-form}... | |
498 @r{around-0-body-form}... | |
499 @r{around-1-body-form}... | |
500 .... | |
501 @r{around-@var{m}-1-body-form}... | |
502 (setq ad-return-value | |
503 @r{apply original definition to @var{arglist}}) | |
504 @r{other-around-@var{m}-1-body-form}... | |
505 .... | |
506 @r{other-around-1-body-form}... | |
507 @r{other-around-0-body-form}... | |
508 @r{after-0-body-form}... | |
509 .... | |
510 @r{after-@var{k}-1-body-form}... | |
511 ad-return-value)) | |
512 @end example | |
513 | |
514 Macros are redefined as macros, which means adding @code{macro} to | |
515 the beginning of the combined definition. | |
516 | |
517 The interactive form is present if the original function or some piece | |
518 of advice specifies one. When an interactive primitive function is | |
519 advised, a special method is used: to call the primitive with | |
520 @code{call-interactively} so that it will read its own arguments. | |
521 In this case, the advice cannot access the arguments. | |
522 | |
523 The body forms of the various advice in each class are assembled | |
524 according to their specified order. The forms of around-advice @var{l} | |
525 are included in one of the forms of around-advice @var{l} @minus{} 1. | |
526 | |
527 The innermost part of the around advice onion is | |
528 | |
529 @display | |
530 apply original definition to @var{arglist} | |
531 @end display | |
532 | |
533 @noindent | |
534 whose form depends on the type of the original function. The variable | |
535 @code{ad-return-value} is set to whatever this returns. The variable is | |
536 visible to all pieces of advice, which can access and modify it before | |
537 it is actually returned from the advised function. | |
538 | |
539 The semantic structure of advised functions that contain protected | |
540 pieces of advice is the same. The only difference is that | |
541 @code{unwind-protect} forms ensure that the protected advice gets | |
542 executed even if some previous piece of advice had an error or a | |
543 non-local exit. If any around-advice is protected, then the whole | |
544 around-advice onion is protected as a result. |