1 Introduction

#+TITLE: CL-ADVICE

A lightweight and portable system for advising functions in Common Lisp.

* Description
  ~CL-ADVICE~ implements a new function type which carries with it slots for
  before, around, and after advice. Functions can be defined as advisable,
  existing functions not within a locked package can be converted to advisable
  functions, and advisable functions can be converted to regular functions.

** Types of Advice
   Pieces of advice are functions which get called before, after, or around the
   main function. Generally speaking, its a good idea to define advice functions
   as named functions and add it as a symbol and not a function object. This
   makes removing advice easier, and allows the advised function to use the new
   definition should the advice function be recompiled. Additionally, while
   installing anonymous functions as advice is allowed, removing anonymous
   function advice requires knowing where in the advice list it lies, or holding
   a reference to the anonymous function object.
*** Before and After Advice
    Before and After advice must have an argument list that is compatible with
    the main function. Two argument lists are considered compatible if they can
    both be applied to the same arguments. These advice functions are looped
    through and called in order.
*** Around Advice
    Around advice must take the next function to be called as its first
    argument, and all following arguments must be compatible with the main
    functions argument list. Around advice is unique in that it has control over
    whether or not the next function will be called. The next function may be
    the main function, or the next piece of around advice.
    
* Usage
  This system is used primarily through the functions ~make-advisable~,
  ~defun-advisable~, ~add-advice~, ~replace-advice~, and ~remove-advice~. For
  more information, see the docstrings of the functions and macros exported in
  =package.lisp=.

** Making Functions Advisable
   When making functions advisable, the original function object is wrapped in a
   funcallable object which has a dispatch function as its main function. This
   conversion is done through the function ~make-advisable~. By default,
   functions are converted to be advisable implicitly, through the function
   ~ensure-advisable-function~. This is controlled by the dynamic variable
   ~*allow-implicit-conversion*~, and can be enabled or disabled for a body of
   code through the macro ~with-implicit-conversion~. If conversion

*** ~MAKE-ADVISABLE~
    This function creates an advisable function object and, if the function to
    make advisable is a symbol, rebinds the symbol-function to this new
    function. In addition it defines a dispatcher function for the advisable
    function object. 
    
    When defining the dispatch function all care will be taken to preserve the
    original argument list, however this isnt guaranteed. The function
    ~make-advisable~ has a compiler macro defined for it which will define the
    dispatcher function with correct arguments if they are provided. However a
    compiler macro may not always be called. For this reason the argument
    ~force-use-arguments~ is provided which forces generation of a dispach
    function with the correct argument list by using ~eval~.
    
** Redefining functions
   The macro ~defun-advisable~ copies existing advice if and only if the
   function has the same argument list (as compared by ~equal~).

** Example: ~TRACE~
   We can implement ~trace~ in terms of ~:around~ advice like so:
#+BEGIN_SRC lisp
  (defpackage :tracer
    (:use :cl :cl-advice))

  (in-package :tracer)

  (defun make-simple-tracer (&optional (sym 'unknown-function))
    (let ((inc 0))
      (lambda (next-fn &rest args)
        (let ((string (make-string inc :initial-element #\space)))
          (format t "~&~A~A: Calling ~A with arguments ~A~%"
                  string inc sym args)
          (incf inc)
          (let ((result (apply next-fn args)))
            (decf inc)
            (format t "~&~A~A: ~A returned ~A~%"
                    string inc sym result)
            result)))))

  (defun-advisable fib (n)
    (if (< n 2)
        n
        (+ (fib (- n 1)) (fib (- n 2)))))

  (add-advice :around 'fib (make-simple-tracer 'fib))
#+END_SRC

   The result of this is that when ~fib~ is called, the following will be
   printed to standard output:
#+BEGIN_SRC lisp
  TRACER> (fib 1)
   0: Calling FIB with arguments (1)
   0: FIB returned 1
  1
  TRACER> (fib 5)
   0: Calling FIB with arguments (5)
    1: Calling FIB with arguments (4)
     2: Calling FIB with arguments (3)
      3: Calling FIB with arguments (2)
       4: Calling FIB with arguments (1)
       4: FIB returned 1
       4: Calling FIB with arguments (0)
       4: FIB returned 0
      3: FIB returned 1
      3: Calling FIB with arguments (1)
      3: FIB returned 1
     2: FIB returned 2
     2: Calling FIB with arguments (2)
      3: Calling FIB with arguments (1)
      3: FIB returned 1
      3: Calling FIB with arguments (0)
      3: FIB returned 0
     2: FIB returned 1
    1: FIB returned 3
    1: Calling FIB with arguments (3)
     2: Calling FIB with arguments (2)
      3: Calling FIB with arguments (1)
      3: FIB returned 1
      3: Calling FIB with arguments (0)
      3: FIB returned 0
     2: FIB returned 1
     2: Calling FIB with arguments (1)
     2: FIB returned 1
    1: FIB returned 2
   0: FIB returned 5
  5 (3 bits, #x5, #o5, #b101)
#+END_SRC

* Documentation
  
** Function ~ADVISABLE-FUNCTION-P~
   *advisable-function-p* /function/

   Returns T if /function/ is an advisable function. 
   
   - Arguments and Values
     - /function/ - a object

** Function ~MAKE-ADVISABLE~
   *make-advisable* /symbol/ &key /arguments force-use-arguments/

   Converts a function to an advisable function. If /symbol/ is a symbol, then
   the function denoted by it is converted and the ~symbol-function~ of /symbol/
   is set to the new advisable function. If /symbol/ is a function object it is
   converted to an advisable function and returned.

   When /arguments/ is provided and the call is being compiled, a compiler macro
   will generate a dispatcher function with this argument list. If the call is
   not being compiled or the compiler macro is not triggered then a generic
   dispatcher argument list is used.

   When /force-use-arguments/ is T and the compiler macro is not triggered,
   ~eval~ is used to generate a dispatcher function that uses /arguments/ for
   its argument list. 

   - Arguments and Values
     - /symbol/ - a symbol denoting a function or a function object
     - /arguments/ - the argument list of /symbol/
     - /force-use-arguments/ - When T force the usage of /arguments/ for the
       advisable function dispatcher function. 

** Function ~MAKE-UNADVISABLE~
   *make-unadvisable* /symbol/

   Convert an advisable function to be unadvisable. If /symbol/ is a symbol then
   the function referred to by /symbol/ is converted to be unadvisable and
   /symbol/ has its ~symbol-function~ rebound to this function. If /symbol/ is a
   function object the unadvisable function is returned.

   - Arguments and Values
     - /symbol/ - a symbol or function to convert to be unadvisable

** Function ~ENSURE-ADVISABLE-FUNCTION~
   *ensure-advisable-function* /symbol/ &optional /arguments force-use-arguments/

   Returns an advisable function or signals an error. If /symbol/ denotes an
   unadvisable function and ~*allow-implicit-conversion*~ is T then /symbol/ is
   converted via ~make-advisable~. If ~*allow-implicit-conversion*~ is NIL, then
   an error of type ~implicit-conversion-to-advisable-function~ is signalled
   with two restarts established around it. These restarts are ~allow-conversion~,
   which converts the function, and ~return-value~, which takes a value to
   return. When called interactively the return-value restart reads and
   evaluates a value from the user.

   When implicitly converting a function to be advisable, /arguments/ and
   /force-use-arguments/ are passed to ~make-advisable~.

   - Arguments and Values
     - /symbol/ - a symbol or function object
     - /arguments/ - a argument list
     - /force-use-arguments/ - a true or false value

** Function ~ENSURE-UNADVISABLE-FUNCTION~
   *ensure-unadvisable-function* /symbol/

   Calls ~make-unadvisable~ on /symbol/ and return an unadvisable function.

   - Arguments and Values
     - /symbol/ - a symbol or function object 
   
** Macro ~WITH-IMPLICIT-CONVERSION~
   *with-implicit-conversion* (/allow-or-not/ &optional /abort-on-implicit-conversion return-on-abort/) &body /body/
   
   Binds the variable ~*allow-implicit-conversion*~ to T or NIL based upon
   whether /allow-or-not/ is ~eql~ to ~:allowed~, where /allow-or-not/ is
   evaluated at runtime. If /abort-on-implicit-conversion/ is true (at
   macroexpansion time) then if ~implicit-conversion-to-advisable-function~ is
   signalled then control leaves /body/ immediately, and /return-on-abort/ is
   returned.

** Macro ~ADVISABLE-LAMBDA~
   *advisable-lambda* /argslist/ &body /body/

   Functions the same as ~lambda~, but returns an advisable function object.

   - Arguments and Values
     - /argslist/ - a function argument list
     - /body/ - A function body

** Macro ~DEFUN-ADVISABLE~
   *defun-advisable* /name argslist/ &body /body/

   Functions the same as ~defun~ but defines an advisable function.
   
   - Arguments and Values
     - /name/ - an unquoted symbol denoting the name for the function
     - /argslist/ - a function argument list
     - /body/ - A function body   

** Dynamic Variable ~*ALLOW-IMPLICIT-CONVERSION*~
   Variable with the default value of T. When T, allow
   ~ensure-advisable-function~ to implicitly convert unadvisable functions to be
   advisable. When NIL, signal an error when attempting to implicitly convert an
   unadvisable function. 

** Function ~ADD-ADVICE~
   *add-advice* /where function advice-function/ &key /allow-duplicates test from-end/

   Advise /function/ with /advice-function/. If /allow-duplicates/ is NIL, test
   for duplicates using /test/.

   - Arguments and Values
     - /where/ - a keyword denoting the kind of advice /advice-function/
       is. Must be one of ~:before~, ~:after~, or ~:around~.
     - /function/ - a symbol or function object
     - /advice-function/ - the advice function to install.
     - /allow-duplicates/ - a true or false value. When true duplicate advice is
       allowed.
     - /test/ - a function to compare pieces of advice. Used when
       /allow-duplicates/ is NIL
     - /from-end/ - Determines where to add the advice in its appropriate advice
       list. When T add the advice at the end of the advice list, when NIL add
       it at the beginning. 

** Function ~REPLACE-ADVICE~
   *replace-advice* /where function old-advice new-advice/ &key /test if-not-found/

   Replace a piece of advice.

   - Arguments and Values
     - /where/ - a symbol denoting the type of advice to replace, one of
       ~:before~, ~:around~, or ~:after~
     - /function/ - the function to replace the advice for
     - /old-advice/ - the advice to replace
     - /new-advice/ - the advice to replace /old-advice/ with
     - /test/ - a function to compare advice
     - /if-not-found/ - A keyword denoting what to do if /old-advice/ isnt
       found. Must be one of ~:prepend~, ~:append~, or NIL. 

** Function ~LIST-ADVICE~
   *list-advice* /fn/ &key /type print/

   Lists advice for /fn/.

   - Arguments and Values
     - /fn/ - a function to print advice for
     - /type/ - a keyword denoting what kind of advice to list. Must be one of
       ~:all~, ~:before~, ~:around~, or ~:after~.
     - /print/ - when true print all advice to standard output.

** Function ~REMOVE-ADVICE~
   *remove-advice* /type fn advice/ &key /test/

   Remove /advice/ from /fn/.

   - Arguments and Values
     - /type/ - a keyword denoting which advice list to remove /advice/
       from. Must be one of ~:before~, ~:around~, or ~:after~.
     - /fn/ - a symbol or function object
     - /advice/ - the piece of advice to remove. Must be a symbol, function, or
       the keyword ~:all~. 
     - /test/ - a function to compare pieces of advice

** Function ~REMOVE-NTH-ADVICE~
   *remove-nth-advice* /type fn nth/

   Remove the /nth/ element of advice from /type/ advice list for /fn/. 

   - Arguments and Values
     - /type/ - a keyword denoting which advice list to remove the /nth/
       from. Must be one of ~:before~, ~:after~, or ~:around~.
     - /fn/ - the function to remove the advice from
     - /nth/ - the element to remove

2 Systems

The main system appears first, followed by any subsystem dependency.

• cl-advice

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

• Lisp

4 Packages

Packages are listed by definition order.

• cl-advice

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

• Public Interface
• Internals