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