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