The cl-advice Reference Manual

Table of Contents

The cl-advice Reference Manual

This is the cl-advice Reference Manual, version 0.0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 03:32:58 2022 GMT+0.

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=.

** 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

2 Systems

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

2.1 cl-advice

Author

szos at posteo dot net

License

LGPL

Description

Portable advice for Common Lisp

Version

0.0.1

Dependency

closer-mop

Source

cl-advice.asd (file)

Components

• package.lisp (file)
• cl-advice.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 cl-advice.asd

Location

cl-advice.asd

Systems

cl-advice (system)

3.1.2 cl-advice/package.lisp

Parent

cl-advice (system)

Location

package.lisp

Packages

cl-advice

3.1.3 cl-advice/cl-advice.lisp

Dependency

package.lisp (file)

Parent

cl-advice (system)

Location

cl-advice.lisp

Exported Definitions

• add-advice (function)
• advisable-function-p (function)
• advisable-lambda (macro)
• define-advisory-functions (macro)
• defun-advisable (macro)
• list-advice (function)
• make-advisable (macro)
• make-unadvisable (function)
• remove-advice (function)
• remove-nth-advice (function)
• replace-advice (function)

Internal Definitions

• add-advice-after (function)
• add-advice-around (function)
• add-advice-before (function)
• advisable-function (class)
• advisable-function-after (method)
• (setf advisable-function-after) (method)
• advisable-function-arguments (method)
• (setf advisable-function-arguments) (method)
• advisable-function-around (method)
• (setf advisable-function-around) (method)
• advisable-function-before (method)
• (setf advisable-function-before) (method)
• advisable-function-main (method)
• (setf advisable-function-main) (method)
• apply-after (function)
• apply-around (function)
• apply-before (function)
• argument-list-to-apply-list (function)
• convert-to-advisable (macro)
• copy-advice (function)
• ensure-advisable-function (function)
• flatten (function)
• generate-around-caller (function)
• generate-ignore-declarations (function)
• make-advisable-function (function)
• make-install-advisable-function-dispatcher (macro)
• remove-advice-all (function)
• remove-advice-if (function)
• remove-advice-if-not (function)
• remove-after-advice-if (function)
• remove-after-advice-if-not (function)
• remove-around-advice-if (function)
• remove-around-advice-if-not (function)
• remove-before-advice-if (function)
• remove-before-advice-if-not (function)
• remove-nth (function)
• remove-nth-advice-after (function)
• remove-nth-advice-around (function)
• remove-nth-advice-before (function)
• replace-advice-after (function)
• replace-advice-around (function)
• replace-advice-before (function)
• when-let1 (macro)
• with-gensyms (macro)

4 Packages

Packages are listed by definition order.

4.1 cl-advice

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• add-advice (function)
• advisable-function-p (function)
• advisable-lambda (macro)
• define-advisory-functions (macro)
• defun-advisable (macro)
• list-advice (function)
• make-advisable (macro)
• make-unadvisable (function)
• remove-advice (function)
• remove-nth-advice (function)
• replace-advice (function)

Internal Definitions

