6.3 The Advice Facility

6.3.3 Reference pages

apply-advice-continue Macro

Syntax:advice-continue&rest args

Syntax:apply-advice-continue args&rest more-args

The macrosadvice-continue andapply-advice-continue call an advised function from within the body ofdefadvice.

The macroadvice-continue applies the continuation to the specified arguments.

The macroapply-advice-continue applies the continuation to a specified list of arguments.

The macroapply-advice-continue is toadvice-continue as the Common Lisp functionapply is tofuncall.

Syntax:defadvice (function-to-advise name-of-advice&optional place) (lambda-list) {form}*

The macrodefadvice defines a piece of advice for a specified function.

The function-to-advise argument is the name of the function being advised. Only functions that are stored as definitions of symbols can be advised.

The name-of-advice argument specifies a name for the advice. Any existing advice with this name is replaced; the names are compared by using the Common Lisp functionstring-equal.

The optional place argument specifies how the advice that is being defined relates to other pieces of advice on the same function. This argument should be a list of keywords and values. The following options are valid:

• (:outside name), (:before name)

The:outside keyword option puts the piece of advice that is being defined outside the advice with the specified name; the:before keyword option is synonymous.

• (:inside name), (:after name)

The:inside keyword option puts the piece of advice that is being defined inside the advice with the specified name; the:after keyword option is synonymous.

If no advice with the specified name exists, the place argument has no effect. However, if you later define advice with the name name, the relationship described by this place argument takes effect.

If you omit the place argument, the new piece of advice goes outside any advice defined earlier and inside any advice defined later. If the order of the pieces of advice is important, you should explicitly specify the position of the new advice in relation to the existing pieces.

The lambda-list argument specifies the arguments to the advised function.

The forms specified by the form arguments make up the body ofdefadvice, which is any normal function body.

Ifdefadvice appears in a compiled file, the advice is compiled.

Note: Defining a macro causes an expansion function for the given macro to be associated with the macro name. When you define advice for a macro,defadvice advises the expansion function for the macro, not the macro itself. For information about expansion functions for macros, see the chapter on macros in CLtL2.

;; Define a macro that creates a cons of an object with itself.
> (defmacro two (x) '(cons ,x ,x))
TWO

> (macroexpand '(two 3))           ; It expands into consing code.
(CONS 3 3)
T

> (two 3)                              ; It returns a cons cell.
(3 . 3)

;; Now advise the expansion function.  The advice first takes 
;; apart the form it is given and then creates a new form for the
;; macro to expand. In this case, if the FORM argument is (TWO 3),
;; the NAME argument is TWO and the ARG argument is 3.  You call
;; the continuation with the form (TWO (1+ 3)) for it to expand. 
;; The continuation expands this form into (CONS (1+ 3) (1+ 3)),
;; as shown.
> (defadvice (two add-one-first) (form &optional env)
    (destructuring-bind (name arg) form
       (advice-continue '(,name (1+ ,arg)) env)))
#<ADVICE ADD-ONE-FIRST B52087>

> (macroexpand '(two 3))
(CONS (1+ 3) (1+ 3))
T

> (two 3)
(4 . 4)

Syntax:describe-advice function

The functiondescribe-advice describes all levels of advice for a specified function.

The function argument names the function whose advice is being described.

See Also: defadvice

Syntax:remove-advice function&optional advice-name

The functionremove-advice removes some or all of the advice from a specified function.

The function argument specifies the name of the function from which the advice should be removed.

The advice-name argument specifies the name of the advice to be removed. If you specify the advice-name argument, only advice that matches the given name is removed. The names are compared by using the Common Lisp functionstring-equal. If you do not specify this argument, all advice is removed from the function.

See Also: defadvice

Generated with Harlequin WebMaker