architecture.hooks

https://github.com/scymtym/architecture.hooks.git

git clone 'https://github.com/scymtym/architecture.hooks.git'

(ql:quickload :architecture.hooks)
1

+TITLE: cl-hooks README

+AUTHOR: Jan Moringen

+EMAIL: jmoringe@techfak.uni-bielefeld.DE

In the Common LISP Object System (CLOS), a similar kind of extensibility is possible using the flexible multi-method dispatch mechanism. It may even seem that the concept of hooks does not provide any benefits over the possibilites of CLOS. However, there are some differences: + There can be only one method for each combination of specializers and qualifiers. As a result this kind of extension point cannot be used by multiple extensions independently. + Removing code previously attached via a :before, :after or :around method can be cumbersome. + There could be other or even multiple extension points besides :before and :after in a single method. + Attaching codes to individual objects using eql specializers can be cumbersome. + Introspection of code attached a particular extension point is cumbersome since this requires enumerating and inspecting the methods of a generic function. This library tries to complement some of these weaknesses of method-based extension-points via the concept of hooks.

There are several kinds of hooks defined in this library, but new kinds of hooks can easily be defined by adding methods to the generic functions =hook-handlers=, =(setf hook-handlers)=, =hook-combination=, =(setf hook-combination)=, =documentation= and =(setf documentation)=.

The following sections briefly discuss the three kinds of hooks that are currently defined in the library.

Mention documentation ** Variable Hooks The most straightforward approach to implementing a hook is to use a variable. The variable is used as followed + Symbol Name :: name of the hook + Symbol Value :: list of handlers currently attached to the hook + Symbol Documentation :: if no dedicated hook documentation is installed using =(setf (hook-documentation …) …)=, the documentation of the symbol as a variable is used

Consider the following example

+BEGIN_SRC lisp :session hooks :exports both :results output

(defvar my-hook nil “My hook is only run for educational purposes.”)

(hooks:add-to-hook 'my-hook (lambda (x) (format t “my-hook called with argument ~S~%” x)))

(hooks:run-hook 'my-hook 1)

+END_SRC

+BEGIN_SRC lisp :session hooks :exports both :results value verbatim

(documentation 'my-hook 'hooks::hook)

+END_SRC

** Internal Object Hooks Hooks can also live in other places like object slots:

+BEGIN_SRC lisp :session hooks :exports both :results output

(defclass my-class () ((my-hook :initarg :my-hook :type list :initform nil :documentation “This hook bla bla”)))

(defvar my-object (make-instance 'my-class))

(hooks:object-hook my-object 'my-hook)

+END_SRC

Operation on an intern object hook work in the usual way:

+BEGIN_SRC lisp :session hooks :exports both :results output

(hooks:add-to-hook (hooks:object-hook my-object 'my-hook) (lambda (x) (format t “my-hook called with argument ~S~%” x)))

(hooks:object-hook my-object 'my-hook)

+END_SRC

+BEGIN_SRC lisp :session hooks :exports both :results output

(format t “bla~%”) (hooks:run-hook (hooks:object-hook my-object 'my-hook) 1)

+END_SRC

For object internal hooks, the documentation of the backing slot is used as the hook's documentation:

+BEGIN_SRC lisp :session hooks :exports both :results value verbatim

(documentation (hooks:object-hook my-object 'my-hook) 'hooks::hook)

+END_SRC

** External Object Hooks Or outside of objects:

+BEGIN_SRC lisp :session hooks :exports both :results value

(defparameter external-hook (hooks:external-hook my-object 'my-external-hook))

external-hook

+END_SRC

We stored the hook object in a variable since we are going to use it in some other examples.

+BEGIN_SRC lisp :session hooks :exports both :results output

(hooks:add-to-hook external-hook (lambda (x) (format t “my-external-hook called with argument ~S~%” x)))

(hooks:run-hook external-hook 1)

+END_SRC

** Hook Combination Hook combination refers to the different possible way of constructing the resulting value of running a hook. While bearing a strong resemblance to method combination in CLOS namewise, hook combination is a much more restricted and less powerful concept.

The default hook combination is =progn=:

+BEGIN_SRC lisp :session hooks :exports both :results output

(hooks:hook-combination (hooks:external-hook my-object 'my-external-hook))

+END_SRC

=progn= hook combination means the final result is the return value of the handler run last: TODO

Let's set up the hook to test some other combinations

+BEGIN_SRC lisp :session hooks :exports both :results output

(hooks:clear-hook external-hook) (hooks:add-to-hook external-hook #‘(lambda (x) (mod x 5))) (hooks:add-to-hook external-hook #’(lambda (x) (- x)))

+END_SRC

(list (hooks:run-hook external-hook -3) (hooks:run-hook external-hook 1) (hooks:run-hook external-hook 7))

+END_SRC

(list (hooks:run-hook external-hook -3) (hooks:run-hook external-hook 1) (hooks:run-hook external-hook 7))

+END_SRC

Note: #+BEGIN_QUOTE Some functions can be used for hook combination, but will not work as expected in all cases. =max= is one such examples. Running a hook with =max= hook combination that does not have any handlers will result in an error because =max= cannot be called without any arguments (which is the result of calling zero handlers). #+END_QUOTE * Tracking State

+BEGIN_SRC lisp :session hooks :exports both :results output

(defmethod hooks:on-become-active :after ((hook t)) (format t “hook ~S is now active~%” hook))

(defmethod hooks:on-become-inactive :after ((hook t)) (format t “hook ~S is now inactive~%” hook))

(setf my-object (make-instance 'my-class))

(hooks:add-to-hook (hooks:object-hook my-object 'my-hook) (lambda (x)))

(setf (hooks:hook-handlers (hooks:object-hook my-object 'my-hook)) nil)

+END_SRC

Local Variables:

mode: org

End: