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.0"

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



167
168
169
170
171
172
 
# File 'lib/eventually.rb', line 167

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

#listeners(event) ⇒ Object

Report the number of registered listeners for the given event



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

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

#num_listeners ⇒ Object

Report the number of listeners across all registered events



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

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



126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/eventually.rb', line 126

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.



142
143
144
145
146
 
# File 'lib/eventually.rb', line 142

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



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

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



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

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