The modularize-hooks Reference Manual

Table of Contents

The modularize-hooks Reference Manual

This is the modularize-hooks Reference Manual, version 1.0.2, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 17:07:01 2021 GMT+0.

1 Introduction

About Modularize-Hooks

This is a simple extension to Modularize that allows modules to define and trigger hooks, which other modules can... well, hook on to. While such a system is very easy to create for your own projects, it's a good idea to have a standard form of doing it that doesn't interfere in any other way.

How To

In order to define hooks, you need to have a module. See Modularize on how to get that set up. If the modularize-hooks system has already been loaded prior to your module definition, everything should be ready and set up. Otherwise, you may call HOOKIFY on your module to initialise it. Creating hooks is similar to creating generic functions:

(define-hook documentation-finished (project)
  "Hook called whenever documentation for a project is finished.")

This defines a hook with a single argument, the project. In order to latch on to this hook, you may define a trigger. It is not strictly necessary to be within a module context to define triggers, but it is recommended in order to keep things tidy.

(define-trigger other-module:documentation-finished (project)
  (format T "~&Finished project documentation for ~a" project))

If you want to have multiple triggers on the same hook within the same package, you need to specify some kind of identifier to distinguish it from others.

(define-trigger (other-module:documentation-finished extra) ()
  (format T "~&ゆっくりしていってね！！！"))

Note that in this second example we did not provide any arguments to the trigger. Triggers may either accept no arguments if they have no use for them, or they need to match the arguments list of the hook. A simple test to assert this is done on trigger definition. Actually triggering the hook with its trigger is merely a question of calling TRIGGER:

(trigger 'other-module:documentation-finishe

2 Systems

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

2.1 modularize-hooks

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://Shinmera.github.io/modularize-hooks/

Source Control

(:git "https://github.com/shinmera/modularize-hooks.git")

Bug Tracker

https://github.com/Shinmera/modularize-hooks/issues

License

zlib

Description

Generic hooks and triggers extension for modularize.

Version

1.0.2

Dependencies

• modularize
• closer-mop
• trivial-arguments
• lambda-fiddle

Source

modularize-hooks.asd (file)

Components

• package.lisp (file)
• toolkit.lisp (file)
• hooks.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 modularize-hooks.asd

Location

modularize-hooks.asd

Systems

modularize-hooks (system)

3.1.2 modularize-hooks/package.lisp

Parent

modularize-hooks (system)

Location

package.lisp

Packages

modularize-hooks

3.1.3 modularize-hooks/toolkit.lisp

Dependency

package.lisp (file)

Parent

modularize-hooks (system)

Location

toolkit.lisp

Internal Definitions

function-lambda-matches (function)

3.1.4 modularize-hooks/hooks.lisp

Dependency

toolkit.lisp (file)

Parent

modularize-hooks (system)

Location

hooks.lisp

Exported Definitions

• arglist (method)
• (setf arglist) (method)
• define-hook (macro)
• define-hook-switch (macro)
• define-trigger (macro)
• dehookify (function)
• docstring (method)
• (setf docstring) (method)
• hook (function)
• (setf hook) (function)
• hook (class)
• hookify (function)
• list-hooks (function)
• name (method)
• (setf name) (method)
• remove-hook (function)
• remove-trigger (function)
• sticky-hook (class)
• trigger (function)

Internal Definitions

• enlist (function)
• find-trigger (method)
• (setf find-trigger) (method)
• run-triggers (method)
• run-triggers (method)
• stuck-args (method)
• (setf stuck-args) (method)
• triggers (method)
• (setf triggers) (method)

4 Packages

Packages are listed by definition order.

4.1 modularize-hooks

Source

package.lisp (file)

Nicknames

• hooks
• org.shirakumo.radiance.lib.modularize.hooks

Use List

• lambda-fiddle
• modularize
• common-lisp

Exported Definitions

• arglist (generic function)
• arglist (method)
• (setf arglist) (method)
• (setf arglist) (generic function)
• define-hook (macro)
• define-hook-switch (macro)
• define-trigger (macro)
• dehookify (function)
• docstring (generic function)
• docstring (method)
• (setf docstring) (method)
• (setf docstring) (generic function)
• hook (function)
• (setf hook) (function)
• hook (class)
• hookify (function)
• list-hooks (function)
• name (generic function)
• name (method)
• (setf name) (method)
• (setf name) (generic function)
• remove-hook (function)
• remove-trigger (function)
• sticky-hook (class)
• trigger (function)

Internal Definitions

• enlist (function)
• find-trigger (generic function)
• find-trigger (method)
• (setf find-trigger) (generic function)
• (setf find-trigger) (method)
• function-lambda-matches (function)
• run-triggers (generic function)
• run-triggers (method)
• run-triggers (method)
• stuck-args (generic function)
• stuck-args (method)
• (setf stuck-args) (method)
• (setf stuck-args) (generic function)
• triggers (generic function)
• triggers (method)
• (setf triggers) (method)
• (setf triggers) (generic function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Macros

Macro: define-hook NAME ARGS &optional DOCUMENTATION

Defines a new hook on which triggers can be defined.
The name should be a symbol from the module that the hook should belong to.

Package

modularize-hooks

Source

hooks.lisp (file)

Macro: define-hook-switch ON OFF ARGS

Package

modularize-hooks

Source

hooks.lisp (file)

Macro: define-trigger HOOK ARGS &body BODY

Defines a new trigger on the hook.
A trigger can either accept no arguments or it has to match the hook in its arguments list. The name of the trigger defaults to the *PACKAGE*. If you want to have multiple triggers for the same hook in the same package, use a list of the following structure as the HOOK argument: (hook trigger-name hook-module)

Package

modularize-hooks

Source

hooks.lisp (file)

5.1.2 Functions

Function: dehookify &optional MODULE

Returns the module to one that is not capable of hooks.

In essence this merely removes all functions from the hooks package and deletes it.

Package

modularize-hooks

Source

hooks.lisp (file)

Function: hook NAME &optional MODULE ERROR

Function: (setf hook) HOOK NAME &optional MODULE

Package

modularize-hooks

Source

hooks.lisp (file)

Function: hookify &optional MODULE

Turns the module into one capable of hooks.

In essence this merely defines a new package with a matching name.

Package

modularize-hooks

Source

hooks.lisp (file)

Function: list-hooks &optional MODULE

Package

modularize-hooks

Source

hooks.lisp (file)

Function: remove-hook NAME &optional MODULE

Removes the hook as named.

Package

modularize-hooks

Source

hooks.lisp (file)

Function: remove-trigger HOOK &optional IDENT MODULE

Attempts to remove the trigger from the hook.

Package

modularize-hooks

Source

hooks.lisp (file)

Function: trigger HOOK &rest ARGS

Calls all triggers registered on the hook with the given arguments.

Package

modularize-hooks

Source

hooks.lisp (file)

5.1.3 Generic functions

Generic Function: arglist OBJECT

Generic Function: (setf arglist) NEW-VALUE OBJECT

Package

modularize-hooks

Methods

Method: arglist (HOOK hook)

automatically generated reader method

Source

hooks.lisp (file)

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

automatically generated writer method

Source

hooks.lisp (file)

Generic Function: docstring OBJECT

Generic Function: (setf docstring) NEW-VALUE OBJECT

Package

modularize-hooks

Methods

Method: docstring (HOOK hook)

automatically generated reader method

Source

hooks.lisp (file)

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

automatically generated writer method

Source

hooks.lisp (file)

Generic Function: name OBJECT

Generic Function: (setf name) NEW-VALUE OBJECT

Package

modularize-hooks

Methods

Method: name (HOOK hook)

automatically generated reader method

Source

hooks.lisp (file)

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

automatically generated writer method

Source

hooks.lisp (file)

5.1.4 Classes

Class: hook ()

Package

modularize-hooks

Source

hooks.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

sticky-hook (class)

Direct methods

• find-trigger (method)
• find-trigger (method)
• find-trigger (method)
• run-triggers (method)
• documentation (method)
• documentation (method)
• print-object (method)
• docstring (method)
• docstring (method)
• triggers (method)
• triggers (method)
• arglist (method)
• arglist (method)
• name (method)
• name (method)

Direct slots

Slot: name

Initargs

:name

Readers

name (generic function)

Writers

(setf name) (generic function)

Slot: arglist

Initargs

:arglist

Readers

arglist (generic function)

Writers

(setf arglist) (generic function)

Slot: triggers

Initform

(make-hash-table :test (quote eql))

Readers

triggers (generic function)

Writers

(setf triggers) (generic function)

Slot: docstring

Initargs

:docstring

Readers

docstring (generic function)

Writers

(setf docstring) (generic function)

Direct Default Initargs

Initarg	Value
:name	(error "name required.")
:arglist	nil
:docstring	nil

Class: sticky-hook ()

Package

modularize-hooks

Source

hooks.lisp (file)

Direct superclasses

hook (class)

Direct methods

• (setf find-trigger) (method)
• run-triggers (method)
• stuck-args (method)
• stuck-args (method)

Direct slots

Slot: stuck-args

Readers

stuck-args (generic function)

Writers

(setf stuck-args) (generic function)

5.2 Internal definitions

5.2.1 Functions

Function: enlist A &rest ARGS

Package

modularize-hooks

Source

hooks.lisp (file)

Function: function-lambda-matches CUR ACT

Returns T if the function matches the lambda-list in arguments.
As a secondary value it returns a reason as to why it may have failed the test.

Package

modularize-hooks

Source

toolkit.lisp (file)

5.2.2 Generic functions

Generic Function: find-trigger NAME HOOK

Generic Function: (setf find-trigger) FUNCTION NAME HOOK

Package

modularize-hooks

Methods

Method: find-trigger NAME (HOOK hook)

Source

hooks.lisp (file)

Method: (setf find-trigger) (FUNCTION function) NAME (HOOK sticky-hook) after

Source

hooks.lisp (file)

Generic Function: run-triggers HOOK ARGS

Package

modularize-hooks

Methods

Method: run-triggers (HOOK sticky-hook) ARGS after

Source

hooks.lisp (file)

Method: run-triggers (HOOK hook) ARGS

Source

hooks.lisp (file)

Generic Function: stuck-args OBJECT

Generic Function: (setf stuck-args) NEW-VALUE OBJECT

Package

modularize-hooks

Methods

Method: stuck-args (STICKY-HOOK sticky-hook)

automatically generated reader method

Source

hooks.lisp (file)

Method: (setf stuck-args) NEW-VALUE (STICKY-HOOK sticky-hook)

automatically generated writer method

Source

hooks.lisp (file)

Generic Function: triggers OBJECT

Generic Function: (setf triggers) NEW-VALUE OBJECT

Package

modularize-hooks

Methods

Method: triggers (HOOK hook)

automatically generated reader method

Source

hooks.lisp (file)

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

automatically generated writer method

Source

hooks.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types