• add-advice-after (function)
• add-advice-around (function)
• add-advice-before (function)
• advisable-function (class)
• advisable-function-after (generic function)
• advisable-function-after (method)
• (setf advisable-function-after) (method)
• (setf advisable-function-after) (generic function)
• advisable-function-arguments (generic function)
• advisable-function-arguments (method)
• (setf advisable-function-arguments) (method)
• (setf advisable-function-arguments) (generic function)
• advisable-function-around (generic function)
• advisable-function-around (method)
• (setf advisable-function-around) (method)
• (setf advisable-function-around) (generic function)
• advisable-function-before (generic function)
• advisable-function-before (method)
• (setf advisable-function-before) (method)
• (setf advisable-function-before) (generic function)
• advisable-function-main (generic function)
• advisable-function-main (method)
• (setf advisable-function-main) (method)
• (setf advisable-function-main) (generic function)
• apply-after (function)
• apply-around (function)
• apply-before (function)
• argument-list-to-apply-list (function)
• convert-to-advisable (macro)
• copy-advice (function)
• ensure-advisable-function (function)
• flatten (function)
• generate-around-caller (function)
• generate-ignore-declarations (function)
• make-advisable-function (function)
• make-install-advisable-function-dispatcher (macro)
• remove-advice-all (function)
• remove-advice-if (function)
• remove-advice-if-not (function)
• remove-after-advice-if (function)
• remove-after-advice-if-not (function)
• remove-around-advice-if (function)
• remove-around-advice-if-not (function)
• remove-before-advice-if (function)
• remove-before-advice-if-not (function)
• remove-nth (function)
• remove-nth-advice-after (function)
• remove-nth-advice-around (function)
• remove-nth-advice-before (function)
• replace-advice-after (function)
• replace-advice-around (function)
• replace-advice-before (function)
• when-let1 (macro)
• with-gensyms (macro)

5 Definitions

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

5.1 Exported definitions

5.1.1 Macros

Macro: advisable-lambda ARGSLIST &body BODY

Return an advisable function object

Package

cl-advice

Source

cl-advice.lisp (file)

Macro: define-advisory-functions (TO-ADVISE &key NEXT-ARG) ARGS &body ADVICE

Define advisable functions and add them to TO-ADVISE.

Package

cl-advice

Source

cl-advice.lisp (file)

Macro: defun-advisable NAME ARGSLIST &body BODY

Define a function as an advisable function - works the same as DEFUN.

Package

cl-advice

Source

cl-advice.lisp (file)

Macro: make-advisable SYMBOL &optional ARGSLIST

Take a quoted symbol and convert the function denoted by it to an advisable function. If argslist is provided, it must match the symbols functions argument list. if argslist is nil, a single &rest argument will be used.

Package

cl-advice

Source

cl-advice.lisp (file)

5.1.2 Functions

Function: add-advice WHERE FUNCTION ADVICE-FUNCTION &key ALLOW-DUPLICATES TEST FROM-END

Add ADVICE-FUNCTION to FUNCTION. WHERE must be one of :before, :around, or :after. If ALLOW-DUPLICATES is true, advice will be added regardless. TEST is used to check if ADVICE-FUNCTION is already present. When FROM-END is true, advice will be appended instead of prepended.

Package

cl-advice

Source

cl-advice.lisp (file)

Function: advisable-function-p OBJECT

Check if OBJECT is an advisable function

Package

cl-advice

Source

cl-advice.lisp (file)

Function: list-advice FN &key TYPE PRINT

List advice for FN, of type TYPE. When PRINT is true, advice will be printed to standard output.

Package

cl-advice

Source

cl-advice.lisp (file)

Function: make-unadvisable SYMBOL

Package

cl-advice

Source

cl-advice.lisp (file)

Function: remove-advice TYPE FN ADVICE &key TEST

Package

cl-advice

Source

cl-advice.lisp (file)

Function: remove-nth-advice TYPE FN NTH

Remove NTH advice advice from FNs advice list of type TYPE.

Package

cl-advice

Source

cl-advice.lisp (file)

Function: replace-advice WHERE FUNCTION OLD-ADVICE NEW-ADVICE &key TEST IF-NOT-FOUND

Replace OLD-ADVICE with NEW-ADVICE in the advice list for FUNCTION denoted by WHERE. TEST is used to find OLD-ADVICE. IF-NOT-FOUND dictates what to do in the event OLD-ADVICE is not present. It may be one of :prepend, :append, or nil.

Package

cl-advice

Source

cl-advice.lisp (file)

5.2 Internal definitions

5.2.1 Macros

Macro: convert-to-advisable SYMBOL &optional ARGLIST

Package

cl-advice

Source

cl-advice.lisp (file)

Macro: make-install-advisable-function-dispatcher ARGSLIST MAINFN

Package

cl-advice

Source

cl-advice.lisp (file)

Macro: when-let1 (VAR FORM) &body BODY

Package

cl-advice

Source

cl-advice.lisp (file)

Macro: with-gensyms SYMS &body BODY

Package

cl-advice

Source

cl-advice.lisp (file)

5.2.2 Functions

Function: add-advice-after FUNCTION ADVICE-FN &key ALLOW-DUPLICATES TEST FROM-END

Package

cl-advice

Source

cl-advice.lisp (file)

Function: add-advice-around FUNCTION ADVICE-FN &key ALLOW-DUPLICATES TEST FROM-END

Package

cl-advice

Source

cl-advice.lisp (file)

Function: add-advice-before FUNCTION ADVICE-FN &key ALLOW-DUPLICATES TEST FROM-END

Package

cl-advice

Source

cl-advice.lisp (file)

Function: apply-after OBJ ARGS

Package

cl-advice

Source

cl-advice.lisp (file)

Function: apply-around OBJ ARGS

Package

cl-advice

Source

cl-advice.lisp (file)

Function: apply-before OBJ ARGS

Package

cl-advice

Source

cl-advice.lisp (file)

Function: argument-list-to-apply-list ARGSLIST

This function is for use a macroexpansion time. It takes an ordinary lambda list and parses it into code to generate a list suitable for use with apply

Package

cl-advice

Source

cl-advice.lisp (file)

Function: copy-advice FN1 FN2

DESTRUCTIVELY Copy all advice from FN1 to FN2

Package

cl-advice

Source

cl-advice.lisp (file)

Function: ensure-advisable-function FN

Package

cl-advice

Source

cl-advice.lisp (file)

Function: flatten L

Package

cl-advice

Source

cl-advice.lisp (file)

Function: generate-around-caller FUNCTION-LIST

Package

cl-advice

Source

cl-advice.lisp (file)

Function: generate-ignore-declarations ARGUMENT-LIST

Package

cl-advice

Source

cl-advice.lisp (file)

Function: make-advisable-function FUNCTION &rest INITARGS

Package

cl-advice

Source

cl-advice.lisp (file)

Function: remove-advice-all FN

Package

cl-advice

Source

cl-advice.lisp (file)

Function: remove-advice-if PREDICATE TYPE FUNCTION &key FROM-END START END

Package

cl-advice

Source

cl-advice.lisp (file)

Function: remove-advice-if-not PREDICATE TYPE FUNCTION &key FROM-END START END

Package

cl-advice

Source

cl-advice.lisp (file)

Function: remove-after-advice-if PREDICATE FUNCTION FROM-END START END

Package

cl-advice

Source

cl-advice.lisp (file)

Function: remove-after-advice-if-not PREDICATE FUNCTION FROM-END START END

Package

cl-advice

Source

cl-advice.lisp (file)

Function: remove-around-advice-if PREDICATE FUNCTION FROM-END START END

Package

cl-advice

Source

cl-advice.lisp (file)

Function: remove-around-advice-if-not PREDICATE FUNCTION FROM-END START END

Package

cl-advice

Source

cl-advice.lisp (file)

Function: remove-before-advice-if PREDICATE FUNCTION FROM-END START END

Package

cl-advice

Source

cl-advice.lisp (file)

Function: remove-before-advice-if-not PREDICATE FUNCTION FROM-END START END

Package

cl-advice

Source

cl-advice.lisp (file)

Function: remove-nth LIST NTH

Package

cl-advice

Source

cl-advice.lisp (file)

Function: remove-nth-advice-after FN NTH

Package

cl-advice

Source

cl-advice.lisp (file)

Function: remove-nth-advice-around FN NTH

Package

cl-advice

Source

cl-advice.lisp (file)

Function: remove-nth-advice-before FN NTH

Package

cl-advice

Source

cl-advice.lisp (file)

Function: replace-advice-after FUNCTION OLD-ADVICE NEW-ADVICE TEST IF-NOT-FOUND

Package

cl-advice

Source

cl-advice.lisp (file)

