The nhooks Reference Manual

Table of Contents

The nhooks Reference Manual

This is the nhooks Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 05:40:06 2022 GMT+0.

1 Systems

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

1.1 nhooks

Author

Qiantan Hong <qhong@alum.mit.edu>

License

MIT

Description

Improved hooks facility inspired by Serapeum.

Version

1.0.0

Dependency

serapeum

Source

nhooks.asd (file)

Component

nhooks.lisp (file)

2 Files

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

2.1 Lisp

2.1.1 nhooks.asd

Location

nhooks.asd

Systems

nhooks (system)

2.1.2 nhooks/nhooks.lisp

Parent

nhooks (system)

Location

nhooks.lisp

Packages

nhooks

Exported Definitions

• combination (method)
• (setf combination) (method)
• combine-composed-hook (method)
• combine-hook-until-failure (method)
• combine-hook-until-success (method)
• default-combine-hook (method)
• define-hook (function)
• define-hook-type (macro)
• description (method)
• description (method)
• (setf description) (method)
• disable-hook (method)
• disabled-handlers (method)
• enable-hook (method)
• find-handler (function)
• find-hook (function)
• fn (method)
• fn (method)
• fn (method)
• (setf fn) (method)
• handler (class)
• handler-type (method)
• handlers (method)
• handlers-alist (method)
• (setf handlers-alist) (method)
• hook (class)
• hook-any (class)
• hook-number->number (class)
• hook-string->string (class)
• hook-void (class)
• name (method)
• name (method)
• name (method)
• (setf name) (method)
• place (method)
• (setf place) (method)
• run-hook-with-args-until-failure (method)
• run-hook-with-args-until-success (method)
• value (method)
• (setf value) (method)
• with-disable-handler-restart (macro)

Internal Definitions

• %hook-table (special variable)
• add-hook-internal (function)
• equals (method)
• equals (method)
• equals (method)
• equals (method)
• equals (method)
• equals (method)
• equals (method)
• equals (method)
• equals (method)
• probe-ftype (function)

3 Packages

Packages are listed by definition order.

3.1 nhooks

Source

nhooks.lisp (file)

Use List

common-lisp

Exported Definitions

• combination (generic function)
• combination (method)
• (setf combination) (method)
• (setf combination) (generic function)
• combine-composed-hook (generic function)
• combine-composed-hook (method)
• combine-hook-until-failure (generic function)
• combine-hook-until-failure (method)
• combine-hook-until-success (generic function)
• combine-hook-until-success (method)
• default-combine-hook (generic function)
• default-combine-hook (method)
• define-hook (function)
• define-hook-type (macro)
• description (generic function)
• description (method)
• description (method)
• (setf description) (method)
• (setf description) (generic function)
• disable-hook (generic function)
• disable-hook (method)
• disabled-handlers (generic function)
• disabled-handlers (method)
• enable-hook (generic function)
• enable-hook (method)
• find-handler (function)
• find-hook (function)
• fn (generic function)
• fn (method)
• fn (method)
• fn (method)
• (setf fn) (method)
• (setf fn) (generic function)
• handler (class)
• handler-type (generic function)
• handler-type (method)
• handlers (generic function)
• handlers (method)
• handlers-alist (generic function)
• handlers-alist (method)
• (setf handlers-alist) (method)
• (setf handlers-alist) (generic function)
• hook (class)
• hook-any (class)
• hook-number->number (class)
• hook-string->string (class)
• hook-void (class)
• name (generic function)
• name (method)
• name (method)
• name (method)
• (setf name) (method)
• (setf name) (generic function)
• place (generic function)
• place (method)
• (setf place) (method)
• (setf place) (generic function)
• run-hook-with-args-until-failure (generic function)
• run-hook-with-args-until-failure (method)
• run-hook-with-args-until-success (generic function)
• run-hook-with-args-until-success (method)
• value (generic function)
• value (method)
• (setf value) (method)
• (setf value) (generic function)
• with-disable-handler-restart (macro)

Internal Definitions

• %hook-table (special variable)
• add-hook-internal (function)
• equals (generic function)
• equals (method)
• equals (method)
• equals (method)
• equals (method)
• equals (method)
• equals (method)
• equals (method)
• equals (method)
• equals (method)
• probe-ftype (function)

4 Definitions

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

4.1 Exported definitions

4.1.1 Macros

Macro: define-hook-type NAME TYPE

Define hook class.
Type must be something like:

(function (string) (values integer t))

The ‘handler-type’ of the defined hook class has ‘:class’ allocation type, so that all hooks of such class have the same ‘handler-type’.

