annotate doc/lispref/advice.texi @ 99746:07389f46a9e0

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