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