1hook(n)                              Hooks                             hook(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       hook - Hooks
9

SYNOPSIS

11       package require Tcl  8.5
12
13       package require hook  ?0.2?
14
15       hook bind ?subject? ?hook? ?observer? ?cmdPrefix?
16
17       hook call subject hook ?args...?
18
19       hook forget object
20
21       hook cget option
22
23       hook configure option value ...
24
25______________________________________________________________________________
26

DESCRIPTION

28       This  package  provides the hook ensemble command, which implements the
29       Subject/Observer pattern. It allows subjects, which may be modules, ob‐
30       jects,  widgets, and so forth, to synchronously call hooks which may be
31       bound to an arbitrary number of subscribers, called observers.  A  sub‐
32       ject may call any number of distinct hooks, and any number of observers
33       can bind callbacks to a particular hook called by a particular subject.
34       Hook bindings can be queried and deleted.
35
36       This man page is intended to be a reference only.
37

CONCEPTS

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 re‐
44       ceiving the notification.
45
46       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  im‐
52       plementing loose coupling of this kind. This package defines a new com‐
53       mand, hook, which implements just such a mechanism.
54
55   BINDINGS
56       The hook command manages a collection of hook bindings. A hook  binding
57       has four elements:
58
59       [1]    A subject: the name of the entity that will be calling the hook.
60
61       [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
67       [3]    The  name  of  the observer that wishes to receive the hook from
68              the subject.
69
70       [4]    A command prefix to which the hook arguments  will  be  appended
71              when the binding is executed.
72
73   SUBJECTS AND OBSERVERS
74       For  convenience, this document collectively refers to subjects and ob‐
75       servers as objects, while placing no requirements on how these  objects
76       are actually implemented. An object can be a TclOO or Snit or XOTcl ob‐
77       ject, a Tcl command, a namespace, a module, a pseudo-object managed  by
78       some other object (as tags are managed by the Tk text widget) or simply
79       a well-known name.
80
81       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
86       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
96       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

REFERENCE

101       Hook provides the following commands:
102
103       hook bind ?subject? ?hook? ?observer? ?cmdPrefix?
104              This  subcommand  is  used  to create, update, delete, and query
105              hook bindings.
106
107              Called with no arguments it returns a list of the subjects  with
108              hooks to which observers are currently bound.
109
110              Called  with  one  argument, a subject, it returns a list of the
111              subject's hooks to which observers are currently bound.
112
113              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
117              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
122              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 re‐
125              turned. Otherwise, cmdPrefix must be a command prefix taking  as
126              many  additional arguments as are documented for the subject and
127              hook. The binding is added or updated, and the observer  is  re‐
128              turned.
129
130              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
137              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
142
143                  hook bind $s $h $o $binding
144
145
146              is called during the execution of
147
148
149                  hook call $s $h
150
151
152              [1]    No binding is ever called after it is deleted.
153
154              [2]    When a binding is called, the most recently given command
155                     prefix is always used.
156
157              [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
162              In particular:
163
164              [1]    If  $os  binding to $s and $h is deleted, and $os binding
165                     has not yet been called during this execution of
166
167
168                         hook call $s $h
169
170
171                     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
175              [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
179
180                         hook call $s $h
181
182
183                     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
187              [3]    If a new observer is bound to $s and $h, its binding will
188                     not be called until the next invocation of
189
190
191                         hook call $s $h
192
193
194       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
202              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
207              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
212              [1]    hook call returns the empty string.
213
214              [2]    Normal return values from observer bindings are ignored.
215
216              [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 -er‐
222                     rorcommand.
223
224              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
229       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
235              [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
239              [2]    If a subject $s is forgotten during a call to
240
241                     hook call $s $h
242
243                     then hook call will return as soon as the current binding
244                     returns.  No further bindings will be called.
245
246       hook cget option
247              This command returns the value of one of the hook command's con‐
248              figuration options.
249
250       hook configure option value ...
251              This command sets the value of one or more of the hook command's
252              configuration options:
253
254              -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
260                     [1]    a 4-element list {subject hook arglist observer},
261
262                     [2]    the result string, and
263
264                     [3]    the return options dictionary.
265
266                     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
271              -tracecommand cmdPrefix
272                     The option's value should be a command prefix taking four
273                     arguments:
274
275                     [1]    a subject,
276
277                     [2]    a hook,
278
279                     [3]    a list of the hook's argument values, and
280
281                     [4]    a list of objects the hook was called for.
282
283                     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

EXAMPLE

288       The ::model module calls the <Update> hook in response to commands that
289       change the model's data:
290
291
292                   hook call ::model <Update>
293
294       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
298
299                   hook bind ::model <Update> .view [list .view ModelUpdate]
300
301       When the ::model calls the hook, the .views ModelUpdate subcommand will
302       be called.
303
304       Later the .view megawidget is destroyed. In its  destructor,  it  tells
305       the hook that it no longer exists:
306
307
308                   hook forget .view
309
310       All bindings involving .view are deleted.
311

CREDITS

313       Hook has been designed and implemented by William H. Duquette.
314

BUGS, IDEAS, FEEDBACK

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
322       When proposing code changes, please provide unified diffs, i.e the out‐
323       put of diff -u.
324
325       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

SEE ALSO

331       uevent(n)
332

KEYWORDS

334       callback,  event,  hook,  observer,  producer, publisher, subject, sub‐
335       scriber, uevent
336

CATEGORY

338       Programming tools
339
341       Copyright (c) 2010, by William H. Duquette
342
343
344
345
346tcllib                                0.2                              hook(n)
Impressum