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