The cl-advice Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

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.


Next: , Previous: , Up: Top   [Contents][Index]

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


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

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

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-advice.asd

Location

cl-advice.asd

Systems

cl-advice (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-advice/package.lisp

Parent

cl-advice (system)

Location

package.lisp

Packages

cl-advice


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-advice/cl-advice.lisp

Dependency

package.lisp (file)

Parent

cl-advice (system)

Location

cl-advice.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-advice

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Previous: , Up: Exported definitions   [Contents][Index]

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)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Classes

Class: advisable-function ()
Package

cl-advice

Source

cl-advice.lisp (file)

Direct superclasses

funcallable-standard-object (class)

Direct methods
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)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-advice.asd: The cl-advice․asd file
cl-advice/cl-advice.lisp: The cl-advice/cl-advice․lisp file
cl-advice/package.lisp: The cl-advice/package․lisp file

F
File, Lisp, cl-advice.asd: The cl-advice․asd file
File, Lisp, cl-advice/cl-advice.lisp: The cl-advice/cl-advice․lisp file
File, Lisp, cl-advice/package.lisp: The cl-advice/package․lisp file

L
Lisp File, cl-advice.asd: The cl-advice․asd file
Lisp File, cl-advice/cl-advice.lisp: The cl-advice/cl-advice․lisp file
Lisp File, cl-advice/package.lisp: The cl-advice/package․lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
A   C   D   E   F   G   L   M   R   W  
Index Entry  Section

