Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 126 lines (88 sloc) 3.291 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
61 ### Watching Once
62
63 Only want to be notified the first time something happens? `once` is
64 like `on`, but fickle.
65
66 ```ruby
67 frob = Frob.new
68
69 frob.on :twiddle do
70 p :twiddled!
71 end
72
73 frob.fire :twiddle
74 frob.fire :twiddle
75 ```
76
77 #### Result
78
79 :twiddled!
80
81 ### Unwatching
82
83 Specific blocks or callable objects can be removed from an event's
84 watchers, or all the event's watchers can be removed.
85
86 ```ruby
87 b = lambda {}
88 frob = Frob.new
89
90 frob.on :twiddle, &b
91
92 frob.off :twiddle, b # removes the 'b' watcher, same as frob.off :twiddle, &b
93 frob.off :twiddle # removes all watchers for the 'twiddle' event
94 ```
95
96 ## Compatibility
97
98 Watchable is actively developed against MRI Ruby 1.8.7 as a least common
99 denominator, but is widely tested against other Ruby versions and
100 implementations. Check the [travis-ci][] page for details.
101
102 [travis-ci]: http://travis-ci.org/jbarnette/watchable
103
104 ## License (MIT)
105
106 Copyright 2012 John Barnette (john@jbarnette.com)
107
108 Permission is hereby granted, free of charge, to any person obtaining
109 a copy of this software and associated documentation files (the
110 'Software'), to deal in the Software without restriction, including
111 without limitation the rights to use, copy, modify, merge, publish,
112 distribute, sublicense, and/or sell copies of the Software, and to
113 permit persons to whom the Software is furnished to do so, subject to
114 the following conditions:
115
116 The above copyright notice and this permission notice shall be
117 included in all copies or substantial portions of the Software.
118
119 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
120 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
121 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
122 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
123 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
124 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
125 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.