Package

nhooks

Source

nhooks.lisp (file)

Macro: with-disable-handler-restart (HANDLER) &body BODY

This is intended to wrap all handler executions.

Package

nhooks

Source

nhooks.lisp (file)

4.1.2 Functions

Function: define-hook HOOK-TYPE NAME &key OBJECT HANDLERS DISABLED-HANDLERS COMBINATION

Return a globally-accessible hook.
The hook can be accessed with ‘find-hook’ at (list NAME OBJECT). OBJECT is an arbitrary value the hook is associated to.

Package

nhooks

Source

nhooks.lisp (file)

Function: find-handler HANDLER-OR-NAME HANDLERS

Return handler matching HANDLER-OR-NAME in HANDLERS sequence.

Package

nhooks

Source

nhooks.lisp (file)

Function: find-hook NAME &optional OBJECT

Return the global hook with name NAME associated to OBJECT, if provided. The following examples return different hooks:
- (find-hook ’foo-hook)
- (find-hook ’foo-hook ’bar-class)
- (find-hook ’foo-hook (make-instance ’bar-class))

Package

nhooks

Source

nhooks.lisp (file)

4.1.3 Generic functions

Generic Function: combination OBJECT

Generic Function: (setf combination) NEW-VALUE OBJECT

Package

nhooks

Methods

Method: combination (HOOK hook)

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

This can be used to reverse the execution order, return a single value, etc.

Source

nhooks.lisp (file)

Generic Function: combine-composed-hook HOOK &rest ARGS

Package

nhooks

Methods

Method: combine-composed-hook (HOOK hook) &rest ARGS

Return the result of the composition of the HOOK handlers on ARGS, from oldest to youngest.
Without handler, return ARGS as values.
This is an acceptable ‘combination’ for ‘hook’.

Source

nhooks.lisp (file)

Generic Function: combine-hook-until-failure HOOK &rest ARGS

Package

nhooks

Methods

Method: combine-hook-until-failure (HOOK hook) &rest ARGS

Return the list of values until the first nil result. Handlers after the failing one are not run.

This is an acceptable ‘combination’ for ‘hook’.

Source

nhooks.lisp (file)

Generic Function: combine-hook-until-success HOOK &rest ARGS

Package

nhooks

Methods

Method: combine-hook-until-success (HOOK hook) &rest ARGS

Return the value of the first non-nil result.
Handlers after the successful one are not run.

You need to check if the hook has handlers to know if a NIL return value is due to all handlers failing or an empty hook.

This is an acceptable ‘combination’ for ‘hook’.

Source

nhooks.lisp (file)

Generic Function: default-combine-hook HOOK &rest ARGS

Package

nhooks

Methods

Method: default-combine-hook (HOOK hook) &rest ARGS

Return the list of the results of the HOOK handlers applied from youngest to oldest to ARGS.
Return ’() when there is no handler.
This is an acceptable ‘combination’ for ‘hook’.

Source

nhooks.lisp (file)

Generic Function: description OBJECT

Generic Function: (setf description) NEW-VALUE OBJECT

Package

nhooks

Methods

Method: description (SYMBOL symbol)

Source

nhooks.lisp (file)

Method: description (HANDLER handler)

Method: (setf description) NEW-VALUE (HANDLER handler)

Description of the handler. This is purely informative.

Source

nhooks.lisp (file)

Generic Function: disable-hook HOOK &rest HANDLERS

Package

nhooks

Methods

Method: disable-hook (HOOK hook) &rest HANDLERS

Disable HANDLERS.
Without HANDLERS, disable all of them.

Source

nhooks.lisp (file)

Generic Function: disabled-handlers HOOK

Package

nhooks

Methods

Method: disabled-handlers (HOOK hook)

Source

nhooks.lisp (file)

Generic Function: enable-hook HOOK &rest HANDLERS

Package

nhooks

Methods

Method: enable-hook (HOOK hook) &rest HANDLERS

Enable HANDLERS.
Without HANDLERS, enable all of them.

Source

nhooks.lisp (file)

Generic Function: fn OBJECT

Generic Function: (setf fn) NEW-VALUE OBJECT

Package

nhooks

Methods

Method: fn (FUNCTION function)

Source

nhooks.lisp (file)

Method: fn (SYMBOL symbol)

Source

nhooks.lisp (file)

Method: fn (HANDLER handler)

Method: (setf fn) NEW-VALUE (HANDLER handler)

The handler function. It can be an anonymous function.

Source

nhooks.lisp (file)

Generic Function: handler-type OBJECT

