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