This is the nhooks Reference Manual, version 1.1.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Jan 15 07:11:45 2023 GMT+0.
The main system appears first, followed by any subsystem dependency.
nhooksImproved hooks facility inspired by Serapeum.
Qiantan Hong <qhong@alum.mit.edu>
MIT
1.1.1
serapeum (system).
closer-mop (system).
package.lisp (file).
nhooks.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
nhooks/nhooks.lispnhooks (system).
add-hook (method).
combination (reader method).
(setf combination) (writer 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 (reader method).
(setf description) (writer method).
disable-hook (method).
disabled-handlers (method).
enable-hook (method).
find-handler (function).
find-hook (function).
fn (method).
fn (method).
fn (reader method).
(setf fn) (writer method).
handler (class).
handler-type (reader method).
handlers (method).
handlers-alist (reader method).
(setf handlers-alist) (writer method).
hook (class).
hook-any (class).
hook-number->number (class).
hook-string->string (class).
hook-void (class).
initialize-instance (method).
initialize-instance (method).
name (method).
name (method).
name (reader method).
(setf name) (writer method).
on (macro).
once-on (macro).
place (reader method).
(setf place) (writer method).
print-object (method).
remove-hook (method).
run-hook (method).
run-hook-with-args-until-failure (method).
run-hook-with-args-until-success (method).
value (reader method).
(setf value) (writer method).
with-disable-handler-restart (macro).
%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).
Packages are listed by definition order.
nhooksA 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.
common-lisp.
combination (generic reader).
(setf combination) (generic writer).
combine-composed-hook (generic function).
combine-hook-until-failure (generic function).
combine-hook-until-success (generic function).
default-combine-hook (generic function).
define-hook (function).
define-hook-type (macro).
description (generic function).
(setf description) (generic writer).
disable-hook (generic function).
disabled-handlers (generic function).
enable-hook (generic function).
find-handler (function).
find-hook (function).
fn (generic function).
(setf fn) (generic writer).
handler (class).
handler-type (generic reader).
handlers (generic function).
handlers-alist (generic reader).
(setf handlers-alist) (generic writer).
hook (class).
hook-any (class).
hook-number->number (class).
hook-string->string (class).
hook-void (class).
name (generic function).
(setf name) (generic writer).
on (macro).
once-on (macro).
place (generic reader).
(setf place) (generic writer).
run-hook-with-args-until-failure (generic function).
run-hook-with-args-until-success (generic function).
value (generic reader).
(setf value) (generic writer).
with-disable-handler-restart (macro).
%hook-table (special variable).
add-hook-internal (function).
equals (generic function).
probe-ftype (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
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’.
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.
Attach a handler with ARGS and BODY to the HOOK.
Remove the handler after it fires the first time.
See ‘on’.
This is intended to wrap all handler executions.
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.
Return handler matching HANDLER-OR-NAME in HANDLERS sequence.
If INCLUDE-DISABLED is non-nil, search both enabled and disabled handlers. Otherwise, search only enabled handlers.
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))
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’.
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.
function)) ¶symbol)) ¶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.
hook) handler &key append) ¶Add HANDLER to HOOK. Return HOOK.
Check HANDLER’s type according to the ‘handler-type’ slot of HOOK.
serapeum.
hook) &key handlers disabled-handlers &allow-other-keys) ¶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.
serapeum.
hook) &rest args) ¶Invoke all the HOOK handlers with the default ‘combination’.
Alternatively, use ‘funcall’ of the hook for the same effect.
serapeum.
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.
Handlers are ‘funcall’able. If you subclass those, don’t forget to add
a ‘closer-mop:funcallable-standard-class’ to retain this property.
funcallable-standard-object.
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.
symbol
:name
name.
Description of the handler. This is purely informative.
string
""
:description
The handler function. It can be an anonymous function.
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.
(or symbol list)
:place
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.
:value
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.
Hooks are ‘funcall’able. If you subclass those, don’t forget to add a
‘closer-mop:funcallable-standard-class’ to retain this
property. ‘define-hook-type’ does that for you.
funcallable-standard-object.
add-hook.
(setf combination).
combination.
combine-composed-hook.
combine-hook-until-failure.
combine-hook-until-success.
default-combine-hook.
disable-hook.
disabled-handlers.
enable-hook.
handler-type.
handlers.
(setf handlers-alist).
handlers-alist.
initialize-instance.
remove-hook.
run-hook.
run-hook-with-args-until-failure.
run-hook-with-args-until-success.
The exptected function type of handlers.
:handler-type
This slot is read-only.
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.
list
(quote nil)
:handlers-alist
This can be used to reverse the execution order, return a single value, etc.
(or symbol function)
(function nhooks:default-combine-hook)
:combination
Add HANDLER to HOOK.
Return HOOK.
If APPEND is non-nil, HANDLER is added at the end. If HANDLER is already present in HOOK, move it to the front (or end if APPEND is non-nil) of ‘handler-alist’ and ensure it is enabled.
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.
function) obj) ¶function)) ¶function) (f2 function)) ¶| Jump to: | (
A C D E F G H I M N O P R V W |
|---|
| Jump to: | (
A C D E F G H I M N O P R V W |
|---|
| Jump to: | %
C D F H N P S V |
|---|
| Jump to: | %
C D F H N P S V |
|---|
| Jump to: | C F H N P S |
|---|
| Jump to: | C F H N P S |
|---|