annotate lispref/advice.texi @ 22099:50b3a29265e4

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