Mercurial > emacs
annotate doc/lispref/advice.texi @ 105336:bd4a08d4865a
Fix comment typo.
author | Glenn Morris <rgm@gnu.org> |
---|---|
date | Thu, 01 Oct 2009 04:31:40 +0000 |
parents | a43e99d78f43 |
children | 1d1d5d9bd884 |
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, | |
100974 | 4 @c 2005, 2006, 2007, 2008, 2009 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 | |
99046
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
317 @var{function} in class @var{class}. The argument @var{advice} has |
84047 | 318 this form: |
319 | |
320 @example | |
321 (@var{name} @var{protected} @var{enabled} @var{definition}) | |
322 @end example | |
323 | |
99046
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
324 @noindent |
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
325 Here, @var{protected} and @var{enabled} are flags; if @var{protected} |
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
326 is non-@code{nil}, the advice is protected against non-local exits |
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
327 (@pxref{Defining Advice}), and if @var{enabled} is @code{nil} the |
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
328 advice is initially disabled (@pxref{Enabling Advice}). |
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
329 @var{definition} should have the form |
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
330 |
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
331 @example |
99071
39579cd31158
(Computed Advice): Minor phrasing change.
Chong Yidong <cyd@stupidchicken.com>
parents:
99046
diff
changeset
|
332 (advice . @var{lambda}) |
99046
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
333 @end example |
84047 | 334 |
99046
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
335 @noindent |
99071
39579cd31158
(Computed Advice): Minor phrasing change.
Chong Yidong <cyd@stupidchicken.com>
parents:
99046
diff
changeset
|
336 where @var{lambda} is a lambda expression; this lambda expression is |
39579cd31158
(Computed Advice): Minor phrasing change.
Chong Yidong <cyd@stupidchicken.com>
parents:
99046
diff
changeset
|
337 called in order to perform the advice. @xref{Lambda Expressions}. |
99046
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
338 |
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
339 If the @var{function} argument to @code{ad-add-advice} already has one |
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
340 or more pieces of advice in the specified @var{class}, then |
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
341 @var{position} specifies where in the list to put the new piece of |
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
342 advice. The value of @var{position} can either be @code{first}, |
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
343 @code{last}, or a number (counting from 0 at the beginning of the |
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
344 list). Numbers outside the range are mapped to the beginning or the |
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
345 end of the range, whichever is closer. The @var{position} value is |
7257b84b68a2
(Computed Advice): Explain what DEFINITION is.
Chong Yidong <cyd@stupidchicken.com>
parents:
87649
diff
changeset
|
346 ignored when redefining an existing piece of advice. |
84047 | 347 |
348 If @var{function} already has a piece of @var{advice} with the same | |
349 name, then the position argument is ignored and the old advice is | |
350 replaced with the new one. | |
351 @end defun | |
352 | |
353 @node Activation of Advice | |
354 @section Activation of Advice | |
355 @cindex activating advice | |
356 @cindex advice, activating | |
357 | |
358 By default, advice does not take effect when you define it---only when | |
359 you @dfn{activate} advice for the function that was advised. However, | |
360 the advice will be activated automatically if you define or redefine | |
361 the function later. You can request the activation of advice for a | |
362 function when you define the advice, by specifying the @code{activate} | |
363 flag in the @code{defadvice}. But normally you activate the advice | |
364 for a function by calling the function @code{ad-activate} or one of | |
365 the other activation commands listed below. | |
366 | |
367 Separating the activation of advice from the act of defining it permits | |
368 you to add several pieces of advice to one function efficiently, without | |
369 redefining the function over and over as each advice is added. More | |
370 importantly, it permits defining advice for a function before that | |
371 function is actually defined. | |
372 | |
373 When a function's advice is first activated, the function's original | |
374 definition is saved, and all enabled pieces of advice for that function | |
375 are combined with the original definition to make a new definition. | |
376 (Pieces of advice that are currently disabled are not used; see | |
377 @ref{Enabling Advice}.) This definition is installed, and optionally | |
378 byte-compiled as well, depending on conditions described below. | |
379 | |
380 In all of the commands to activate advice, if @var{compile} is | |
381 @code{t} (or anything but @code{nil} or a negative number), the | |
382 command also compiles the combined definition which implements the | |
383 advice. If it is @code{nil} or a negative number, what happens | |
384 depends on @code{ad-default-compilation-action} as described below. | |
385 | |
386 @deffn Command ad-activate function &optional compile | |
387 This command activates all the advice defined for @var{function}. | |
388 @end deffn | |
389 | |
390 Activating advice does nothing if @var{function}'s advice is already | |
391 active. But if there is new advice, added since the previous time you | |
392 activated advice for @var{function}, it activates the new advice. | |
393 | |
394 @deffn Command ad-deactivate function | |
395 This command deactivates the advice for @var{function}. | |
396 @cindex deactivating advice | |
397 @c @cindex advice, deactivating "advice, activating" is just above | |
398 @end deffn | |
399 | |
400 @deffn Command ad-update function &optional compile | |
401 This command activates the advice for @var{function} | |
402 if its advice is already activated. This is useful | |
403 if you change the advice. | |
404 @end deffn | |
405 | |
406 @deffn Command ad-activate-all &optional compile | |
407 This command activates the advice for all functions. | |
408 @end deffn | |
409 | |
410 @deffn Command ad-deactivate-all | |
411 This command deactivates the advice for all functions. | |
412 @end deffn | |
413 | |
414 @deffn Command ad-update-all &optional compile | |
415 This command activates the advice for all functions | |
416 whose advice is already activated. This is useful | |
417 if you change the advice of some functions. | |
418 @end deffn | |
419 | |
420 @deffn Command ad-activate-regexp regexp &optional compile | |
421 This command activates all pieces of advice whose names match | |
422 @var{regexp}. More precisely, it activates all advice for any function | |
423 which has at least one piece of advice that matches @var{regexp}. | |
424 @end deffn | |
425 | |
426 @deffn Command ad-deactivate-regexp regexp | |
427 This command deactivates all pieces of advice whose names match | |
428 @var{regexp}. More precisely, it deactivates all advice for any | |
429 function which has at least one piece of advice that matches | |
430 @var{regexp}. | |
431 @end deffn | |
432 | |
433 @deffn Command ad-update-regexp regexp &optional compile | |
434 This command activates pieces of advice whose names match @var{regexp}, | |
435 but only those for functions whose advice is already activated. | |
436 @cindex reactivating advice | |
437 | |
438 Reactivating a function's advice is useful for putting into effect all | |
439 the changes that have been made in its advice (including enabling and | |
440 disabling specific pieces of advice; @pxref{Enabling Advice}) since the | |
441 last time it was activated. | |
442 @end deffn | |
443 | |
444 @deffn Command ad-start-advice | |
445 Turn on automatic advice activation when a function is defined or | |
446 redefined. This is the default mode. | |
447 @end deffn | |
448 | |
449 @deffn Command ad-stop-advice | |
450 Turn off automatic advice activation when a function is defined or | |
451 redefined. | |
452 @end deffn | |
453 | |
454 @defopt ad-default-compilation-action | |
455 This variable controls whether to compile the combined definition | |
456 that results from activating advice for a function. | |
457 | |
458 A value of @code{always} specifies to compile unconditionally. | |
459 A value of @code{never} specifies never compile the advice. | |
460 | |
86437
5e5bea44b40c
(Preactivation, Activation of Advice): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
84116
diff
changeset
|
461 A value of @code{maybe} specifies to compile if the byte compiler is |
84047 | 462 already loaded. A value of @code{like-original} specifies to compile |
463 the advice if the original definition of the advised function is | |
464 compiled or a built-in function. | |
465 | |
466 This variable takes effect only if the @var{compile} argument of | |
467 @code{ad-activate} (or any of the above functions) did not force | |
468 compilation. | |
469 @end defopt | |
470 | |
471 If the advised definition was constructed during ``preactivation'' | |
472 (@pxref{Preactivation}), then that definition must already be compiled, | |
473 because it was constructed during byte-compilation of the file that | |
474 contained the @code{defadvice} with the @code{preactivate} flag. | |
475 | |
476 @node Enabling Advice | |
477 @section Enabling and Disabling Advice | |
478 @cindex enabling advice | |
479 @cindex advice, enabling and disabling | |
480 @cindex disabling advice | |
481 | |
482 Each piece of advice has a flag that says whether it is enabled or | |
483 not. By enabling or disabling a piece of advice, you can turn it on | |
484 and off without having to undefine and redefine it. For example, here is | |
485 how to disable a particular piece of advice named @code{my-advice} for | |
486 the function @code{foo}: | |
487 | |
488 @example | |
489 (ad-disable-advice 'foo 'before 'my-advice) | |
490 @end example | |
491 | |
492 This function by itself only changes the enable flag for a piece of | |
493 advice. To make the change take effect in the advised definition, you | |
494 must activate the advice for @code{foo} again: | |
495 | |
496 @example | |
497 (ad-activate 'foo) | |
498 @end example | |
499 | |
500 @deffn Command ad-disable-advice function class name | |
501 This command disables the piece of advice named @var{name} in class | |
502 @var{class} on @var{function}. | |
503 @end deffn | |
504 | |
505 @deffn Command ad-enable-advice function class name | |
506 This command enables the piece of advice named @var{name} in class | |
507 @var{class} on @var{function}. | |
508 @end deffn | |
509 | |
510 You can also disable many pieces of advice at once, for various | |
511 functions, using a regular expression. As always, the changes take real | |
512 effect only when you next reactivate advice for the functions in | |
513 question. | |
514 | |
515 @deffn Command ad-disable-regexp regexp | |
516 This command disables all pieces of advice whose names match | |
517 @var{regexp}, in all classes, on all functions. | |
518 @end deffn | |
519 | |
520 @deffn Command ad-enable-regexp regexp | |
521 This command enables all pieces of advice whose names match | |
522 @var{regexp}, in all classes, on all functions. | |
523 @end deffn | |
524 | |
525 @node Preactivation | |
526 @section Preactivation | |
527 @cindex preactivating advice | |
528 @cindex advice, preactivating | |
529 | |
530 Constructing a combined definition to execute advice is moderately | |
531 expensive. When a library advises many functions, this can make loading | |
532 the library slow. In that case, you can use @dfn{preactivation} to | |
533 construct suitable combined definitions in advance. | |
534 | |
535 To use preactivation, specify the @code{preactivate} flag when you | |
536 define the advice with @code{defadvice}. This @code{defadvice} call | |
537 creates a combined definition which embodies this piece of advice | |
538 (whether enabled or not) plus any other currently enabled advice for the | |
539 same function, and the function's own definition. If the | |
540 @code{defadvice} is compiled, that compiles the combined definition | |
541 also. | |
542 | |
543 When the function's advice is subsequently activated, if the enabled | |
544 advice for the function matches what was used to make this combined | |
545 definition, then the existing combined definition is used, thus avoiding | |
546 the need to construct one. Thus, preactivation never causes wrong | |
547 results---but it may fail to do any good, if the enabled advice at the | |
548 time of activation doesn't match what was used for preactivation. | |
549 | |
550 Here are some symptoms that can indicate that a preactivation did not | |
551 work properly, because of a mismatch. | |
552 | |
553 @itemize @bullet | |
554 @item | |
555 Activation of the advised | |
556 function takes longer than usual. | |
557 @item | |
86437
5e5bea44b40c
(Preactivation, Activation of Advice): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
84116
diff
changeset
|
558 The byte compiler gets |
84047 | 559 loaded while an advised function gets activated. |
560 @item | |
561 @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
|
562 though you did not ever explicitly use the byte compiler. |
84047 | 563 @end itemize |
564 | |
565 Compiled preactivated advice works properly even if the function itself | |
566 is not defined until later; however, the function needs to be defined | |
567 when you @emph{compile} the preactivated advice. | |
568 | |
569 There is no elegant way to find out why preactivated advice is not being | |
570 used. What you can do is to trace the function | |
571 @code{ad-cache-id-verification-code} (with the function | |
572 @code{trace-function-background}) before the advised function's advice | |
573 is activated. After activation, check the value returned by | |
574 @code{ad-cache-id-verification-code} for that function: @code{verified} | |
575 means that the preactivated advice was used, while other values give | |
576 some information about why they were considered inappropriate. | |
577 | |
578 @strong{Warning:} There is one known case that can make preactivation | |
579 fail, in that a preconstructed combined definition is used even though | |
580 it fails to match the current state of advice. This can happen when two | |
581 packages define different pieces of advice with the same name, in the | |
582 same class, for the same function. But you should avoid that anyway. | |
583 | |
584 @node Argument Access in Advice | |
585 @section Argument Access in Advice | |
586 | |
587 The simplest way to access the arguments of an advised function in the | |
588 body of a piece of advice is to use the same names that the function | |
589 definition uses. To do this, you need to know the names of the argument | |
590 variables of the original function. | |
591 | |
592 While this simple method is sufficient in many cases, it has a | |
593 disadvantage: it is not robust, because it hard-codes the argument names | |
594 into the advice. If the definition of the original function changes, | |
595 the advice might break. | |
596 | |
597 Another method is to specify an argument list in the advice itself. | |
598 This avoids the need to know the original function definition's argument | |
599 names, but it has a limitation: all the advice on any particular | |
600 function must use the same argument list, because the argument list | |
601 actually used for all the advice comes from the first piece of advice | |
602 for that function. | |
603 | |
604 A more robust method is to use macros that are translated into the | |
605 proper access forms at activation time, i.e., when constructing the | |
104291
a43e99d78f43
* advice.texi (Argument Access in Advice): Note that argument
Chong Yidong <cyd@stupidchicken.com>
parents:
102513
diff
changeset
|
606 advised definition. Access macros access actual arguments by their |
a43e99d78f43
* advice.texi (Argument Access in Advice): Note that argument
Chong Yidong <cyd@stupidchicken.com>
parents:
102513
diff
changeset
|
607 (zero-based) position, regardless of how these actual arguments get |
a43e99d78f43
* advice.texi (Argument Access in Advice): Note that argument
Chong Yidong <cyd@stupidchicken.com>
parents:
102513
diff
changeset
|
608 distributed onto the argument variables of a function. This is robust |
a43e99d78f43
* advice.texi (Argument Access in Advice): Note that argument
Chong Yidong <cyd@stupidchicken.com>
parents:
102513
diff
changeset
|
609 because in Emacs Lisp the meaning of an argument is strictly |
a43e99d78f43
* advice.texi (Argument Access in Advice): Note that argument
Chong Yidong <cyd@stupidchicken.com>
parents:
102513
diff
changeset
|
610 determined by its position in the argument list. |
84047 | 611 |
612 @defmac ad-get-arg position | |
613 This returns the actual argument that was supplied at @var{position}. | |
614 @end defmac | |
615 | |
616 @defmac ad-get-args position | |
617 This returns the list of actual arguments supplied starting at | |
618 @var{position}. | |
619 @end defmac | |
620 | |
621 @defmac ad-set-arg position value | |
622 This sets the value of the actual argument at @var{position} to | |
623 @var{value} | |
624 @end defmac | |
625 | |
626 @defmac ad-set-args position value-list | |
627 This sets the list of actual arguments starting at @var{position} to | |
628 @var{value-list}. | |
629 @end defmac | |
630 | |
631 Now an example. Suppose the function @code{foo} is defined as | |
632 | |
633 @example | |
634 (defun foo (x y &optional z &rest r) ...) | |
635 @end example | |
636 | |
637 @noindent | |
638 and is then called with | |
639 | |
640 @example | |
641 (foo 0 1 2 3 4 5 6) | |
642 @end example | |
643 | |
644 @noindent | |
645 which means that @var{x} is 0, @var{y} is 1, @var{z} is 2 and @var{r} is | |
646 @code{(3 4 5 6)} within the body of @code{foo}. Here is what | |
647 @code{ad-get-arg} and @code{ad-get-args} return in this case: | |
648 | |
649 @example | |
650 (ad-get-arg 0) @result{} 0 | |
651 (ad-get-arg 1) @result{} 1 | |
652 (ad-get-arg 2) @result{} 2 | |
653 (ad-get-arg 3) @result{} 3 | |
654 (ad-get-args 2) @result{} (2 3 4 5 6) | |
655 (ad-get-args 4) @result{} (4 5 6) | |
656 @end example | |
657 | |
658 Setting arguments also makes sense in this example: | |
659 | |
660 @example | |
661 (ad-set-arg 5 "five") | |
662 @end example | |
663 | |
664 @noindent | |
665 has the effect of changing the sixth argument to @code{"five"}. If this | |
666 happens in advice executed before the body of @code{foo} is run, then | |
667 @var{r} will be @code{(3 4 "five" 6)} within that body. | |
668 | |
669 Here is an example of setting a tail of the argument list: | |
670 | |
671 @example | |
672 (ad-set-args 0 '(5 4 3 2 1 0)) | |
673 @end example | |
674 | |
675 @noindent | |
676 If this happens in advice executed before the body of @code{foo} is run, | |
677 then within that body, @var{x} will be 5, @var{y} will be 4, @var{z} | |
678 will be 3, and @var{r} will be @code{(2 1 0)} inside the body of | |
679 @code{foo}. | |
680 | |
681 These argument constructs are not really implemented as Lisp macros. | |
682 Instead they are implemented specially by the advice mechanism. | |
683 | |
684 @node Advising Primitives | |
685 @section Advising Primitives | |
686 @cindex advising primitives | |
687 | |
102513
4357cad47eae
(Advising Primitives): Link to What Is a Function.
Chong Yidong <cyd@stupidchicken.com>
parents:
100974
diff
changeset
|
688 Advising a primitive function (@pxref{What Is a Function}) is risky. |
84047 | 689 Some primitive functions are used by the advice mechanism; advising |
690 them could cause an infinite recursion. Also, many primitive | |
691 functions are called directly from C code. Calls to the primitive | |
692 from Lisp code will take note of the advice, but calls from C code | |
693 will ignore the advice. | |
694 | |
695 When the advice facility constructs the combined definition, it needs | |
696 to know the argument list of the original function. This is not | |
697 always possible for primitive functions. When advice cannot determine | |
698 the argument list, it uses @code{(&rest ad-subr-args)}, which always | |
699 works but is inefficient because it constructs a list of the argument | |
700 values. You can use @code{ad-define-subr-args} to declare the proper | |
701 argument names for a primitive function: | |
702 | |
703 @defun ad-define-subr-args function arglist | |
704 This function specifies that @var{arglist} should be used as the | |
705 argument list for function @var{function}. | |
706 @end defun | |
707 | |
708 For example, | |
709 | |
710 @example | |
711 (ad-define-subr-args 'fset '(sym newdef)) | |
712 @end example | |
713 | |
714 @noindent | |
715 specifies the argument list for the function @code{fset}. | |
716 | |
717 @node Combined Definition | |
718 @section The Combined Definition | |
719 | |
720 Suppose that a function has @var{n} pieces of before-advice | |
721 (numbered from 0 through @var{n}@minus{}1), @var{m} pieces of | |
722 around-advice and @var{k} pieces of after-advice. Assuming no piece | |
723 of advice is protected, the combined definition produced to implement | |
724 the advice for a function looks like this: | |
725 | |
726 @example | |
727 (lambda @var{arglist} | |
728 @r{[} @r{[}@var{advised-docstring}@r{]} @r{[}(interactive ...)@r{]} @r{]} | |
729 (let (ad-return-value) | |
730 @r{before-0-body-form}... | |
731 .... | |
732 @r{before-@var{n}@minus{}1-body-form}... | |
733 @r{around-0-body-form}... | |
734 @r{around-1-body-form}... | |
735 .... | |
736 @r{around-@var{m}@minus{}1-body-form}... | |
737 (setq ad-return-value | |
738 @r{apply original definition to @var{arglist}}) | |
739 @r{end-of-around-@var{m}@minus{}1-body-form}... | |
740 .... | |
741 @r{end-of-around-1-body-form}... | |
742 @r{end-of-around-0-body-form}... | |
743 @r{after-0-body-form}... | |
744 .... | |
745 @r{after-@var{k}@minus{}1-body-form}... | |
746 ad-return-value)) | |
747 @end example | |
748 | |
749 Macros are redefined as macros, which means adding @code{macro} to | |
750 the beginning of the combined definition. | |
751 | |
752 The interactive form is present if the original function or some piece | |
753 of advice specifies one. When an interactive primitive function is | |
754 advised, advice uses a special method: it calls the primitive with | |
755 @code{call-interactively} so that it will read its own arguments. | |
756 In this case, the advice cannot access the arguments. | |
757 | |
758 The body forms of the various advice in each class are assembled | |
759 according to their specified order. The forms of around-advice @var{l} | |
760 are included in one of the forms of around-advice @var{l} @minus{} 1. | |
761 | |
762 The innermost part of the around advice onion is | |
763 | |
764 @display | |
765 apply original definition to @var{arglist} | |
766 @end display | |
767 | |
768 @noindent | |
769 whose form depends on the type of the original function. The variable | |
770 @code{ad-return-value} is set to whatever this returns. The variable is | |
771 visible to all pieces of advice, which can access and modify it before | |
772 it is actually returned from the advised function. | |
773 | |
774 The semantic structure of advised functions that contain protected | |
775 pieces of advice is the same. The only difference is that | |
776 @code{unwind-protect} forms ensure that the protected advice gets | |
777 executed even if some previous piece of advice had an error or a | |
778 non-local exit. If any around-advice is protected, then the whole | |
779 around-advice onion is protected as a result. | |
780 | |
781 @ignore | |
782 arch-tag: 80c135c2-f1c3-4f8d-aa85-f8d8770d307f | |
783 @end ignore |