The cl-hooks Reference Manual

Table of Contents

The cl-hooks Reference Manual

This is the cl-hooks Reference Manual, version 0.2.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 14:05:19 2021 GMT+0.

1 Introduction

#+TITLE:  cl-hooks README
#+AUTHOR: Jan Moringen
#+EMAIL:  jmoringe@techfak.uni-bielefeld.DE


* Prelude                                                          :noexport:
#+BEGIN_SRC lisp :session hooks
  (asdf:load-system :cl-hooks)
#+END_SRC
* Introduction
  A hook, in the present context, is a certain kind of [[http://wikipedia.org/wiki/Extension_point][extension point]]
  in a program that allows interleaving the execution of arbitrary
  code with the execution of a the program without introducing any
  coupling between the two. Hooks are used extensively in the
  extensible editor [[http://gnu.org/software/emacs][Emacs]].

  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.

  #+ATTR_HTML: :alt "build status image" :title Build Status :align right
  [[https://travis-ci.org/scymtym/architecture.hooks][https://travis-ci.org/scymtym/architecture.hooks.svg]]

* Hooks
** Definition
   A hook is an extension point consisting of
   + A name (a symbol or some form)
   + A list of handlers
   + ftype?
   + A result combination
   + A documentation string

   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
  + Combination using =list= ::
#+BEGIN_SRC lisp  :session hooks :exports both :results output verbatim
  (setf (hooks:hook-combination *external-hook*) #'list)

  (list
   (hooks:run-hook *external-hook* -3)
   (hooks:run-hook *external-hook* 1)
   (hooks:run-hook *external-hook* 7))
#+END_SRC
  + Combination using =max= ::
#+BEGIN_SRC lisp  :session hooks :exports both :results output verbatim
  (setf (hooks:hook-combination *external-hook*) #'max)

  (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
* Restarts
  This library uses restart to recover from errors during the
  execution of hooks or their handlers. This section briefly discusses
  the restarts that are installed at the hook and handler levels.
** Hook Restarts
   + =retry= :: When this restart is invoked, the hook is ran again.
   + =use-value= :: When this restart is invoked, the hook is not ran
        and a replacement value is read interactively and returned in
        place of the result of running the hook.
** Handler Restarts
   + =retry= :: When this restart is invoked, the handler is executed
        again.
   + =use-value= :: When this restart is invoked, the handler is not
        executed and a replacement value is read interactively and
        returned in place of the result of executing the handler.
   + =skip= :: When this restart is invoked, the handler is skipped
        without producing any return value. If there are other
        handlers, the hook may still produce a return value.
* Convenience Marcos
#+BEGIN_SRC lisp
  (hooks:with-handlers
      (((hooks:external-hook *my-object* 'my-hook)
        (lambda (x)))

       ((hooks:external-hook *my-object* 'my-other-hook)
        (lambda (y z))))
    (hooks:run-hook (hooks:external-hook *my-object* 'my-hook)))
#+END_SRC

* settings                                                         :noexport:
#+LATEX_CLASS: scrartcl

# Local Variables:
# mode: org
# End:

2 Systems

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

2.1 cl-hooks

Maintainer

Jan Moringen <jmoringe@techfak.uni-bielefeld.de>

Author

Jan Moringen <jmoringe@techfak.uni-bielefeld.de>

License

LLGPLv3

Description

This system provides the hooks extension point mechanism (as known, e.g., from GNU Emacs).

Version

0.2.1

Dependencies

• alexandria
• let-plus
• closer-mop
• trivial-garbage

Source

cl-hooks.asd (file)

Component

src/early (module)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 cl-hooks/src/early

Parent

cl-hooks (system)

Location

src/

Components

• package.lisp (file)
• conditions.lisp (file)
• protocol.lisp (file)
• util.lisp (file)
• hook.lisp (file)
• state.lisp (file)
• mixins.lisp (file)
• symbol.lisp (file)
• object-internal.lisp (file)
• object-external.lisp (file)
• macros.lisp (file)

4 Files

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

4.1 Lisp

4.1.1 cl-hooks.asd

Location

cl-hooks.asd

Systems

cl-hooks (system)

4.1.2 cl-hooks/src/early/package.lisp

Parent

src/early (module)

Location

src/package.lisp

Packages

hooks

4.1.3 cl-hooks/src/early/conditions.lisp

Dependency

package.lisp (file)

Parent

src/early (module)

Location

src/conditions.lisp

Exported Definitions

• duplicate-handler (condition)
• hook-error-handler (method)
• hook-error-hook (method)
• hook-error-mixin (condition)
• malformed-handler-binding (condition)
• malformed-handler-binding-binding (method)
• no-such-hook (condition)

4.1.4 cl-hooks/src/early/protocol.lisp

Dependency

conditions.lisp (file)

Parent

src/early (module)

Location

src/protocol.lisp

Exported Definitions

• add-to-hook (generic function)
• clear-hook (generic function)
• combine-results (generic function)
• hook-combination (generic function)
• (setf hook-combination) (generic function)
• hook-handlers (generic function)
• (setf hook-handlers) (generic function)
• hook-name (generic function)
• remove-from-hook (generic function)
• run-hook (generic function)

4.1.5 cl-hooks/src/early/util.lisp

Dependency

protocol.lisp (file)

Parent

src/early (module)

Location

src/util.lisp

Internal Definitions

• read-value (function)
• run-handler-without-restarts (function)
• signal-with-hook-and-handler-restarts (function)

4.1.6 cl-hooks/src/early/hook.lisp

Dependency

util.lisp (file)

Parent

src/early (module)

Location

src/hook.lisp

Exported Definitions

• add-to-hook (method)
• clear-hook (method)
• combine-results (method)
• combine-results (method)
• hook-combination (method)
• remove-from-hook (method)
• run-hook (method)
• run-hook-fast (function)

4.1.7 cl-hooks/src/early/state.lisp

Dependency

hook.lisp (file)

Parent

src/early (module)

Location

src/state.lisp

Exported Definitions

• (setf hook-handlers) (method)
• on-become-active (generic function)
• on-become-active (method)
• on-become-inactive (generic function)
• on-become-inactive (method)

4.1.8 cl-hooks/src/early/mixins.lisp

Dependency

state.lisp (file)

Parent

src/early (module)

Location

src/mixins.lisp

Exported Definitions

• hook-combination (method)
• (setf hook-combination) (method)
• hook-handlers (method)
• (setf hook-handlers) (method)
• on-become-active (method)
• on-become-inactive (method)

Internal Definitions

• activatable-mixin (class)
• internal-combination-mixin (class)
• internal-documentation-mixin (class)
• internal-handlers-mixin (class)
• simple-printing-mixin (class)

4.1.9 cl-hooks/src/early/symbol.lisp

Dependency

mixins.lisp (file)

Parent

src/early (module)

Location

src/symbol.lisp

Exported Definitions

• hook-combination (method)
• (setf hook-combination) (method)
• hook-handlers (method)
• hook-name (method)

4.1.10 cl-hooks/src/early/object-internal.lisp

Dependency

symbol.lisp (file)

Parent

src/early (module)

Location

src/object-internal.lisp

Exported Definitions

• hook-handlers (method)
• hook-name (method)
• hook-object (method)
• object-hook (generic function)
• object-hook (method)
• object-hook (class)

4.1.11 cl-hooks/src/early/object-external.lisp

Dependency

object-internal.lisp (file)

Parent

src/early (module)

Location

src/object-external.lisp

Exported Definitions

• external-hook (generic function)
• external-hook (method)
• external-hook (class)
• hook-name (method)

4.1.12 cl-hooks/src/early/macros.lisp

Dependency

object-external.lisp (file)

Parent

src/early (module)

Location

src/macros.lisp

Exported Definitions

• defhook (macro)
• define-external-hook-activation (macro)
• define-hook-activation (macro)
• define-hook-activation-method (macro)
• define-internal-hook-activation (macro)
• with-handlers (macro)

5 Packages

Packages are listed by definition order.

5.1 hooks

This package contains functions and classes which implement the "hook" extension point mechanism as known, for example, from GNU Emacs.

Hooks are first-class objects which can be inspected and modified via accessors:

+ ‘hook-name’
+ ‘hook-handlers’
+ ‘hook-combination’

+ ‘run-hook’

+ ‘add-to-hook’
+ ‘remove-from-hook’
+ ‘clear-hook’

The builtin kinds of hooks are the following

+ list of handlers as value of a symbol
+ list of handlers in an object slot
+ hook object is associated to arbitrary Lisp object

Source

package.lisp (file)

Use List

• let-plus
• alexandria
• common-lisp

Exported Definitions

• add-to-hook (generic function)
• add-to-hook (method)
• clear-hook (generic function)
• clear-hook (method)
• combine-results (generic function)
• combine-results (method)
• combine-results (method)
• defhook (macro)
• define-external-hook-activation (macro)
• define-hook-activation (macro)
• define-hook-activation-method (macro)
• define-internal-hook-activation (macro)
• duplicate-handler (condition)
• external-hook (generic function)
• external-hook (method)
• external-hook (class)
• hook-combination (generic function)
• hook-combination (method)
• (setf hook-combination) (method)
• hook-combination (method)
• (setf hook-combination) (method)
• hook-combination (method)
• (setf hook-combination) (generic function)
• hook-error-handler (generic function)
• hook-error-handler (method)
• hook-error-hook (generic function)
• hook-error-hook (method)
• hook-error-mixin (condition)
• hook-handlers (generic function)
• hook-handlers (method)
• hook-handlers (method)
• hook-handlers (method)
• (setf hook-handlers) (method)
• (setf hook-handlers) (generic function)
• (setf hook-handlers) (method)
• hook-name (generic function)
• hook-name (method)
• hook-name (method)
• hook-name (method)
• hook-object (generic function)
• hook-object (method)
• malformed-handler-binding (condition)
• malformed-handler-binding-binding (generic function)
• malformed-handler-binding-binding (method)
• no-such-hook (condition)
• object-hook (generic function)
• object-hook (method)
• object-hook (class)
• on-become-active (generic function)
• on-become-active (method)
• on-become-active (method)
• on-become-inactive (generic function)
• on-become-inactive (method)
• on-become-inactive (method)
• remove-from-hook (generic function)
• remove-from-hook (method)
• run-hook (generic function)
• run-hook (method)
• run-hook-fast (function)
• with-handlers (macro)

Internal Definitions

• activatable-mixin (class)
• internal-combination-mixin (class)
• internal-documentation-mixin (class)
• internal-handlers-mixin (class)
• read-value (function)
• run-handler-without-restarts (function)
• signal-with-hook-and-handler-restarts (function)
• simple-printing-mixin (class)

6 Definitions

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

6.1 Exported definitions

6.1.1 Macros

Macro: defhook HOOK &key COMBINATION DOCUMENTATION

Instantiate HOOK and set COMBINATION and DOCUMENTATION.

Package

hooks

Source

macros.lisp (file)

Macro: define-external-hook-activation (NAME &key (OBJECT OBJECT-VAR) (HOOK HOOK-VAR) CLASS) &body BODY

Execute BODY when the external hook named NAME becomes active. The keyword arguments object and hook can be used to name variables will be bound to the object and the hook object respectively during the execution of BODY.

Package

hooks

Source

macros.lisp (file)

Macro: define-hook-activation (HOOK &key (VAR HOOK-VAR)) ACTIVATE &optional DEACTIVATE

Execute [DE]ACTIVATE when HOOK becomes [in]active respectively. HOOK is a form that designates or retrieves a hook. Examples include a symbol designating a hook stored in that symbol or a form
like (object-hook OBJECT HOOK-SYMBOL).
Within the forms ACTIVATE and DEACTIVATE, the variable VAR (when specified) can be used to refer to the hook object (not HOOK, which is a form to retrieve the hook object).

Package

hooks

Source

macros.lisp (file)

Macro: define-hook-activation-method (HOOK &key (VAR HOOK-VAR)) &body BODY

When HOOK becomes active, execute BODY which has to return a method object. When HOOK becomes inactive, the method is removed. The keyword argument VAR can be used to specify the name of a variable to which the hook object will be bound during the execution of BODY.

Package

hooks

Source

macros.lisp (file)

Macro: define-internal-hook-activation (CLASS HOOK &key (INSTANCE INSTANCE-VAR) (HOOK HOOK-VAR)) ACTIVATE DEACTIVATE

Execute ACTIVATE when internal HOOK of an instance of CLASS becomes active and execute DEACTIVATE when such a hook becomes inactive. The keyword arguments INSTANCE and HOOK can be used to name variables that will be bound to the instance and the hook object respectively during the execution of ACTIVATE and DEACTIVATE.

Package

hooks

Source

macros.lisp (file)

Macro: with-handlers HOOKS-AND-HANDLERS &body BODY

Run BODY with handlers as specified in HOOKS-AND-HANDLERS. HOOKS-AND-HANDLERS is a list of items of the form (HOOK HANDLER) where HOOK is a hook and HANDLER is coercable to a function.

Example:
((with-handlers (((object-external object ’hook)
(lambda (args)
(format t "~S~%" args)))) (do-something))

Package

hooks

Source

macros.lisp (file)

6.1.2 Functions

Function: run-hook-fast ()

Run HOOK with ARGS like ‘run-hook’, with the following differences: + do not run any methods installed on ‘run-hook’
+ do not install any restarts
+ do not collect or combine any values returned by handlers.

Package

hooks

Source

hook.lisp (file)

6.1.3 Generic functions

Generic Function: add-to-hook HOOK HANDLER &key DUPLICATE-POLICY

Add HANDLER to HOOK.

Package

hooks

Source

protocol.lisp (file)

Methods

Method: add-to-hook HOOK (HANDLER function) &key DUPLICATE-POLICY

Source

hook.lisp (file)

Generic Function: clear-hook HOOK

Remove all handlers from HOOK.

Package

hooks

Source

protocol.lisp (file)

Methods

Method: clear-hook HOOK

Source

hook.lisp (file)

Generic Function: combine-results HOOK COMBINATION RESULTS

Combine RESULTS of running HOOK’s handlers according to COMBINATION.

Package

hooks

Source

protocol.lisp (file)

Methods

Method: combine-results HOOK (COMBINATION function) (RESULTS list)

Source

hook.lisp (file)

Method: combine-results HOOK (COMBINATION (eql progn)) (RESULTS list)

Source

hook.lisp (file)

Generic Function: external-hook OBJECT HOOK

Return a representation of the slot residing outside of OBJECT under the name HOOK.

Package

hooks

Source

object-external.lisp (file)

Methods

Method: external-hook OBJECT (HOOK symbol)

Generic Function: hook-combination HOOK

Return the hook combination used by HOOK.

Package

hooks

Source

protocol.lisp (file)

Writer

(setf hook-combination) (generic function)

Methods

Method: hook-combination (HOOK symbol)

Source

symbol.lisp (file)

Method: hook-combination (INTERNAL-COMBINATION-MIXIN internal-combination-mixin)

The hook combination used by this hook.

Source

mixins.lisp (file)

Method: hook-combination HOOK

Source

hook.lisp (file)

Generic Function: (setf hook-combination) NEW-VALUE HOOK

Install NEW-VALUE as the hook combination used by HOOK.

Package

hooks

Source

protocol.lisp (file)

Reader

hook-combination (generic function)

Methods

Method: (setf hook-combination) NEW-VALUE (HOOK symbol)

Source

symbol.lisp (file)

Method: (setf hook-combination) NEW-VALUE (INTERNAL-COMBINATION-MIXIN internal-combination-mixin)

The hook combination used by this hook.

Source

mixins.lisp (file)

Generic Function: hook-error-handler CONDITION

Package

hooks

Methods

Method: hook-error-handler (CONDITION duplicate-handler)

Source

conditions.lisp (file)

Generic Function: hook-error-hook CONDITION

Package

hooks

Methods

Method: hook-error-hook (CONDITION hook-error-mixin)

Source

conditions.lisp (file)

Generic Function: hook-handlers HOOK

Return a list of handlers attached to HOOK.

Package

hooks

Source

protocol.lisp (file)

Writer

(setf hook-handlers) (generic function)

Methods

Method: hook-handlers (HOOK object-hook)

Source

object-internal.lisp (file)

Method: hook-handlers (HOOK symbol)

Source

symbol.lisp (file)

Method: hook-handlers (INTERNAL-HANDLERS-MIXIN internal-handlers-mixin)

The list of handlers associated with this hook.

Source

mixins.lisp (file)

Generic Function: (setf hook-handlers) NEW-VALUE HOOK

Replace list of handlers attached to HOOK with NEW-VALUE.

Package

hooks

Source

protocol.lisp (file)

Reader

hook-handlers (generic function)

Methods

Method: (setf hook-handlers) NEW-VALUE (INTERNAL-HANDLERS-MIXIN internal-handlers-mixin)

The list of handlers associated with this hook.

Source

mixins.lisp (file)

Method: (setf hook-handlers) (NEW-VALUE list) HOOK around

Check whether HOOK becomes active or inactive.

Source

state.lisp (file)

Generic Function: hook-name HOOK

Return the name of HOOK (a symbol).

Package

hooks

Source

protocol.lisp (file)

Methods

Method: hook-name (EXTERNAL-HOOK external-hook)

The name of this hook.

Source

object-external.lisp (file)

Method: hook-name (OBJECT-HOOK object-hook)

The slot in which the hook resides.

Source

object-internal.lisp (file)

Method: hook-name (HOOK symbol)

Source

symbol.lisp (file)

Generic Function: hook-object OBJECT

Package

hooks

Methods

Method: hook-object (OBJECT-HOOK object-hook)

The object in which the hook resides.

Source

object-internal.lisp (file)

Generic Function: malformed-handler-binding-binding CONDITION

Package

hooks

Methods

Method: malformed-handler-binding-binding (CONDITION malformed-handler-binding)

Source

conditions.lisp (file)

Generic Function: object-hook OBJECT HOOK

Return a representation of the slot residing in OBJECT under the name HOOK.

Package

hooks

Source

object-internal.lisp (file)

Methods

Method: object-hook (OBJECT standard-object) (HOOK symbol)

Generic Function: on-become-active HOOK

Called when HOOK becomes active.

Package

hooks

Source

state.lisp (file)

Methods

Method: on-become-active (HOOK activatable-mixin)

If HOOK has a handler for becoming active installed, call that handler.

Source

mixins.lisp (file)

Method: on-become-active HOOK

Default behavior is to do nothing.

Generic Function: on-become-inactive HOOK

Called when HOOK becomes inactive.

Package

hooks

Source

state.lisp (file)

Methods

Method: on-become-inactive (HOOK activatable-mixin)

If HOOK has a handler for becoming inactive installed, call that handler.

Source

mixins.lisp (file)

Method: on-become-inactive HOOK

Default behavior is to do nothing.

Generic Function: remove-from-hook HOOK HANDLER

Remove HANDLER from HOOK.

Package

hooks

Source

protocol.lisp (file)

Methods

Method: remove-from-hook HOOK (HANDLER function)

Source

hook.lisp (file)

Generic Function: run-hook HOOK &rest ARGS

Run HOOK passing extra args ARGS to all handlers.

Package

hooks

Source

protocol.lisp (file)

Methods

Method: run-hook HOOK &rest ARGS

Source

hook.lisp (file)

6.1.4 Conditions

Condition: duplicate-handler ()

This condition is signaled if a handler is added to a hook to which it has been added before and the policy does not permit handlers to be added to a hook multiple times.

Package

hooks

Source

conditions.lisp (file)

Direct superclasses

hook-error-mixin (condition)

Direct methods

hook-error-handler (method)

Direct slots

Slot: handler

The handler which was added to the hook twice.

Initargs

:handler

Readers

hook-error-handler (generic function)

Direct Default Initargs

Initarg	Value
:handler	(alexandria:required-argument :handler)

Condition: hook-error-mixin ()

This condition servers as a superclass for condition classes that are related to hooks.

Package

hooks

Source

conditions.lisp (file)

Direct superclasses

error (condition)

Direct subclasses

• no-such-hook (condition)
• duplicate-handler (condition)

Direct methods

hook-error-hook (method)

Direct slots

Slot: hook

The hook object from which the error originated.

Initargs

:hook

Readers

hook-error-hook (generic function)

Direct Default Initargs

Initarg	Value
:hook	(alexandria:required-argument :hook)

Condition: malformed-handler-binding ()

This condition is signaled if an invalid hook-handler binding is detected during the expansion of an ‘with-handlers’ macro.

Package

hooks

Source

conditions.lisp (file)

Direct superclasses

error (condition)

Direct methods

malformed-handler-binding-binding (method)

Direct slots

Slot: binding

The invalid hook-handler binding.

Initargs

:binding

Readers

malformed-handler-binding-binding (generic function)

Direct Default Initargs

Initarg	Value
:binding	(alexandria:required-argument :binding)

Condition: no-such-hook ()

This condition is signaled when a designated hook cannot be found.

Package

hooks

Source

conditions.lisp (file)

Direct superclasses

hook-error-mixin (condition)

6.1.5 Classes

Class: external-hook ()

Instances of this class represent hooks that reside outside of objects.

Package

hooks

Source

object-external.lisp (file)

Direct superclasses

• activatable-mixin (class)
• simple-printing-mixin (class)
• internal-documentation-mixin (class)
• internal-handlers-mixin (class)
• internal-combination-mixin (class)

Direct methods

hook-name (method)

Direct slots

Slot: name

The name of this hook.

Type

symbol

Initargs

:name

Readers

hook-name (generic function)

Direct Default Initargs

Initarg	Value
:name	(alexandria:required-argument :name)

Class: object-hook ()

Instances of this class represent hooks that reside in object.

Package

hooks

Source

object-internal.lisp (file)

Direct superclasses

• activatable-mixin (class)
• simple-printing-mixin (class)
• internal-combination-mixin (class)

Direct methods

• documentation (method)
• documentation (method)
• hook-handlers (method)
• hook-handlers (method)
• hook-name (method)
• hook-object (method)

Direct slots

Slot: object

The object in which the hook resides.

Type

standard-object

Initargs

:object

Readers

hook-object (generic function)

Slot: slot

The slot in which the hook resides.

Type

symbol

Initargs

:slot

Readers

hook-name (generic function)

Direct Default Initargs

Initarg	Value
:object	(alexandria:required-argument :object)
:slot	(alexandria:required-argument :slot)

6.2 Internal definitions

6.2.1 Functions

Function: read-value ()

Read a replacement value.

Package

hooks

Source

util.lisp (file)

Function: run-handler-without-restarts ()

Run HANDLER with ARGS.

Package

hooks

Source

util.lisp (file)

Function: signal-with-hook-and-handler-restarts HOOK HANDLER CONDITION RETRY-HOOK USE-VALUE-FOR-HOOK RETRY-HANDLER SKIP-HANDLER USE-VALUE-FOR-HANDLER

Signal CONDITION with appropriate restarts installed.

The installed restarts for HANDLER are:
+ ‘retry’
+ ‘continue’
+ ‘use-value’

The installed restarts for HOOK are:
+ ‘retry’
+ ‘use-value’

Package

hooks

Source

util.lisp (file)

6.2.2 Classes

Class: activatable-mixin ()

This mixin adds slot to functions which run when the hook becomes active or inactive.

Package

hooks

Source

mixins.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• object-hook (class)
• external-hook (class)

Direct methods

• on-become-inactive (method)
• on-become-active (method)

Direct slots

Slot: on-become-active

If a function is stored in this slot, the function is called when the hook becomes active.

Type

(or null function)

Initargs

hooks:on-become-active

Slot: on-become-inactive

If a function is stored in this slot, the function is called when the hook becomes inactive.

Type

(or null function)

Initargs

hooks:on-become-inactive

Class: internal-combination-mixin ()

This mixin adds a slot which stores the hook combination of the hook.

Package

hooks

Source

mixins.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• object-hook (class)
• external-hook (class)

Direct methods

• hook-combination (method)
• hook-combination (method)

Direct slots

Slot: combination

The hook combination used by this hook.

Initargs

:combination

Initform

(quote progn)

Readers

hook-combination (generic function)

Writers

(setf hook-combination) (generic function)

Class: internal-documentation-mixin ()

This mixin adds a slot which stores the documentation of the hook.

Package

hooks

Source

mixins.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

external-hook (class)

Direct methods

• documentation (method)
• documentation (method)

Direct slots

Slot: documentation

Documentation string of the hook.

Type

(or null string)

Initargs

:documentation

Class: internal-handlers-mixin ()

This mixin adds a slot which stores the list of handlers of the hook.

Package

hooks

Source

mixins.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

external-hook (class)

Direct methods

• hook-handlers (method)
• hook-handlers (method)

Direct slots

Slot: handlers

The list of handlers associated with this hook.

Type

list

Initargs

:handlers

Initform

(quote nil)

Readers

hook-handlers (generic function)

Writers

(setf hook-handlers) (generic function)

Class: simple-printing-mixin ()

This mixin adds simple printing behavior for hooks.

Package

hooks

Source

mixins.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• object-hook (class)
• external-hook (class)

Direct methods

print-object (method)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types