6.1 Defining advice

Each change that is required should be specified using the defadvice macro. This defines a new body of code to be used when the function is called; this piece of code is called a piece of advice. Consider the following example:

(defadvice
   (capi:prompt-for-file pff-1 :before)
   (message &key &allow-other-keys)
 (format t "~&Prompting for file with message ~S~%" message))

Here defadvice is given the name of the function you want to alter, a name for the piece of advice, and the keyword :before to indicate that you want the code carried out before capi:prompt-for-file is called. The rest of the call to defadvice specifies the additional behavior required, and consists of the lambda list for the new piece of advice and its body (the lambda list may specify keyword parameters and so forth). The advice facility arranges that pff-1 is invoked whenever capi:prompt-for-file is called, and that it receives the arguments to capi:prompt-for-file, and that directly after this the original definition of capi:prompt-for-file is called.

After executing this advice definition, demonstrate it by selecting the menu command File > Open in the LispWorks IDE. The message appears in the Output tab.

Pieces of advice may be given to be executed after the call by specifying :after instead of :before in the call to defadvice. So if you wished to add further code to be performed after capi:prompt-for-file you could also define:

(defadvice
    (capi:prompt-for-file pff-2 :after)
    (message &rest args)
  (format t 
          "~&The other arguments to prompt-for-file were: ~S~%"
          args))

Note that pff-2 also receives the arguments to capi:prompt-for-file, which are reported by the body.

Note also that defadvice works on function names, not function objects, like trace. See 5.7.2.2 trace works on function names, not function objects for details.