[Openmcl-devel] Am I failing to find documentation that exists?

[Daniel Weinreb]

I couldn't find any documentation of advise, either, so
I wrote some (which I hope is correct):


The macro CCL:ADVISE lets you modify the behavior of a function or
method in an arbitrary way.  You should not use ADVISE in production
code, but it's useful for debugging and other tools.

The argument list is::

  (function form &key when name define-if-not dynamic-extent-arglist)

It basically means: whenever FUNCTION is called, run FORM.

function
  The name of a function, or (:method name-of-method).  This is not 
evaluated.  The advice is placed on this.  You can use (setf xxx) as a 
function name.  FUNCTION cannot be the name of a macro or special form.

form
  The Lisp form to be evaluated when FUNCTION is called.
 
when
  (Evaluated.) One of :before, :after, or :around.  The default is 
:before.  If :before, then evaluate FORM before calling the function. If 
:after, evaluate FORM after calling the function. If :around, then just 
evaluate FORM whenever the function is called; if FORM wants to do the 
function call that would ordinarily have happened, it should evaluate 
"(:do-it)".

name
  (Evaluated.) A symbol that can be used to identify this piece of 
advice, as an argument to other functions.

define-if-not
  (NOT evaluated.) If FUNCTION is not defined, define it as a function 
that does nothing.

dynamic-extent-arglist
  (NOT evaluated.) If true, declare the argument list of the advised 
function with dynamic-extent.

The macro CCL:UNADVISE removes advice from a function.  The argument 
list is::

  (function &key when name)

These arguments have the same meaning as in ADVISE, except that if 
FUNCTION is T, UNADVISE removes all advice on all functions.  Otherwise, 
it removes all advice on FUNCTION.  If WHEN is specified, only return 
advice for which that value of WHEN was given; NAME is analogous.

Examples::

  (ccl:advise foo (print "about to call FOO"))
  (ccl:advise current-height (+ 5 (:do-it)) :when :around)


Tim Bradshaw wrote:
> I just discovered ADVISE & friends, which I failed to find any  
> documentation for - am I not looking in the right place or is there  
> none (I tried manual & wiki)?  If there isn't any, does anyone have  
> any non-trivial examples of using it so I can avoid poring over the  
> source too much.
>
> [Note this is not a complaint about lack of documentation: given I'm  
> neither paying nor contributing I'm very happy with anything I get.]
>
> --tim
>
>
> _______________________________________________
> Openmcl-devel mailing list
> Openmcl-devel at clozure.com
> http://clozure.com/mailman/listinfo/openmcl-devel
>