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.
Next: Files, Previous: The nhooks Reference Manual, Up: The nhooks Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
Improved hooks facility inspired by Serapeum.
Qiantan Hong <qhong@alum.mit.edu>
MIT
1.1.1
serapeum (system).
Next: Packages, Previous: Systems, Up: The nhooks Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: nhooks/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
nhooks (system).
Next: nhooks/nhooks.lisp, Previous: nhooks/nhooks.asd, Up: Lisp [Contents][Index]
nhooks (system).
Previous: nhooks/package.lisp, Up: Lisp [Contents][Index]
nhooks (system).
Next: Definitions, Previous: Files, Up: The nhooks Reference Manual [Contents][Index]
Packages are listed by definition order.
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.
common-lisp.
Next: Indexes, Previous: Packages, Up: The nhooks Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Ordinary functions, Previous: Public Interface, Up: Public Interface [Contents][Index]
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.
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
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.
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))
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
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’.
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.
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.
Next: Classes, Previous: Generic functions, Up: Public Interface [Contents][Index]
Add HANDLER to HOOK. Return HOOK.
Check HANDLER’s type according to the ‘handler-type’ slot of HOOK.
serapeum.
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.
Previous: Standalone methods, Up: Public Interface [Contents][Index]
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.
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.
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
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Ordinary functions, Previous: Internals, Up: Internals [Contents][Index]
Global hook table.
Next: Generic functions, Previous: Special variables, Up: Internals [Contents][Index]
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.
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.
Previous: Ordinary functions, Up: Internals [Contents][Index]
Previous: Definitions, Up: The nhooks Reference Manual [Contents][Index]
| 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 |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| 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 |
|---|