Package

nhooks

Methods

Method: handler-type (HOOK hook)

The exptected function type of handlers.

Source

nhooks.lisp (file)

Generic Function: handlers HOOK

Package

nhooks

Methods

Method: handlers (HOOK hook)

Source

nhooks.lisp (file)

Generic Function: handlers-alist OBJECT

Generic Function: (setf handlers-alist) NEW-VALUE OBJECT

Package

nhooks

Methods

Method: handlers-alist (HOOK hook)

Method: (setf handlers-alist) NEW-VALUE (HOOK hook)

A list with elements of the form (HANDLER . ENABLE-P).

‘run-hook’ only runs HANDLERs associated with non nil ENABLE-P. This is useful it the user wishes to disable some or all handlers without removing them from the hook.

Source

nhooks.lisp (file)

Generic Function: name OBJECT

Generic Function: (setf name) NEW-VALUE OBJECT

Package

nhooks

Methods

Method: name (FN function)

Source

nhooks.lisp (file)

Method: name (SYMBOL symbol)

Source

nhooks.lisp (file)

Method: name (HANDLER handler)

Method: (setf name) NEW-VALUE (HANDLER handler)

Name of the handler.
It defaults to the function name if ‘fn’ is a named function.
This is useful so that the user can build handlers out of anonymous functions.

Source

nhooks.lisp (file)

Generic Function: place OBJECT

Generic Function: (setf place) NEW-VALUE OBJECT

Package

nhooks

Methods

Method: place (HANDLER handler)

Method: (setf place) NEW-VALUE (HANDLER handler)

If the handler is meant to be a setter, PLACE describes what is set. PLACE can be a symbol or a pair (CLASS SLOT).
This can be left empty if the handler is not a setter.

Source

nhooks.lisp (file)

Generic Function: run-hook-with-args-until-failure HOOK &rest ARGS

Package

nhooks

Methods

Method: run-hook-with-args-until-failure (HOOK hook) &rest ARGS

This is equivalent to setting the combination function to ‘combine-hook-until-failure’ and calling ‘run-hook’.

Source

nhooks.lisp (file)

Generic Function: run-hook-with-args-until-success HOOK &rest ARGS

Package

nhooks

Methods

Method: run-hook-with-args-until-success (HOOK hook) &rest ARGS

This is equivalent to setting the combination function to ‘combine-hook-until-success’ and calling ‘run-hook’.

Source

nhooks.lisp (file)

Generic Function: value OBJECT

Generic Function: (setf value) NEW-VALUE OBJECT

Package

nhooks

Methods

Method: value (HANDLER handler)

Method: (setf value) NEW-VALUE (HANDLER handler)

If the handler is meant to be a setter, VALUE can be used to describe what FN is going to set to PLACE.
In particular, PLACE and VALUE can be used to compare handlers.
This can be left empty if the handler is not a setter.

Source

nhooks.lisp (file)

4.1.4 Classes

Class: handler ()

Handlers are wrappers around functions used in typed hooks.
They serve two purposes as opposed to regular functions:

- They can embed a NAME so that anonymous functions can be conveniently used in hooks.
- If the handler is meant to be a setter, the PLACE and VALUE slot can be used to identify and compare setters.

With this extra information, it’s possible to compare handlers and, in particular, avoid duplicates in hooks.

Package

nhooks

Source

nhooks.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• equals (method)
• equals (method)
• equals (method)
• equals (method)
• equals (method)
• initialize-instance (method)
• print-object (method)
• value (method)
• value (method)
• place (method)
• place (method)
• fn (method)
• fn (method)
• description (method)
• description (method)
• name (method)
• name (method)

Direct slots

Slot: name

Name of the handler.
It defaults to the function name if ‘fn’ is a named function.
This is useful so that the user can build handlers out of anonymous functions.

Type

symbol

Initargs

:name

Readers

name (generic function)

Writers

(setf name) (generic function)

Slot: description

Description of the handler. This is purely informative.

Type

string

Initargs

:description

Initform

""

Readers

description (generic function)

Writers

(setf description) (generic function)

Slot: fn

The handler function. It can be an anonymous function.

Type

function

Initargs

:fn

Initform

(alexandria:required-argument (quote nhooks:fn))

Readers

fn (generic function)

Writers

(setf fn) (generic function)

Slot: place

If the handler is meant to be a setter, PLACE describes what is set. PLACE can be a symbol or a pair (CLASS SLOT).
This can be left empty if the handler is not a setter.

Type

(or symbol list)

Initargs

:place

Readers

place (generic function)

