The nhooks Reference Manual

Table of Contents

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

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.


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

1 Systems

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


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

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)


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

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 files   [Contents][Index]

2.1.1 nhooks.asd

Location

nhooks.asd

Systems

nhooks (system)


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

2.1.2 nhooks/nhooks.lisp

Parent

nhooks (system)

Location

nhooks.lisp

Packages

nhooks

Exported Definitions
Internal Definitions

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

3 Packages

Packages are listed by definition order.


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

3.1 nhooks

Source

nhooks.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

4 Definitions

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


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

4.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Previous: , Up: Exported definitions   [Contents][Index]

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


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

4.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

4.2.1 Special variables

Special Variable: %hook-table

Global hook table.

Package

nhooks

Source

nhooks.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Previous: , Up: Internal definitions   [Contents][Index]

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)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   N  
Index Entry  Section

F
File, Lisp, nhooks.asd: The nhooks․asd file
File, Lisp, nhooks/nhooks.lisp: The nhooks/nhooks․lisp file

L
Lisp File, nhooks.asd: The nhooks․asd file
Lisp File, nhooks/nhooks.lisp: The nhooks/nhooks․lisp file

N
nhooks.asd: The nhooks․asd file
nhooks/nhooks.lisp: The nhooks/nhooks․lisp file

Jump to:   F   L   N  

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

A.2 Functions

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

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

A
add-hook-internal: Internal functions

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

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

E
enable-hook: Exported generic functions
enable-hook: Exported generic functions
equals: Internal generic functions
equals: Internal generic functions
equals: Internal generic functions
equals: Internal generic functions
equals: Internal generic functions
equals: Internal generic functions
equals: Internal generic functions
equals: Internal generic functions
equals: Internal generic functions
equals: Internal generic functions

F
find-handler: Exported functions
find-hook: Exported functions
fn: Exported generic functions
fn: Exported generic functions
fn: Exported generic functions
fn: Exported generic functions
Function, add-hook-internal: Internal functions
Function, define-hook: Exported functions
Function, find-handler: Exported functions
Function, find-hook: Exported functions
Function, probe-ftype: Internal functions

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

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

M
Macro, define-hook-type: Exported macros
Macro, with-disable-handler-restart: Exported macros
Method, (setf combination): Exported generic functions
Method, (setf description): Exported generic functions
Method, (setf fn): Exported generic functions
Method, (setf handlers-alist): Exported generic functions
Method, (setf name): Exported generic functions
Method, (setf place): Exported generic functions
Method, (setf value): Exported generic functions
Method, combination: Exported generic functions
Method, combine-composed-hook: Exported generic functions
Method, combine-hook-until-failure: Exported generic functions
Method, combine-hook-until-success: Exported generic functions
Method, default-combine-hook: Exported generic functions
Method, description: Exported generic functions
Method, description: Exported generic functions
Method, disable-hook: Exported generic functions
Method, disabled-handlers: Exported generic functions
Method, enable-hook: Exported generic functions
Method, equals: Internal generic functions
Method, equals: Internal generic functions
Method, equals: Internal generic functions
Method, equals: Internal generic functions
Method, equals: Internal generic functions
Method, equals: Internal generic functions
Method, equals: Internal generic functions
Method, equals: Internal generic functions
Method, equals: Internal generic functions
Method, fn: Exported generic functions
Method, fn: Exported generic functions
Method, fn: Exported generic functions
Method, handler-type: Exported generic functions
Method, handlers: Exported generic functions
Method, handlers-alist: Exported generic functions
Method, name: Exported generic functions
Method, name: Exported generic functions
Method, name: Exported generic functions
Method, place: Exported generic functions
Method, run-hook-with-args-until-failure: Exported generic functions
Method, run-hook-with-args-until-success: Exported generic functions
Method, value: Exported generic functions

N
name: Exported generic functions
name: Exported generic functions
name: Exported generic functions
name: Exported generic functions

P
place: Exported generic functions
place: Exported generic functions
probe-ftype: Internal functions

R
run-hook-with-args-until-failure: Exported generic functions
run-hook-with-args-until-failure: Exported generic functions
run-hook-with-args-until-success: Exported generic functions
run-hook-with-args-until-success: Exported generic functions

V
value: Exported generic functions
value: Exported generic functions

W
with-disable-handler-restart: Exported macros

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

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

A.3 Variables

Jump to:   %  
C   D   F   H   N   P   S   V  
Index Entry  Section

%
%hook-table: Internal special variables

C
combination: Exported classes

D
description: Exported classes

F
fn: Exported classes

H
handler-type: Exported classes
handler-type: Exported classes
handler-type: Exported classes
handler-type: Exported classes
handler-type: Exported classes
handlers-alist: Exported classes

N
name: Exported classes

P
place: Exported classes

S
Slot, combination: Exported classes
Slot, description: Exported classes
Slot, fn: Exported classes
Slot, handler-type: Exported classes
Slot, handler-type: Exported classes
Slot, handler-type: Exported classes
Slot, handler-type: Exported classes
Slot, handler-type: Exported classes
Slot, handlers-alist: Exported classes
Slot, name: Exported classes
Slot, place: Exported classes
Slot, value: Exported classes
Special Variable, %hook-table: Internal special variables

V
value: Exported classes

Jump to:   %  
C   D   F   H   N   P   S   V  

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

A.4 Data types

Jump to:   C   H   N   P   S  
Index Entry  Section

C
Class, handler: Exported classes
Class, hook: Exported classes
Class, hook-any: Exported classes
Class, hook-number->number: Exported classes
Class, hook-string->string: Exported classes
Class, hook-void: Exported classes

H
handler: Exported classes
hook: Exported classes
hook-any: Exported classes
hook-number->number: Exported classes
hook-string->string: Exported classes
hook-void: Exported classes

N
nhooks: The nhooks system
nhooks: The nhooks package

P
Package, nhooks: The nhooks package

S
System, nhooks: The nhooks system

Jump to:   C   H   N   P   S