Title

Hooks

Author

Amirouche Boubekki

Status

This SRFI is currently in final status. Here is an explanation of each status that a SRFI can hold. To provide input on this SRFI, please send email to srfi-173@nospamsrfi.schemers.org. To subscribe to the list, follow these instructions. You can access previous messages via the mailing list archive.

Abstract

This library describes a mechanism known as hooks. Hooks are a certain kind of extension point in a program that allows interleaving the execution of arbitrary code with the execution of the program without introducing any coupling between the two.

Rationale

The use of hooks is pervasive in GNU Emacs and many other programs that offer some “plugin” mechanism that is built on top a facility similar to what this library offers.

While building programs, there is a need to offer extension points to allow the user to extend and customize the execution of the program in way that avoids coupling. This library wants to help with that.

Specification

This specification describes one disjoint type called hook.

(make-hook arity)

Create a hook object for storing procedures of ARITY. The return value is a hook object.

(hook? obj)

Return #t if obj is a hook. Otherwise, it returns #f.

(list->hook arity lst)

Create a hook with the given procedures LST that must have an arity equal to ARITY. The return value is a hook object.

(list->hook! hook lst)

Replace procedures in HOOK by the procedures in LST. The return value is unspecified

(hook-add! hook proc)

Add the procedure PROC to the HOOK object. The return value is not specified. An implementation may check that the arity of PROC is equal to the arity of the HOOK.

(hook-delete! hook proc)

Delete the procedure PROC from the HOOK object. The return value is not specified.

(hook-reset! hook)

Remove all procedures from the HOOK object. The return value is not specified.

(hook->list hook)

Convert the list of procedures of HOOK object to a list.

(hook-run hook . args)

Apply all procedures from HOOK to the arguments ARGS. The order of the procedure application is not specified. The return value is not specified. It is an error if the length of ARGS is not equal to the arity of the HOOK object.

In a Scheme with invokable objects, hooks can invoked directly.

Implementation

A portable sample implementation is provided.

Acknowledgements

This specification is based on the GNU Guile module called hook.

Copyright © Amirouche Boubekki (2019).

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


Editor: Arthur A. Gleckler