source: project/wiki/eggref/5/srfi-173 @ 39116

Last change on this file since 39116 was 39116, checked in by gnosis, 6 months ago

Fixed markup of emphasized test

File size: 4.0 KB
Line 
1== SRFI 173: Hooks
2=== Abstract
3This 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.
4
5For more information see: [[https://srfi.schemers.org/srfi-173/srfi-173.html|SRFI 173: Hooks]]
6=== Rationale
7The 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.
8
9While 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.
10=== Specification
11This specification describes one disjoint type called hook.
12
13<enscript highlight="scheme">
14(make-hook arity)
15</enscript>
16
17Create a hook object for storing procedures of ARITY. The return value is a hook object.
18
19<enscript highlight="scheme">
20(hook? obj)
21</enscript>
22
23Return #t if obj is a hook. Otherwise, it returns #f.
24
25<enscript highlight="scheme">
26(list->hook arity lst)
27</enscript>
28
29Create a hook with the given procedures LST that must have an arity equal to ARITY. The return value is a hook object.
30
31<enscript highlight="scheme">
32(list->hook! hook lst)
33</enscript>
34
35Replace procedures in HOOK by the procedures in LST. The return value is unspecified
36
37<enscript highlight="scheme">
38(hook-add! hook proc)
39</enscript>
40
41Add 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.
42
43<enscript highlight="scheme">
44(hook-delete! hook proc)
45</enscript>
46
47Delete the procedure PROC from the HOOK object. The return value is not specified.
48
49<enscript highlight="scheme">
50(hook-reset! hook)
51</enscript>
52
53Remove all procedures from the HOOK object. The return value is not specified.
54
55<enscript highlight="scheme">
56(hook->list hook)
57</enscript>
58
59Convert the list of procedures of HOOK object to a list.
60
61<enscript highlight="scheme">
62(hook-run hook . args)
63</enscript>
64
65Apply 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
66length of ARGS is not equal to the arity of the HOOK object.
67
68In a Scheme with invokable objects, hooks can invoked directly.
69=== Implementation Notes
70The reference implementation from SRFI-173 was used verbatim, with the exception of a single call to {{assume}} from [[https://srfi.schemers.org/srfi-145/srfi-145.html|SRFI 145]], which was replaced with {{assert}}.
71=== Acknowledgements
72This specification is based on the GNU Guile module called [[https://www.gnu.org/software/guile/manual/html_node/Hooks.html#Hooks|hook]].
73=== Author
74The SRFI-173 library author is Amirouche Boubekki.  It was ported to Chicken by Sergey Goldgaber.
75=== Copyright
76Copyright © Amirouche Boubekki (2019).
77
78Permission 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:
79
80The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.
81
82THE 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.
83=== Version history
84==== 0.1
85Ported to Chicken 5.2.0
Note: See TracBrowser for help on using the repository browser.