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