Module: Eventually

Defined in:
lib/eventually.rb,
lib/eventually/event.rb,
lib/eventually/version.rb,
lib/eventually/callable.rb,
lib/eventually/validation/arity.rb,
lib/eventually/validation/max_listeners.rb

Overview

Eventually is a module that facilitates evented callback management similar to the EventEmitter API in NodeJS. Simply include in the class you will be emitting events from and fire away.

Support exists for strict mode, pre-defining the events you plan on emitting, and arity validation on callbacks. See the docs below or the examples folder for further documentation.

Defined Under Namespace

Modules: ClassMethods, Validation Classes: Callable, Event

Constant Summary collapse

VERSION = 
"0.1.1"

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object 



16
17
18
19
 
# File 'lib/eventually.rb', line 16

def self.included(base)
  base.extend(ClassMethods)
  base.emits(:listener_added, :arity => 1)
end

Instance Method Details

#emit(evt_name, *payload) ⇒ Object

Emit the payload arguments back to the registered listeners on the given event. FIFO calling, and we won't deal with concurrency, so it should be handled at the callback level.

Usage: class Car include Eventually def stop #... emit(:stopped, 0) end end

car = Car.new car.on(:stopped) do |mph| puts 'the car stopped, sitting at %d mph' % mph end car.stop # this will indirectly invoke the above callback



173
174
175
176
177
178
 
# File 'lib/eventually.rb', line 173

def emit(evt_name, *payload)
  evt_name = evt_name.to_sym unless evt_name.is_a?(Symbol)
  event = get_event(evt_name)
  Eventually::Validation::Arity.new(evt_name, self, payload.length).raise_unless_valid!
  event.emit(*payload)
end

#emits?(evt) ⇒ Boolean

Check if this instance has pre-defined the given event as emittable. Simply calls the class method of the same name.

Returns:

  • (Boolean) 


123
124
125
 
# File 'lib/eventually.rb', line 123

def emits?(evt)
  self.class.emits?(evt)
end

#listeners(event) ⇒ Object

Report the number of registered listeners for the given event



186
187
188
 
# File 'lib/eventually.rb', line 186

def listeners(event)
  get_event(event).callables.map(&:callable)
end

#num_listeners ⇒ Object

Report the number of listeners across all registered events



181
182
183
 
# File 'lib/eventually.rb', line 181

def num_listeners
  _events.values.inject(0){|acc, evt| acc + evt.callables.size}
end

#on(evt_name, callable = nil, &blk) ⇒ Object

Event registration method. Takes an event to register against and either a callable object (e.g. proc/lambda/detached method) or a block

Usage: see Eventually#emit or examples directory



132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/eventually.rb', line 132

def on(evt_name, callable=nil, &blk)
  evt_name = evt_name.to_sym unless evt_name.is_a?(Symbol)
  
  cb = Eventually::Callable.new(callable, blk)
  Eventually::Validation::Arity.new(evt_name, self, cb.arity).raise_unless_valid!
  
  event = get_event(evt_name)
  event.add_callable(cb)
  emit(:listener_added, cb)
  
  Eventually::Validation::MaxListeners.new(self).warn_unless_valid!
  [event, cb]
end

#once(event, callable = nil, &blk) ⇒ Object

Event registration method which will remove the given callback after it is invoked. See Eventually#on for registration details.



148
149
150
151
152
 
# File 'lib/eventually.rb', line 148

def once(event, callable=nil, &blk)
  event, cb = on(event, callable, &blk)
  cb.availability = :once
  [event, cb]
end

#remove_all_listeners(event) ⇒ Object

Remove all listener callbacks for the given event



196
197
198
 
# File 'lib/eventually.rb', line 196

def remove_all_listeners(event)
  get_event(event).remove_all_callables
end

#remove_listener(event, cbk) ⇒ Object

Remove the given listener callback from the given event callback list



191
192
193
 
# File 'lib/eventually.rb', line 191

def remove_listener(event, cbk)
  get_event(event).remove_callable(cbk)
end