Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 145 lines (100 sloc) 3.588 kB
fab64a2 @jbarnette Spike.
authored
1 [![Build Status](https://secure.travis-ci.org/jbarnette/watchable.png)](http://travis-ci.org/jbarnette/watchable)
2
3 # Watchable
4
5 A simple event/notification mixin, reluctantly extracted to a gem.
6 This is code I've had floating around for a few years now, but I've
7 also incorporated a few extras from node.js' [EventEmitter][ee],
8 [jQuery][jq], and [Backbone.Events][be].
9
10 [ee]: http://nodejs.org/api/events.html#events_class_events_eventemitter
11 [jq]: http://api.jquery.com/on
12 [be]: http://documentcloud.github.com/backbone/#Events
13
14 ## Example
15
16 ### Fixtures
17
18 ```ruby
19 require "watchable"
20
21 class Frob
22 include Watchable
23 end
24
25 class Callable
26 def call *args
27 p :called! => args
28 end
29 end
30
31 ```
32
33 ### Watching and Firing
34
35 Events can have any number of watchers. Each watcher will be called
36 in order, and any args provided when the event is fired will be passed
37 along. Watchers will most commonly be blocks, but any object that
38 responds to `call` can be used instead.
39
40 ```ruby
41 frob = Frob.new
42
43 frob.on :twiddle do |name|
44 puts "#{name} twiddled the frob!"
45 end
46
47 frob.on :twiddle do |name|
48 puts "(not that there's anything wrong with that)"
49 end
50
51 frob.on :twiddle, Callable.new
52 frob.fire :twiddle, "John"
53 ```
54
55 #### Result
56
57 John twiddled the frob!
58 (not that there's anything wrong with that)
59 { :called! => ["John"] }
60
f6390fa @jbarnette Support :all.
authored
61 ### Watching Everything
62
63 Want to see every event? Register for `:all`. The first argument will
64 be the name of the fired event.
65
66 ```ruby
67 frob = Frob.new
68
69 frob.on :all do |event, culprit|
70 p :fired => [event, culprit]
71 end
72
73 frob.fire :foo, "John"
74 ```
75
76 #### Result
77
78 {:fired => [:foo, "John"]}
79
fab64a2 @jbarnette Spike.
authored
80 ### Watching Once
81
82 Only want to be notified the first time something happens? `once` is
83 like `on`, but fickle.
84
85 ```ruby
86 frob = Frob.new
87
578332b @jbarnette Typo.
authored
88 frob.once :twiddle do
fab64a2 @jbarnette Spike.
authored
89 p :twiddled!
90 end
91
92 frob.fire :twiddle
93 frob.fire :twiddle
94 ```
95
96 #### Result
97
98 :twiddled!
99
100 ### Unwatching
101
102 Specific blocks or callable objects can be removed from an event's
103 watchers, or all the event's watchers can be removed.
104
105 ```ruby
106 b = lambda {}
107 frob = Frob.new
108
109 frob.on :twiddle, &b
110
111 frob.off :twiddle, b # removes the 'b' watcher, same as frob.off :twiddle, &b
112 frob.off :twiddle # removes all watchers for the 'twiddle' event
113 ```
114
115 ## Compatibility
116
117 Watchable is actively developed against MRI Ruby 1.8.7 as a least common
118 denominator, but is widely tested against other Ruby versions and
119 implementations. Check the [travis-ci][] page for details.
120
121 [travis-ci]: http://travis-ci.org/jbarnette/watchable
122
123 ## License (MIT)
124
125 Copyright 2012 John Barnette (john@jbarnette.com)
126
127 Permission is hereby granted, free of charge, to any person obtaining
128 a copy of this software and associated documentation files (the
129 'Software'), to deal in the Software without restriction, including
130 without limitation the rights to use, copy, modify, merge, publish,
131 distribute, sublicense, and/or sell copies of the Software, and to
132 permit persons to whom the Software is furnished to do so, subject to
133 the following conditions:
134
135 The above copyright notice and this permission notice shall be
136 included in all copies or substantial portions of the Software.
137
138 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
139 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
140 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
141 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
142 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
143 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
144 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.