architecture.hooks

API Reference

cl-hooks

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

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
  • Condition HOOK-ERROR-MIXIN  (ERROR)
    This condition servers as a superclass for condition classes that are related to hooks.
  • Condition NO-SUCH-HOOK  (HOOK-ERROR-MIXIN)
    This condition is signaled when a designated hook cannot be found.
  • Condition DUPLICATE-HANDLER  (HOOK-ERROR-MIXIN)
    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.
  • Condition MALFORMED-HANDLER-BINDING  (ERROR)
    This condition is signaled if an invalid hook-handler binding is detected during the expansion of an `with-handlers' macro.
  • Generic-Function HOOK-NAME (hook)
    Return the name of HOOK (a symbol).
  • Generic-Function HOOK-COMBINATION (hook)
    Return the hook combination used by HOOK.
  • Generic-Function (setf HOOK-COMBINATION) (new-value hook)
    Install NEW-VALUE as the hook combination used by HOOK.
  • Generic-Function HOOK-HANDLERS (hook)
    Return a list of handlers attached to HOOK.
  • Generic-Function (setf HOOK-HANDLERS) (new-value hook)
    Replace list of handlers attached to HOOK with NEW-VALUE.
  • Generic-Function ADD-TO-HOOK (hook handler &key duplicate-policy)
    Add HANDLER to HOOK.
  • Generic-Function REMOVE-FROM-HOOK (hook handler)
    Remove HANDLER from HOOK.
  • Generic-Function CLEAR-HOOK (hook)
    Remove all handlers from HOOK.
  • Generic-Function RUN-HOOK (hook &rest args)
    Run HOOK passing extra args ARGS to all handlers.
  • Generic-Function COMBINE-RESULTS (hook combination results)
    Combine RESULTS of running HOOK's handlers according to COMBINATION.
  • Method HOOK-COMBINATION ((hook t))
  • Method ADD-TO-HOOK ((hook t) (handler function) &key (duplicate-policy :replace))
  • Method REMOVE-FROM-HOOK ((hook t) (handler function))
  • Method CLEAR-HOOK ((hook t))
  • Method RUN-HOOK ((hook t) &rest args)
  • Function RUN-HOOK-FAST (hook &rest args)
    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.
  • Method COMBINE-RESULTS ((hook t) (combination (eql 'progn)) (results list))
  • Method COMBINE-RESULTS ((hook t) (combination function) (results list))
  • Generic-Function ON-BECOME-ACTIVE (hook)
    Called when HOOK becomes active.
  • Generic-Function ON-BECOME-INACTIVE (hook)
    Called when HOOK becomes inactive.
  • Method (setf HOOK-HANDLERS) ((new-value list) (hook t))
    Check whether HOOK becomes active or inactive.
  • Method ON-BECOME-ACTIVE ((hook t))
    Default behavior is to do nothing.
  • Method ON-BECOME-INACTIVE ((hook t))
    Default behavior is to do nothing.
  • Method ON-BECOME-ACTIVE ((hook activatable-mixin))
    If HOOK has a handler for becoming active installed, call that handler.
  • Method ON-BECOME-INACTIVE ((hook activatable-mixin))
    If HOOK has a handler for becoming inactive installed, call that handler.
  • Method HOOK-COMBINATION ((hook symbol))
  • Method (setf HOOK-COMBINATION) ((new-value t) (hook symbol))
  • Method HOOK-HANDLERS ((hook symbol))
  • Method (setf HOOK-HANDLERS) ((new-value list) (hook symbol))
  • Generic-Function OBJECT-HOOK (object hook)
    Return a representation of the slot residing in OBJECT under the name HOOK.
  • Class OBJECT-HOOK  (INTERNAL-COMBINATION-MIXIN, SIMPLE-PRINTING-MIXIN, ACTIVATABLE-MIXIN)
    Instances of this class represent hooks that reside in object.
    OBJECT   Reader: HOOK-OBJECT
    The object in which the hook resides.
    SLOT   Reader: HOOK-NAME
    The slot in which the hook resides.
  • Method HOOK-HANDLERS ((hook object-hook))
  • Method (setf HOOK-HANDLERS) ((new-value list) (hook object-hook))
  • Method OBJECT-HOOK ((object standard-object) (hook symbol))
  • Generic-Function EXTERNAL-HOOK (object hook)
    Return a representation of the slot residing outside of OBJECT under the name HOOK.
  • Class EXTERNAL-HOOK  (INTERNAL-COMBINATION-MIXIN, INTERNAL-HANDLERS-MIXIN, INTERNAL-DOCUMENTATION-MIXIN, SIMPLE-PRINTING-MIXIN, ACTIVATABLE-MIXIN)
    Instances of this class represent hooks that reside outside of objects.
    NAME   Reader: HOOK-NAME
    The name of this hook.
  • Method EXTERNAL-HOOK ((object t) (hook symbol))
  • Macro DEFHOOK (hook &key combination documentation)
    Instantiate HOOK and set COMBINATION and DOCUMENTATION.
  • Macro DEFINE-HOOK-ACTIVATION ((hook &key ((var hook-var) (gensym "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).
  • Macro DEFINE-HOOK-ACTIVATION-METHOD ((hook &key ((var hook-var) (gensym "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.
  • Macro DEFINE-INTERNAL-HOOK-ACTIVATION ((class hook &key ((instance instance-var) (gensym)) ((hook hook-var) (gensym))) 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.
  • Macro DEFINE-EXTERNAL-HOOK-ACTIVATION ((name &key ((object object-var) (gensym "object-var")) ((hook hook-var) (gensym "hook-var")) (class t)) &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.
  • 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))