Function: replace-advice-around FUNCTION OLD-ADVICE NEW-ADVICE TEST IF-NOT-FOUND

Package

cl-advice

Source

cl-advice.lisp (file)

Function: replace-advice-before FUNCTION OLD-ADVICE NEW-ADVICE TEST IF-NOT-FOUND

Package

cl-advice

Source

cl-advice.lisp (file)

5.2.3 Generic functions

Generic Function: advisable-function-after OBJECT

Generic Function: (setf advisable-function-after) NEW-VALUE OBJECT

Package

cl-advice

Methods

Method: advisable-function-after (ADVISABLE-FUNCTION advisable-function)

automatically generated reader method

Source

cl-advice.lisp (file)

Method: (setf advisable-function-after) NEW-VALUE (ADVISABLE-FUNCTION advisable-function)

automatically generated writer method

Source

cl-advice.lisp (file)

Generic Function: advisable-function-arguments OBJECT

Generic Function: (setf advisable-function-arguments) NEW-VALUE OBJECT

Package

cl-advice

Methods

Method: advisable-function-arguments (ADVISABLE-FUNCTION advisable-function)

automatically generated reader method

Source

cl-advice.lisp (file)

Method: (setf advisable-function-arguments) NEW-VALUE (ADVISABLE-FUNCTION advisable-function)

automatically generated writer method

Source

cl-advice.lisp (file)

Generic Function: advisable-function-around OBJECT

Generic Function: (setf advisable-function-around) NEW-VALUE OBJECT

Package

cl-advice

Methods

Method: advisable-function-around (ADVISABLE-FUNCTION advisable-function)

automatically generated reader method

Source

cl-advice.lisp (file)

Method: (setf advisable-function-around) NEW-VALUE (ADVISABLE-FUNCTION advisable-function)

automatically generated writer method

Source

cl-advice.lisp (file)

Generic Function: advisable-function-before OBJECT

Generic Function: (setf advisable-function-before) NEW-VALUE OBJECT

Package

cl-advice

Methods

Method: advisable-function-before (ADVISABLE-FUNCTION advisable-function)

automatically generated reader method

Source

cl-advice.lisp (file)

Method: (setf advisable-function-before) NEW-VALUE (ADVISABLE-FUNCTION advisable-function)

automatically generated writer method

Source

cl-advice.lisp (file)

Generic Function: advisable-function-main OBJECT

Generic Function: (setf advisable-function-main) NEW-VALUE OBJECT

Package

cl-advice

Methods

Method: advisable-function-main (ADVISABLE-FUNCTION advisable-function)

automatically generated reader method

Source

cl-advice.lisp (file)

Method: (setf advisable-function-main) NEW-VALUE (ADVISABLE-FUNCTION advisable-function)

automatically generated writer method

Source

cl-advice.lisp (file)

5.2.4 Classes

Class: advisable-function ()

Package

cl-advice

Source

cl-advice.lisp (file)

Direct superclasses

funcallable-standard-object (class)

Direct methods

• advisable-function-after (method)
• advisable-function-after (method)
• advisable-function-around (method)
• advisable-function-around (method)
• advisable-function-before (method)
• advisable-function-before (method)
• advisable-function-main (method)
• advisable-function-main (method)
• advisable-function-arguments (method)
• advisable-function-arguments (method)

Direct slots

Slot: arglist

Initargs

:arguments

Readers

advisable-function-arguments (generic function)

Writers

(setf advisable-function-arguments) (generic function)

Slot: main

Initargs

:main

Readers

advisable-function-main (generic function)

Writers

(setf advisable-function-main) (generic function)

Slot: before

Initargs

:before

Readers

advisable-function-before (generic function)

Writers

(setf advisable-function-before) (generic function)

Slot: around

Initargs

:around

Readers

advisable-function-around (generic function)

Writers

(setf advisable-function-around) (generic function)

Slot: after

Initargs

:after

Readers

advisable-function-after (generic function)

Writers

(setf advisable-function-after) (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types