The nhooks Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The nhooks Reference Manual

This is the nhooks Reference Manual, version 1.1.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 05:43:38 2022 GMT+0.

Table of Contents


1 Systems

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


Previous: , Up: Systems   [Contents][Index]

1.1 nhooks

Improved hooks facility inspired by Serapeum.

Author

Qiantan Hong <qhong@alum.mit.edu>

License

MIT

Version

1.1.1

Dependency

serapeum (system).

Source

nhooks.asd.

Child Components

2 Files

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


Previous: , Up: Files   [Contents][Index]

2.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

2.1.1 nhooks/nhooks.asd

Source

nhooks.asd.

Parent Component

nhooks (system).

ASDF Systems

nhooks.


2.1.2 nhooks/package.lisp

Source

nhooks.asd.

Parent Component

nhooks (system).

Packages

nhooks.


Previous: , Up: Lisp   [Contents][Index]

2.1.3 nhooks/nhooks.lisp

Source

nhooks.asd.

Parent Component

nhooks (system).

Public Interface
Internals

3 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

3.1 nhooks

A hook is an instance of the ‘nhooks:hook’ class.
You can define new hook types with the ‘nhooks:define-hook-type’ helper. Examples:

(nhooks:define-hook-type string->string (function (string) string))

defines the ‘hook-string->string’ hook class.
This is equivalent to using ‘defclass’ and overriding the ‘nhooks:handler-type’ slot.

You can then instantiate it:

(defvar test-hook (make-instance ’nhooks:hook-void))

And add handlers to it:

(nhooks:add-hook test-hook #’my-function)

To run the hook:

(nhooks:run-hook test-hook)

Hook handlers can be automatically derived from named functions when calling ‘hooks:add-hook’. If you want to add an anonymous function, you’ll have to instantiate the handler manually:

(nhooks:add-hook test-hook
(make-instance ’nhooks:handler
:fn (lambda () (format t "Hello!~%")) :name ’my-anonymous-function))

You can customize the way handlers are composed by a hook:

(let ((hook (make-instance ’nhooks:hook-number->number
:handlers (list #’add-1 #’multiply-by-2) :combination #’nhooks:combine-composed-hook))) (nhooks:run-hook hook 17))
; => 35

Handlers can be enabled and disabled with ‘nhooks:enable-hook’ and ‘nhooks:disable-hook’ respectively.

If the handler is meant to be a setter, the ‘nhooks:place’ and ‘nhooks:value’ slots can be specified; this helps ‘nhooks:add-hook’ to compare handlers and, in particular, avoid duplicates in hooks.

Hooks can be defined globally and attached to arbitrary symbols or objects:

(nhooks:define-hook ’nhooks:hook-number->number ’foo
:object my-object

There are also the convenience macros ‘nhooks:on’ and ‘nhooks:once-on’ to attach a form to a hook and, for once-on, to ensure it’s run only once.

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

4 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

4.1 Public Interface


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.

Macro: on (hook args &body body)

Attach a handler with ARGS and BODY to the HOOK.

ARGS can be
- A symbol if there’s only one argument to the callback. - A list of arguments.
- An empty list, if the hook handlers take no argument.

Package

nhooks.

Source

nhooks.lisp.

Macro: once-on (hook args &body body)

Attach a handler with ARGS and BODY to the HOOK.

Remove the handler after it fires the first time.

See ‘on’.

Package

nhooks.

Source

nhooks.lisp.

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

This is intended to wrap all handler executions.

Package

nhooks.

Source

nhooks.lisp.


4.1.2 Ordinary 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.

Function: find-handler (handler-or-name handlers)

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

Package

nhooks.

Source

nhooks.lisp.

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.


4.1.3 Generic functions

Generic Reader: combination (object)
Generic Writer: (setf combination) (object)
Package

nhooks.

Methods
Reader Method: combination ((hook hook))
Writer Method: (setf combination) ((hook hook))

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

Source

nhooks.lisp.

Target Slot

combination.

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.

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.

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.

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.

Generic Function: description (object)
Package

nhooks.

Methods
Method: description ((symbol symbol))
Source

nhooks.lisp.

Reader Method: description ((handler handler))

Description of the handler. This is purely informative.

Source

nhooks.lisp.

Target Slot

description.

Generic Writer: (setf description) (object)
Package

nhooks.

Methods
Writer Method: (setf description) ((handler handler))

Description of the handler. This is purely informative.

Source

nhooks.lisp.

Target Slot

description.

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.

Generic Function: disabled-handlers (hook)
Package

nhooks.

Methods
Method: disabled-handlers ((hook hook))
Source

nhooks.lisp.

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.

Generic Function: fn (object)
Package

nhooks.

Methods
Method: fn ((function function))
Source

nhooks.lisp.

Method: fn ((symbol symbol))
Source

nhooks.lisp.

Reader Method: fn ((handler handler))

The handler function. It can be an anonymous function.

Source

nhooks.lisp.

Target Slot

fn.

Generic Writer: (setf fn) (object)
Package

nhooks.

Methods
Writer Method: (setf fn) ((handler handler))

The handler function. It can be an anonymous function.

Source

nhooks.lisp.

Target Slot

fn.

Generic Reader: handler-type (object)
Package

nhooks.

Methods
Reader Method: handler-type ((hook hook))

The exptected function type of handlers.

Source

nhooks.lisp.

Target Slot

handler-type.

Generic Function: handlers (hook)
Package

nhooks.

Methods
Method: handlers ((hook hook))
Source

nhooks.lisp.

Generic Reader: handlers-alist (object)
Generic Writer: (setf handlers-alist) (object)
Package

nhooks.

Methods
Reader Method: handlers-alist ((hook hook))
Writer Method: (setf handlers-alist) ((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.

Target Slot

handlers-alist.

Generic Function: name (object)
Package

nhooks.

Methods
Method: name ((fn function))
Source

nhooks.lisp.

Method: name ((symbol symbol))
Source

nhooks.lisp.

Reader Method: name ((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.

Target Slot

name.

Generic Writer: (setf name) (object)
Package

nhooks.

Methods
Writer Method: (setf name) ((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.

Target Slot

name.

Generic Reader: place (object)
Generic Writer: (setf place) (object)
Package

nhooks.

Methods
Reader Method: place ((handler handler))
Writer Method: (setf place) ((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.

Target Slot

place.

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.

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.

Generic Reader: value (object)
Generic Writer: (setf value) (object)
Package

nhooks.

Methods
Reader Method: value ((handler handler))
Writer Method: (setf 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.

Target Slot

value.


4.1.4 Standalone methods

Method: add-hook ((hook hook) handler &key append)

Add HANDLER to HOOK. Return HOOK.
Check HANDLER’s type according to the ‘handler-type’ slot of HOOK.

Package

serapeum.

Source

nhooks.lisp.

Method: initialize-instance :after ((handler handler) &key &allow-other-keys)
Source

nhooks.lisp.

Method: initialize-instance :after ((hook hook) &key handlers disabled-handlers &allow-other-keys)
Source

nhooks.lisp.

Method: print-object ((handler handler) stream)
Source

nhooks.lisp.

Method: remove-hook ((hook hook) handler-or-name)

Remove handler entry matching HANDLER-OR-NAME from handlers-alist in HOOK. HANDLER-OR-NAME is either a handler object or a symbol. Return HOOK’s handlers-alist.

Package

serapeum.

Source

nhooks.lisp.

Method: run-hook ((hook hook) &rest args)
Package

serapeum.

Source

nhooks.lisp.


4.1.5 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 slots 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.

Direct methods
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.

Writers

(setf name).

Slot: description

Description of the handler. This is purely informative.

Type

string

Initform

""

Initargs

:description

Readers

description.

Writers

(setf description).

Slot: fn

The handler function. It can be an anonymous function.

Type

function

Initform

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

Initargs

:fn

Readers

fn.

Writers

(setf fn).

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.

Writers

(setf place).

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.

Writers

(setf value).

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 its handlers accept the right argument types and return the right value types.

Package

nhooks.

Source

nhooks.lisp.

Direct subclasses
Direct methods
Direct slots
Slot: handler-type

The exptected function type of handlers.

Initargs

:handler-type

Readers

handler-type.

Writers

This slot is read-only.

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

Initform

(quote nil)

Initargs

:handlers-alist

Readers

handlers-alist.

Writers

(setf handlers-alist).

Slot: combination

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

Type

(or symbol function)

Initform

(function nhooks:default-combine-hook)

Initargs

:combination

Readers

combination.

Writers

(setf combination).

Class: hook-any
Package

nhooks.

Source

nhooks.lisp.

Direct superclasses

hook.

Direct slots
Slot: handler-type
Allocation

:class

Initform

(quote (function (&rest t)))

Class: hook-number->number
Package

nhooks.

Source

nhooks.lisp.

Direct superclasses

hook.

Direct slots
Slot: handler-type
Allocation

:class

Initform

(quote (function (number) number))

Class: hook-string->string
Package

nhooks.

Source

nhooks.lisp.

Direct superclasses

hook.

Direct slots
Slot: handler-type
Allocation

:class

Initform

(quote (function (string) string))

Class: hook-void
Package

nhooks.

Source

nhooks.lisp.

Direct superclasses

hook.

Direct slots
Slot: handler-type
Allocation

:class

Initform

(quote (function nil))


4.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

4.2.1 Special variables

Special Variable: %hook-table

Global hook table.

Package

nhooks.

Source

nhooks.lisp.


4.2.2 Ordinary 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.

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.


4.2.3 Generic functions

Generic Function: equals (fn1 fn2)
Package

nhooks.

Methods
Method: equals (obj1 obj2)
Source

nhooks.lisp.

Method: equals ((fn function) obj)
Source

nhooks.lisp.

Method: equals (obj (fn function))
Source

nhooks.lisp.

Method: equals ((fn handler) obj)
Source

nhooks.lisp.

Method: equals (obj (fn handler))
Source

nhooks.lisp.

Method: equals ((f1 function) (f2 function))
Source

nhooks.lisp.

Method: equals ((f function) (h handler))
Source

nhooks.lisp.

Method: equals ((h handler) (f function))
Source

nhooks.lisp.

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.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
A   C   D   E   F   G   H   I   M   N   O   P   R   V   W  
Index Entry  Section

(
(setf combination): Public generic functions
(setf combination): Public generic functions
(setf description): Public generic functions
(setf description): Public generic functions
(setf fn): Public generic functions
(setf fn): Public generic functions
(setf handlers-alist): Public generic functions
(setf handlers-alist): Public generic functions
(setf name): Public generic functions
(setf name): Public generic functions
(setf place): Public generic functions
(setf place): Public generic functions
(setf value): Public generic functions
(setf value): Public generic functions

A
add-hook: Public standalone methods
add-hook-internal: Private ordinary functions

C
combination: Public generic functions
combination: Public generic functions
combine-composed-hook: Public generic functions
combine-composed-hook: Public generic functions
combine-hook-until-failure: Public generic functions
combine-hook-until-failure: Public generic functions
combine-hook-until-success: Public generic functions
combine-hook-until-success: Public generic functions

D
default-combine-hook: Public generic functions
default-combine-hook: Public generic functions
define-hook: Public ordinary functions
define-hook-type: Public macros
description: Public generic functions
description: Public generic functions
description: Public generic functions
disable-hook: Public generic functions
disable-hook: Public generic functions
disabled-handlers: Public generic functions
disabled-handlers: Public generic functions

E
enable-hook: Public generic functions
enable-hook: Public generic functions
equals: Private generic functions
equals: Private generic functions
equals: Private generic functions
equals: Private generic functions
equals: Private generic functions
equals: Private generic functions
equals: Private generic functions
equals: Private generic functions
equals: Private generic functions
equals: Private generic functions

F
find-handler: Public ordinary functions
find-hook: Public ordinary functions
fn: Public generic functions
fn: Public generic functions
fn: Public generic functions
fn: Public generic functions
Function, add-hook-internal: Private ordinary functions
Function, define-hook: Public ordinary functions
Function, find-handler: Public ordinary functions
Function, find-hook: Public ordinary functions
Function, probe-ftype: Private ordinary functions

G
Generic Function, (setf combination): Public generic functions
Generic Function, (setf description): Public generic functions
Generic Function, (setf fn): Public generic functions
Generic Function, (setf handlers-alist): Public generic functions
Generic Function, (setf name): Public generic functions
Generic Function, (setf place): Public generic functions
Generic Function, (setf value): Public generic functions
Generic Function, combination: Public generic functions
Generic Function, combine-composed-hook: Public generic functions
Generic Function, combine-hook-until-failure: Public generic functions
Generic Function, combine-hook-until-success: Public generic functions
Generic Function, default-combine-hook: Public generic functions
Generic Function, description: Public generic functions
Generic Function, disable-hook: Public generic functions
Generic Function, disabled-handlers: Public generic functions
Generic Function, enable-hook: Public generic functions
Generic Function, equals: Private generic functions
Generic Function, fn: Public generic functions
Generic Function, handler-type: Public generic functions
Generic Function, handlers: Public generic functions
Generic Function, handlers-alist: Public generic functions
Generic Function, name: Public generic functions
Generic Function, place: Public generic functions
Generic Function, run-hook-with-args-until-failure: Public generic functions
Generic Function, run-hook-with-args-until-success: Public generic functions
Generic Function, value: Public generic functions

H
handler-type: Public generic functions
handler-type: Public generic functions
handlers: Public generic functions
handlers: Public generic functions
handlers-alist: Public generic functions
handlers-alist: Public generic functions

I
initialize-instance: Public standalone methods
initialize-instance: Public standalone methods

M
Macro, define-hook-type: Public macros
Macro, on: Public macros
Macro, once-on: Public macros
Macro, with-disable-handler-restart: Public macros
Method, (setf combination): Public generic functions
Method, (setf description): Public generic functions
Method, (setf fn): Public generic functions
Method, (setf handlers-alist): Public generic functions
Method, (setf name): Public generic functions
Method, (setf place): Public generic functions
Method, (setf value): Public generic functions
Method, add-hook: Public standalone methods
Method, combination: Public generic functions
Method, combine-composed-hook: Public generic functions
Method, combine-hook-until-failure: Public generic functions
Method, combine-hook-until-success: Public generic functions
Method, default-combine-hook: Public generic functions
Method, description: Public generic functions
Method, description: Public generic functions
Method, disable-hook: Public generic functions
Method, disabled-handlers: Public generic functions
Method, enable-hook: Public generic functions
Method, equals: Private generic functions
Method, equals: Private generic functions
Method, equals: Private generic functions
Method, equals: Private generic functions
Method, equals: Private generic functions
Method, equals: Private generic functions
Method, equals: Private generic functions
Method, equals: Private generic functions
Method, equals: Private generic functions
Method, fn: Public generic functions
Method, fn: Public generic functions
Method, fn: Public generic functions
Method, handler-type: Public generic functions
Method, handlers: Public generic functions
Method, handlers-alist: Public generic functions
Method, initialize-instance: Public standalone methods
Method, initialize-instance: Public standalone methods
Method, name: Public generic functions
Method, name: Public generic functions
Method, name: Public generic functions
Method, place: Public generic functions
Method, print-object: Public standalone methods
Method, remove-hook: Public standalone methods
Method, run-hook: Public standalone methods
Method, run-hook-with-args-until-failure: Public generic functions
Method, run-hook-with-args-until-success: Public generic functions
Method, value: Public generic functions

N
name: Public generic functions
name: Public generic functions
name: Public generic functions
name: Public generic functions

O
on: Public macros
once-on: Public macros

P
place: Public generic functions
place: Public generic functions
print-object: Public standalone methods
probe-ftype: Private ordinary functions

R
remove-hook: Public standalone methods
run-hook: Public standalone methods
run-hook-with-args-until-failure: Public generic functions
run-hook-with-args-until-failure: Public generic functions
run-hook-with-args-until-success: Public generic functions
run-hook-with-args-until-success: Public generic functions

V
value: Public generic functions
value: Public generic functions

W
with-disable-handler-restart: Public macros

Jump to:   (  
A   C   D   E   F   G   H   I   M   N   O   P   R   V   W