6.3 The Advice Facility

6.3.1 About Advice

Assume that a certain symbol has a function definition. When some advice is applied, the symbol is changed to have a new definition, called a piece of advice. From within the advice, the original definition is called the continuation.

When the symbol is called as a function, the advice is called instead of the original definition. The advice accepts the arguments and returns the value for the call. The advice might or might not call its continuation, or it might call its continuation several times or with different arguments. The advice might pass on its return values, or it might modify or ignore them. It might do exactly what the continuation does, or it might perform an unrelated action. In other words, the advice takes the place of the original definition for all external interfaces.

You can supply multiple, nested pieces of advice for a function. The outermost piece of advice is the one that is invoked first when the function is called. The continuation for the outermost advice is the next inner piece of advice, and so on. The continuation for the innermost piece of advice is the original definition of the function.

To create a piece of advice, use thedefadvice macro. You can specify the order of the pieces of advice by using the place argument todefadvice. To call the advised function from within the body ofdefadvice, use the macros advice-continue and apply-advice-continue.

To remove a piece of advice, use the function remove-advice. If the advice is removed, the continuation is restored as the definition of the symbol.

For the sake of efficiency, you might want to have compiled advice for a function. There are two procedures for providing compiled advice:

;; Define a function to handle the advising.
(defun install-my-fun-advice ()
   (defadvice (fun do-my-stuff) (&rest args)
     (do-my-stuff args)
     (apply-advice-continue args)))

;; Compile the function. (compile 'install-my-fun-advice)

;; Execute the function. (install-my-fun-advice)

The Advanced User's Guide - 9 SEP 1996

Generated with Harlequin WebMaker