(
(setf advisable-function-after): Internal generic functions
(setf advisable-function-after): Internal generic functions
(setf advisable-function-arguments): Internal generic functions
(setf advisable-function-arguments): Internal generic functions
(setf advisable-function-around): Internal generic functions
(setf advisable-function-around): Internal generic functions
(setf advisable-function-before): Internal generic functions
(setf advisable-function-before): Internal generic functions
(setf advisable-function-main): Internal generic functions
(setf advisable-function-main): Internal generic functions

A
add-advice: Exported functions
add-advice-after: Internal functions
add-advice-around: Internal functions
add-advice-before: Internal functions
advisable-function-after: Internal generic functions
advisable-function-after: Internal generic functions
advisable-function-arguments: Internal generic functions
advisable-function-arguments: Internal generic functions
advisable-function-around: Internal generic functions
advisable-function-around: Internal generic functions
advisable-function-before: Internal generic functions
advisable-function-before: Internal generic functions
advisable-function-main: Internal generic functions
advisable-function-main: Internal generic functions
advisable-function-p: Exported functions
advisable-lambda: Exported macros
apply-after: Internal functions
apply-around: Internal functions
apply-before: Internal functions
argument-list-to-apply-list: Internal functions

C
convert-to-advisable: Internal macros
copy-advice: Internal functions

D
define-advisory-functions: Exported macros
defun-advisable: Exported macros

E
ensure-advisable-function: Internal functions

F
flatten: Internal functions
Function, add-advice: Exported functions
Function, add-advice-after: Internal functions
Function, add-advice-around: Internal functions
Function, add-advice-before: Internal functions
Function, advisable-function-p: Exported functions
Function, apply-after: Internal functions
Function, apply-around: Internal functions
Function, apply-before: Internal functions
Function, argument-list-to-apply-list: Internal functions
Function, copy-advice: Internal functions
Function, ensure-advisable-function: Internal functions
Function, flatten: Internal functions
Function, generate-around-caller: Internal functions
Function, generate-ignore-declarations: Internal functions
Function, list-advice: Exported functions
Function, make-advisable-function: Internal functions
Function, make-unadvisable: Exported functions
Function, remove-advice: Exported functions
Function, remove-advice-all: Internal functions
Function, remove-advice-if: Internal functions
Function, remove-advice-if-not: Internal functions
Function, remove-after-advice-if: Internal functions
Function, remove-after-advice-if-not: Internal functions
Function, remove-around-advice-if: Internal functions
Function, remove-around-advice-if-not: Internal functions
Function, remove-before-advice-if: Internal functions
Function, remove-before-advice-if-not: Internal functions
Function, remove-nth: Internal functions
Function, remove-nth-advice: Exported functions
Function, remove-nth-advice-after: Internal functions
Function, remove-nth-advice-around: Internal functions
Function, remove-nth-advice-before: Internal functions
Function, replace-advice: Exported functions
Function, replace-advice-after: Internal functions
Function, replace-advice-around: Internal functions
Function, replace-advice-before: Internal functions

G
generate-around-caller: Internal functions
generate-ignore-declarations: Internal functions
Generic Function, (setf advisable-function-after): Internal generic functions
Generic Function, (setf advisable-function-arguments): Internal generic functions
Generic Function, (setf advisable-function-around): Internal generic functions
Generic Function, (setf advisable-function-before): Internal generic functions
Generic Function, (setf advisable-function-main): Internal generic functions
Generic Function, advisable-function-after: Internal generic functions
Generic Function, advisable-function-arguments: Internal generic functions
Generic Function, advisable-function-around: Internal generic functions
Generic Function, advisable-function-before: Internal generic functions
Generic Function, advisable-function-main: Internal generic functions

L
list-advice: Exported functions

M
Macro, advisable-lambda: Exported macros
Macro, convert-to-advisable: Internal macros
Macro, define-advisory-functions: Exported macros
Macro, defun-advisable: Exported macros
Macro, make-advisable: Exported macros
Macro, make-install-advisable-function-dispatcher: Internal macros
Macro, when-let1: Internal macros
Macro, with-gensyms: Internal macros
make-advisable: Exported macros
make-advisable-function: Internal functions
make-install-advisable-function-dispatcher: Internal macros
make-unadvisable: Exported functions
Method, (setf advisable-function-after): Internal generic functions
Method, (setf advisable-function-arguments): Internal generic functions
Method, (setf advisable-function-around): Internal generic functions
Method, (setf advisable-function-before): Internal generic functions
Method, (setf advisable-function-main): Internal generic functions
Method, advisable-function-after: Internal generic functions
Method, advisable-function-arguments: Internal generic functions
Method, advisable-function-around: Internal generic functions
Method, advisable-function-before: Internal generic functions
Method, advisable-function-main: Internal generic functions

R
remove-advice: Exported functions
remove-advice-all: Internal functions
remove-advice-if: Internal functions
remove-advice-if-not: Internal functions
remove-after-advice-if: Internal functions
remove-after-advice-if-not: Internal functions
remove-around-advice-if: Internal functions
remove-around-advice-if-not: Internal functions
remove-before-advice-if: Internal functions
remove-before-advice-if-not: Internal functions
remove-nth: Internal functions
remove-nth-advice: Exported functions
remove-nth-advice-after: Internal functions
remove-nth-advice-around: Internal functions
remove-nth-advice-before: Internal functions
replace-advice: Exported functions
replace-advice-after: Internal functions
replace-advice-around: Internal functions
replace-advice-before: Internal functions

W
when-let1: Internal macros
with-gensyms: Internal macros

Jump to:   (  
A   C   D   E   F   G   L   M   R   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   A   B   M   S  
Index Entry  Section

A
after: Internal classes
arglist: Internal classes
around: Internal classes

B
before: Internal classes

M
main: Internal classes

S
Slot, after: Internal classes
Slot, arglist: Internal classes
Slot, around: Internal classes
Slot, before: Internal classes
Slot, main: Internal classes

Jump to:   A   B   M   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   A   C   P   S  
Index Entry  Section

A
advisable-function: Internal classes

C
cl-advice: The cl-advice system
cl-advice: The cl-advice package
Class, advisable-function: Internal classes

P
Package, cl-advice: The cl-advice package

S
System, cl-advice: The cl-advice system

Jump to:   A   C   P   S