1hook(n) Hooks hook(n)
2______________________________________________________________________________
6
8 hook - Hooks
9
11 package require Tcl 8.5
12 package require hook ?0.1?
14 hook bind ?subject? ?hook? ?observer? ?cmdPrefix?
16 hook call subject hook ?args...?
18 hook forget object
20 hook cget option
22 hook configure option value ...
24______________________________________________________________________________
26
28 This package provides the hook ensemble command, which implements the
29 Subject/Observer pattern. It allows subjects, which may be modules,
30 objects, widgets, and so forth, to synchronously call hooks which may
31 be bound to an arbitrary number of subscribers, called observers. A
32 subject may call any number of distinct hooks, and any number of
33 observers can bind callbacks to a particular hook called by a particu‐
34 lar subject. Hook bindings can be queried and deleted.
35 This man page is intended to be a reference only.
37
39 INTRODUCTION
40 Tcl modules usually send notifications to other modules in two ways:
41 via Tk events, and via callback options like the text widget's
42 -yscrollcommand option. Tk events are available only in Tk, and call‐
43 back options require tight coupling between the modules sending and
44 receiving the notification.
45 Loose coupling between sender and receiver is often desirable, however.
47 In Model/View/Controller terms, a View can send a command (stemming
48 from user input) to the Controller, which updates the Model. The Model
49 can then call a hook to which all relevant Views subscribe. The Model
50 is decoupled from the Views, and indeed need not know whether any Views
51 actually exist. At present, Tcl/Tk has no standard mechanism for
52 implementing loose coupling of this kind. This package defines a new
53 command, hook, which implements just such a mechanism.
54 BINDINGS
56 The hook command manages a collection of hook bindings. A hook binding
57 has four elements:
58 [1] A subject: the name of the entity that will be calling the hook.
60 [2] The hook itself. A hook usually reflects some occurrence in the
62 life of the subject that other entities might care to know
63 about. A hook has a name, and may also have arguments. Hook
64 names are arbitrary strings. Each subject must document the
65 names and arguments of the hooks it can call.
66 [3] The name of the observer that wishes to receive the hook from
68 the subject.
69 [4] A command prefix to which the hook arguments will be appended
71 when the binding is executed.
72 SUBJECTS AND OBSERVERS
74 For convenience, this document collectively refers to subjects and
75 observers as objects, while placing no requirements on how these
76 objects are actually implemented. An object can be a TclOO or Snit or
77 XOTcl object, a Tcl command, a namespace, a module, a pseudo-object
78 managed by some other object (as tags are managed by the Tk text wid‐
79 get) or simply a well-known name.
80 Subject and observer names are arbitrary strings; however, as hook
82 might be used at the package level, it's necessary to have conventions
83 that avoid name collisions between packages written by different peo‐
84 ple.
85 Therefore, any subject or observer name used in core or package level
87 code should look like a Tcl command name, and should be defined in a
88 namespace owned by the package. Consider, for example, an ensemble com‐
89 mand ::foo that creates a set of pseudo-objects and uses hook to send
90 notifications. The pseudo-objects have names that are not commands and
91 exist in their own namespace, rather like file handles do. To avoid
92 name collisions with subjects defined by other packages, users of hook,
93 these ::foo handles should have names like ::foo::1, ::foo::2, and so
94 on.
95 Because object names are arbitrary strings, application code can use
97 whatever additional conventions are dictated by the needs of the appli‐
98 cation.
99
101 Hook provides the following commands:
102 hook bind ?subject? ?hook? ?observer? ?cmdPrefix?
104 This subcommand is used to create, update, delete, and query
105 hook bindings.
106 Called with no arguments it returns a list of the subjects with
108 hooks to which observers are currently bound.
109 Called with one argument, a subject, it returns a list of the
111 subject's hooks to which observers are currently bound.
112 Called with two arguments, a subject and a hook, it returns a
114 list of the observers which are currently bound to this subject
115 and hook.
116 Called with three arguments, a subject, a hook, and an observer,
118 it returns the binding proper, the command prefix to be called
119 when the hook is called, or the empty string if there is no such
120 binding.
121 Called with four arguments, it creates, updates, or deletes a
123 binding. If cmdPrefix is the empty string, it deletes any exist‐
124 ing binding for the subject, hook, and observer; nothing is
125 returned. Otherwise, cmdPrefix must be a command prefix taking
126 as many additional arguments as are documented for the subject
127 and hook. The binding is added or updated, and the observer is
128 returned.
129 If the observer is the empty string, "", it will create a new
131 binding using an automatically generated observer name of the
132 form ::hook::ob<number>. The automatically generated name will
133 be returned, and can be used to query, update, and delete the
134 binding as usual. If automated observer names are always used,
135 the observer name effectively becomes a unique binding ID.
136 It is possible to call hook bind to create or delete a binding
138 to a subject and hook while in an observer binding for that same
139 subject and hook. The following rules determine what happens
140 when
141 hook bind $s $h $o $binding
144 is called during the execution of
147 hook call $s $h
150 [1] No binding is ever called after it is deleted.
153 [2] When a binding is called, the most recently given command
155 prefix is always used.
156 [3] The set of observers whose bindings are to be called is
158 determined when this method begins to execute, and does
159 not change thereafter, except that deleted bindings are
160 not called.
161 In particular:
163 [1] If $os binding to $s and $h is deleted, and $os binding
165 has not yet been called during this execution of
166 hook call $s $h
169 it will not be called. (Note that it might already have
172 been called; and in all likelihood, it is probably delet‐
173 ing itself.)
174 [2] If $o changes the command prefix that's bound to $s and
176 $h, and if $os binding has not yet been called during
177 this execution of
178 hook call $s $h
181 the new binding will be called when the time comes. (But
184 again, it is probably $os binding that is is making the
185 change.)
186 [3] If a new observer is bound to $s and $h, its binding will
188 not be called until the next invocation of
189 hook call $s $h
192 hook call subject hook ?args...?
195 This command is called when the named subject wishes to call the
196 named hook. All relevant bindings are called with the specified
197 arguments in the global namespace. Note that the bindings are
198 called synchronously, before the command returns; this allows
199 the args to include references to entities that will be cleaned
200 up as soon as the hook has been called.
201 The order in which the bindings are called is not guaranteed. If
203 sequence among observers must be preserved, define one observer
204 and have its bindings call the other callbacks directly in the
205 proper sequence.
206 Because the hook mechanism is intended to support loose cou‐
208 pling, it is presumed that the subject has no knowledge of the
209 observers, nor any expectation regarding return values. This has
210 a number of implications:
211 [1] hook call returns the empty string.
213 [2] Normal return values from observer bindings are ignored.
215 [3] Errors and other exceptional returns propagate normally
217 by default. This will rarely be what is wanted, because
218 the subjects usually have no knowledge of the observers
219 and will therefore have no particular competence at han‐
220 dling their errors. That makes it an application issue,
221 and so applications will usually want to define an
222 -errorcommand.
223 If the -errorcommand configuration option has a non-empty value,
225 its value will be invoked for all errors and other exceptional
226 returns in observer bindings. See hook configure, below, for
227 more information on configuration options.
228 hook forget object
230 This command deletes any existing bindings in which the named
231 object appears as either the subject or the observer. Bindings
232 deleted by this method will never be called again. In particu‐
233 lar,
234 [1] If an observer is forgotten during a call to hook call,
236 any uncalled binding it might have had to the relevant
237 subject and hook will not be called subsequently.
238 [2] If a subject $s is forgotten during a call to
240 hook call $s $h
242 then hook call will return as soon as the current binding
244 returns. No further bindings will be called.
245 hook cget option
247 This command returns the value of one of the hook command's con‐
248 figuration options.
249 hook configure option value ...
251 This command sets the value of one or more of the hook command's
252 configuration options:
253 -errorcommand cmdPrefix
255 If the value of this option is the empty string, "", then
256 errors and other exception returns in binding scripts are
257 propagated normally. Otherwise, it must be a command pre‐
258 fix taking three additional arguments:
259 [1] a 4-element list {subject hook arglist observer},
261 [2] the result string, and
263 [3] the return options dictionary.
265 Given this information, the -errorcommand can choose to
267 log the error, call interp bgerror, delete the errant
268 binding (thus preventing the error from arising a second
269 time) and so forth.
270 -tracecommand cmdPrefix
272 The option's value should be a command prefix taking four
273 arguments:
274 [1] a subject,
276 [2] a hook,
278 [3] a list of the hook's argument values, and
280 [4] a list of objects the hook was called for.
282 The command will be called for each hook that is called.
284 This allows the application to trace hook execution for
285 debugging purposes.
286
288 The ::model module calls the <Update> hook in response to commands that
289 change the model's data:
290 hook call ::model <Update>
293 The .view megawidget displays the model state, and needs to know about
295 model updates. Consequently, it subscribes to the ::model's <Update>
296 hook.
297 hook bind ::model <Update> .view [list .view ModelUpdate]
300 When the ::model calls the hook, the .views ModelUpdate subcommand will
302 be called.
303 Later the .view megawidget is destroyed. In its destructor, it tells
305 the hook that it no longer exists:
306 hook forget .view
309 All bindings involving .view are deleted.
311
313 Hook has been designed and implemented by William H. Duquette.
314
316 This document, and the package it describes, will undoubtedly contain
317 bugs and other problems. Please report such in the category hook of
318 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
319 also report any ideas for enhancements you may have for either package
320 and/or documentation.
321 When proposing code changes, please provide unified diffs, i.e the out‐
323 put of diff -u.
324 Note further that attachments are strongly preferred over inlined
326 patches. Attachments can be made by going to the Edit form of the
327 ticket immediately after its creation, and then using the left-most
328 button in the secondary navigation bar.
329
331 uevent(n)
332
334 callback, event, hook, observer, producer, publisher, subject, sub‐
335 scriber, uevent
336
338 Programming tools
339
341 Copyright (c) 2010, by William H. Duquette
342tcllib 0.1 hook(n)