class Pokan::EventHandler

EventHandler is a class that associate blocks with events, making it possible to emit events and executing all the related callbacks (sequentially, in the order they were registered).

Usage

e = EventHandler.new
e.register(:my_event) { puts 'oh my!' }
e.events                     #=> [:my_event]
e.subscribers(:my_event)     #=> Proc array with callbacks
e.emit(:my_event)            #=> 'oh my!' is printed

Public Class Methods

new() click to toggle source

creates a new instance of EventHandler, ready for event registrations

# File lib/pokan/event_handler.rb, line 22
def initialize
  @callbacks = {}
end

Public Instance Methods

emit(event, options = {}) click to toggle source

Emits the given event, thus calling all the registered callbacks up to that point. If there are no registered callbacks for the event passed, nothing is done.

If the registered callbacks expected parameters, pass them using the with option

 e = EventHandler.new
 e.register(:awesome) { puts 'awesome!' }
 e.register(:awesome) { puts 'not that awesome...' }
 e.emit(:awesome)    #=> messages are print

Using the +with+ option:

 e = EventHandler.new
 e.register(:awesome) { |msg| puts msg }
 e.emit(:awesome, :with => ['awesome!']) #=> 'awesome!' is print
# File lib/pokan/event_handler.rb, line 88
def emit(event, options = {})
  raise_unless_symbol(event)

  args = options[:with] || []
  
  if @callbacks.has_key? event
    @callbacks[event].each { |c| c.call(*args) }
  end

  self
end
events() click to toggle source

Retrieves the names of all the events for which there is at least one associated callback

# File lib/pokan/event_handler.rb, line 49
def events
  @callbacks.keys
end
register(event, &block) click to toggle source

register is the method used to associate a block with an event. The event name must be passed as a symbol, otherwise an exception is raised. You can call register on the same event any number of times, but it is important to note that the blocks associated will be called in the same order they were registered.

e = EventHandler.new
e.register(:my_event) { puts 'my event' }.register(:my_event) { puts 'is cool!' }
# File lib/pokan/event_handler.rb, line 36
def register(event, &block)
  raise_unless_symbol(event)

  raise NoBlockGivenError, 'must provide a block' unless block_given?

  initialize_callbacks_for(event)
  @callbacks[event] << block
  self
end
reset(event) click to toggle source

Removes all the callbacks registered with event

# File lib/pokan/event_handler.rb, line 63
def reset(event)
  raise_unless_symbol(event)

  @callbacks.delete(event)
  self
end
subscribers(event) click to toggle source

Returns an array with all the Proc objects for callbacks registered for the given event

# File lib/pokan/event_handler.rb, line 56
def subscribers(event)
  raise_unless_symbol(event)

  @callbacks[event] || []
end

Private Instance Methods

initialize_callbacks_for(event) click to toggle source

If there hasn’t been any callback registered to event, create a new list for it

# File lib/pokan/event_handler.rb, line 108
def initialize_callbacks_for(event)
  @callbacks[event] ||= []
end
raise_unless_symbol(event) click to toggle source

Raises an ArgumentError if the given parameter is not a symbol

# File lib/pokan/event_handler.rb, line 103
def raise_unless_symbol(event)
  raise ArgumentError, 'event name must be passed as a symbol' unless event.is_a? Symbol
end