Writers

(setf place) (generic function)

Slot: value

If the handler is meant to be a setter, VALUE can be used to describe what FN is going to set to PLACE.
In particular, PLACE and VALUE can be used to compare handlers.
This can be left empty if the handler is not a setter.

Initargs

:value

Readers

value (generic function)

Writers

(setf value) (generic function)

Class: hook ()

This hook class serves as support for typed-hook.

Typing in hook is crucial to guarantee that a hook is well formed, i.e. that it’s handlers accept the right argument types and return the right value types.

Package

nhooks

Source

nhooks.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• hook-void (class)
• hook-string->string (class)
• hook-number->number (class)
• hook-any (class)

Direct methods

• add-hook (method)
• enable-hook (method)
• disable-hook (method)
• run-hook-with-args-until-success (method)
• run-hook-with-args-until-failure (method)
• run-hook (method)
• remove-hook (method)
• combine-composed-hook (method)
• combine-hook-until-success (method)
• combine-hook-until-failure (method)
• default-combine-hook (method)
• disabled-handlers (method)
• handlers (method)
• initialize-instance (method)
• combination (method)
• combination (method)
• handlers-alist (method)
• handlers-alist (method)
• handler-type (method)

Direct slots

Slot: handler-type

The exptected function type of handlers.

Initargs

:handler-type

Readers

handler-type (generic function)

Slot: handlers-alist

A list with elements of the form (HANDLER . ENABLE-P).

‘run-hook’ only runs HANDLERs associated with non nil ENABLE-P. This is useful it the user wishes to disable some or all handlers without removing them from the hook.

Type

list

Initargs

:handlers-alist

Initform

(quote nil)

Readers

handlers-alist (generic function)

Writers

(setf handlers-alist) (generic function)

Slot: combination

This can be used to reverse the execution order, return a single value, etc.

Type

(or symbol function)

Initargs

:combination

Initform

(function nhooks:default-combine-hook)

Readers

combination (generic function)

Writers

(setf combination) (generic function)

Class: hook-any ()

Package

nhooks

Source

nhooks.lisp (file)

Direct superclasses

hook (class)

Direct slots

Slot: handler-type

Allocation

:class

Initform

(quote (function (&rest t)))

Class: hook-number->number ()

Package

nhooks

Source

nhooks.lisp (file)

Direct superclasses

hook (class)

Direct slots

Slot: handler-type

Allocation

:class

Initform

(quote (function (number) number))

Class: hook-string->string ()

Package

nhooks

Source

nhooks.lisp (file)

Direct superclasses

hook (class)

Direct slots

Slot: handler-type

Allocation

:class

Initform

(quote (function (string) string))

Class: hook-void ()

Package

nhooks

Source

nhooks.lisp (file)

Direct superclasses

hook (class)

Direct slots

Slot: handler-type

Allocation

:class

Initform

(quote (function nil))

4.2 Internal definitions

4.2.1 Special variables

Special Variable: %hook-table

Global hook table.

Package

nhooks

Source

nhooks.lisp (file)

4.2.2 Functions

Function: add-hook-internal HOOK HANDLER &key APPEND

Add HANDLER to HOOK if not already in it. Return HOOK.
HANDLER is also not added if it’s disabled.
If APPEND is non-nil, HANDLER is added at the end.

Package

nhooks

Source

nhooks.lisp (file)

Function: probe-ftype FUNCTION FTYPE

Invoke compiler to probe the type of FUNCTION.

If type of FUNCTION contradicts with FTYPE, raise an error.

If FTYPE is nil, nothing is done.

Package

nhooks

Source

nhooks.lisp (file)

4.2.3 Generic functions

Generic Function: equals FN1 FN2

Package

nhooks

Methods

Method: equals OBJ1 OBJ2

Source

nhooks.lisp (file)

Method: equals (FN function) OBJ

Source

nhooks.lisp (file)

Method: equals OBJ (FN function)

Source

nhooks.lisp (file)

Method: equals (FN handler) OBJ

Source

nhooks.lisp (file)

Method: equals OBJ (FN handler)

Source

nhooks.lisp (file)

Method: equals (F1 function) (F2 function)

Source

nhooks.lisp (file)

Method: equals (F1 function) (F2 handler)

Source

nhooks.lisp (file)

Method: equals (H handler) (F function)

Source

nhooks.lisp (file)

Method: equals (FN1 handler) (FN2 handler)

Return non-nil if FN1 and FN2 are equal.
Handlers are equal if they are setters of the same place and same value, or if their names are equal.

Source

nhooks.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types