Class: EventBus

Inherits:
Object
  • Object
show all
Defined in:
lib/event_bus.rb,
lib/event_bus/registrations.rb

Defined Under Namespace

Classes: Registrations

Class Method Summary collapse

Class Method Details

.clear ⇒ Object

Delete all current listener registrations

Returns:

  • the EventBus, ready to be called again.



92
93
94
95
 
# File 'lib/event_bus.rb', line 92

def clear
  registrations.clear
  self
end

.on_error(&blk) ⇒ EventBus

Register a global error handler

The supplied block will be called once for each error that is raised by any listener, for any event.

The block will be provided with two parameters, the listener that errored, and the payload of the event.

Parameters:

  • blk —

    the block to be called when any unhandled error occurs in a listener

Returns:

  • (EventBus) —

    the EventBus, ready to be called again



82
83
84
85
 
# File 'lib/event_bus.rb', line 82

def on_error(&blk)
  registrations.on_error &blk
  self
end

.publish(event_name, payload = {}) ⇒ EventBus Also known as: announce, broadcast

Announce an event to any waiting listeners.

The event_name is added to the payload hash (with the key :event_name) before being passed on to listeners.

Parameters:

  • event_name (String, Symbol) —

    the name of your event

  • payload (Hash) (defaults to: {}) —

    the information you want to pass to the listeners

Returns:

  • (EventBus) —

    the EventBus, ready to be called again.



17
18
19
20
21
22
23
24
25
 
# File 'lib/event_bus.rb', line 17

def publish(event_name, payload = {})
  case event_name
  when Symbol, String
    registrations.announce(event_name, payload)
    self
  else
    raise ArgumentError.new('The event name must be a string or a symbol')
  end
end

.subscribe(pattern, listener = nil, method_name = nil, &blk) ⇒ EventBus Also known as: listen_for

Subscribe to a set of events.

If blk is supplied, it will be called with any event whose name matches pattern.

If no block is given, and if pattern is a String or a Regexp, a method will be called on listener whenever an event matching pattern occurs. In this case, if method_name is supplied the EventBus will look for, and call, a method of that name on listener; otherwise if method_name is not given, the EventBus will attempt to call a method whose name matches the event’s name.

Finally, if no block is given and pattern is not a String or a Regexp, then pattern is taken to be a listener object and the EventBus will attempt to call a method on it whose name matches the event’s name.

Either listener or blk must be provided, both never both.

When a matching event occurs, either the block is called or the method_name method on the listener object is called.

Parameters:

  • pattern (String, Regexp) —

    listen for any events whose name matches this pattern

  • listener (defaults to: nil) —

    the object to be notified when a matching event occurs

  • method_name (Symbol) (defaults to: nil) —

    the method to be called on listener when a matching event occurs

Returns:

  • (EventBus) —

    the EventBus, ready to be called again.



57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/event_bus.rb', line 57

def subscribe(pattern, listener = nil, method_name = nil, &blk)
  case pattern
  when Regexp, String, Symbol
    subscribe_pattern(pattern, listener, method_name, &blk)
  else
    raise ArgumentError.new('You cannot give two listeners') if listener || method_name
    raise ArgumentError.new('You cannot give both a listener and a block') if block_given?
    subscribe_obj(pattern)
  end
  self
end

.with_temporary_subscriber(pattern, listener = nil, method_name = nil) ⇒ EventBus

Adds a subscriber that only listens for the duration of the block. Mostly useful for testing event dispatching.

Parameters:

  • pattern (String, Regexp) —

    listen for any events whose name matches this pattern

  • listener (defaults to: nil) —

    the object to be notified when a matching event occurs

  • method_name (Symbol) (defaults to: nil) —

    the method to be called on listener when a matching event occurs

Returns:

  • (EventBus) —

    the EventBus, ready to be called again.



105
106
107
108
109
110
111
112
113
114
 
# File 'lib/event_bus.rb', line 105

def with_temporary_subscriber(pattern, listener = nil, method_name = nil)
  subscribe(pattern, listener, method_name)
  temporary_subscriber = registrations.last_subscriber

  yield

  self
ensure
  registrations.remove_subscriber(temporary_subscriber)
end