annotate lispref/advice.texi @ 36322:b95226aa58b9

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