Common Lisp Package: HOOKS

README:

FUNCTION

Public

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.

Private

READ-VALUE

Read a replacement value.

RUN-HANDLER-WITH-RESTARTS (HANDLER &REST ARGS)

Run HANDLER with ARGS after installing appropriate restarts. The installed restarts are: + retry + skip + use-value

RUN-HANDLER-WITHOUT-RESTARTS

Run HANDLER with ARGS.

MACRO

Public

DEFHOOK (HOOK &KEY COMBINATION DOCUMENTATION)

Instantiate HOOK and set COMBINATION and DOCUMENTATION.

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.

DEFINE-HOOK-ACTIVATION ((HOOK &KEY ((VAR HOOK-VAR) (GENSYM HOOK-VAR))) ACTIVATE 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).

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.

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.

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

Private

WITH-HOOK-RESTARTS (HOOK &BODY BODY)

Run BODY after installing restarts for HOOK. The installed restarts are: + retry + use-value

GENERIC-FUNCTION

Public

ADD-TO-HOOK (HOOK HANDLER &KEY DUPLICATE-POLICY (DUPLICATE-POLICY REPLACE))

Add HANDLER to HOOK.

CLEAR-HOOK (HOOK)

Remove all handlers from HOOK.

COMBINE-RESULTS (HOOK COMBINATION RESULTS)

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

EXTERNAL-HOOK (OBJECT HOOK)

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

OBJECT-HOOK (OBJECT HOOK)

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

ON-BECOME-ACTIVE (HOOK)

Called when HOOK becomes active.

ON-BECOME-INACTIVE (HOOK)

Called when HOOK becomes inactive.

REMOVE-FROM-HOOK (HOOK HANDLER)

Remove HANDLER from HOOK.

RUN-HOOK (HOOK &REST ARGS)

Run HOOK passing extra args ARGS to all handlers.

Private

Undocumented

HOOK-ERROR-HANDLER (CONDITION)

HOOK-ERROR-HOOK (CONDITION)

MALFORMED-HOOK-HANDLER-BINDING-BINDING (CONDITION)

SLOT-ACCESSOR

Public

HOOK-COMBINATION (HOOK)

The Return the hook combination used by HOOK.

SETFHOOK-COMBINATION (NEW-VALUE HOOK)

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

HOOK-HANDLERS (HOOK)

The Return a list of handlers attached to HOOK.

SETFHOOK-HANDLERS (NEW-VALUE HOOK)

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

HOOK-NAME (HOOK)

The Return the name of HOOK (a symbol).

CLASS

Public

EXTERNAL-HOOK (OBJECT HOOK)

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

OBJECT-HOOK (OBJECT HOOK)

Instances of this class represent hooks that reside in object.

Private

INTERNAL-COMBINATION-MIXIN

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

INTERNAL-DOCUMENTATION-MIXIN

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

INTERNAL-HANDLERS-MIXIN

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

SIMPLE-PRINTING-MIXIN

This mixin adds simple printing behavior for hooks.

Undocumented

INTERNAL-COMBINATION

CONDITION

Public

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.

MALFORMED-HOOK-HANDLER-BINDING

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

NO-SUCH-HOOK

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

Private

HOOK-ERROR-MIXIN

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