event_bus 0.0.4 → 0.1.0

data/Gemfile

@@ -1,4 +1,4 @@
-source :rubygems
+source 'https://rubygems.org'
 gemspec
 
 group :test do

data/Gemfile.lock

@@ -1,22 +1,22 @@
 PATH
   remote: .
   specs:
-    event_bus (0.0.3)
+    event_bus (0.0.4)
 
 GEM
-  remote: http://rubygems.org/
+  remote: https://rubygems.org/
   specs:
-    diff-lcs (1.1.3)
-    multi_json (1.5.0)
-    rake (10.0.3)
-    rspec (2.12.0)
-      rspec-core (~> 2.12.0)
-      rspec-expectations (~> 2.12.0)
-      rspec-mocks (~> 2.12.0)
-    rspec-core (2.12.2)
-    rspec-expectations (2.12.1)
-      diff-lcs (~> 1.1.3)
-    rspec-mocks (2.12.1)
+    diff-lcs (1.2.3)
+    multi_json (1.7.2)
+    rake (10.0.4)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.1)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.1)
     simplecov (0.7.1)
       multi_json (~> 1.0)
       simplecov-html (~> 0.7.1)

data/README.md

@@ -5,10 +5,12 @@ A simple pubsub event bus for Ruby applications.
 [![Build Status](https://travis-ci.org/kevinrutherford/event_bus.png)](https://travis-ci.org/kevinrutherford/event_bus)
 [![Dependency
 Status](https://gemnasium.com/kevinrutherford/event_bus.png)](https://gemnasium.com/kevinrutherford/event_bus)
+[![Code
+Climate](https://codeclimate.com/github/kevinrutherford/event_bus.png)](https://codeclimate.com/github/kevinrutherford/event_bus)
 
-* <https://rubygems.org/gems/event_bus>
-* <http://rubydoc.info/gems/event_bus/frames>
-* <https://github.com/kevinrutherford/event_bus>
+* Gem: <https://rubygems.org/gems/event_bus>
+* API docs: <http://rubydoc.info/gems/event_bus/frames>
+* Source code: <https://github.com/kevinrutherford/event_bus>
 
 ## Features
 
@@ -17,6 +19,7 @@ Status](https://gemnasium.com/kevinrutherford/event_bus.png)](https://gemnasium.
 * Listen for events without coupling to the publishing object or class.
 * Subscribe to events using names or regex patterns.
 * Works with Rails.
+* Works without Rails.
 
 ## Installation
 
@@ -34,44 +37,93 @@ gem 'event_bus'
 
 ## Usage
 
-Subscribe to an event in your application's initialization code:
+### Publishing events
 
-```ruby
-EventBus.subscribe('order-placed', StatsRecorder.new, :order_placed)
-```
+Publish events whenever something significant happens in your application:
 
 ```ruby
-class StatsRecorder
-  def order_placed(details)
-    order = details[:order]
-    //...
-  end
+class PlaceOrder
+  //...
+  EventBus.announce(:order_placed, order: current_order, customer: current_user)
 end
 ```
 
-Or subscribe a block:
+The event name (first argument) can be a String or a Symbol.
+The Hash is optional and supplies a payload of information to any subscribers.
 
-```ruby
-EventBus.subscribe('order-placed') do |details|
-  order = details[:order]
-  //...
-end
-```
+(If you don't like the method name `announce` you can use `publish` or
+`broadcast` instead.)
 
-Fire the event whenever something significant happens in your application:
+### Subscribing to events
 
-```ruby
-class PlaceOrder
-  //...
-  EventBus.announce('order-placed', :order => current_order, :customer => current_user)
-end
-```
+There are three ways to subscribe to events.
+
+1. Subscribe a listener object:
+
+    ```ruby
+    EventBus.subscribe(StatsRecorder.new)
+    ```
+
+    The event will be handled by a method whose name matches the event name:
+
+    ```ruby
+    class StatsRecorder
+      def order_placed(payload)
+        order = payload[:order]
+        //...
+      end
+    end
+    ```
+
+    If the object has no matching method, it doesn't receive the event.
+
+2. Specify the method to be called when the event fires:
+
+    ```ruby
+    EventBus.subscribe(:order_placed, StatsRecorder.new, :print_order)
+    ```
+
+    In this case the event will be handled by the `print_order` method:
+
+    ```ruby
+    class StatsRecorder
+      def print_order(payload)
+        order = payload[:order]
+        //...
+      end
+    end
+    ```
+
+    The first argument to `subscribe` can be a String,
+    a Symbol or a Regexp:
+
+    ```ruby
+    EventBus.subscribe(/order/, StatsRecorder.new, :print_order)
+    ```
+
+3. Subscribe a block:
+
+    ```ruby
+    EventBus.subscribe(:order_placed) do |payload|
+      order = payload[:order]
+      //...
+    end
+    ```
+
+    The argument to `subscribe` can be a String, a Symbol or a Regexp:
+
+    ```ruby
+    EventBus.subscribe(/order/) do |payload|
+      order = payload[:order]
+      //...
+    end
+    ```
 
 See the specs for more detailed usage scenarios.
 
 ## Compatibility
 
-Tested with Ruby 1.8.7, 1.9.x, JRuby, Rubinius.
+Tested with Ruby 1.9.x, JRuby, Rubinius.
 See the [build status](https://travis-ci.org/kevinrutherford/event_bus)
 for details.
 

data/lib/event_bus.rb

@@ -1,4 +1,4 @@
-require 'singleton'
+require_relative 'event_bus/registrations'
 
 class EventBus
 
@@ -7,37 +7,61 @@ class EventBus
     #
     # Announce an event to any waiting listeners.
     #
-    # The +event_name+ is added to the +details+ hash (with the key +:event_name+)
-    # before the event is passed on to listeners.
+    # The +event_name+ is added to the +payload+ hash (with the key +:event_name+)
+    # before being passed on to listeners.
     #
     # @param event_name [String, Symbol] the name of your event
-    # @param details [Hash] the information you want to pass to the listeners
-    # @return the EventBus, ready to be called again.
+    # @param payload [Hash] the information you want to pass to the listeners
+    # @return [EventBus] the EventBus, ready to be called again.
     #
-    def publish(event_name, details = {})
-      registrations.announce(event_name, details)
-      self
+    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
 
     alias :announce :publish
     alias :broadcast :publish
 
     #
-    # Register a single listener.
+    # 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.
     #
-    # @param pattern [String, Regex] listen for any events whose name matches this pattern
+    # 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.
+    #
+    # @param pattern [String, Regexp] listen for any events whose name matches this pattern
     # @param listener the object to be notified when a matching event occurs
     # @param method_name [Symbol] the method to be called on +listener+ when a matching event occurs
-    # @return the EventBus, ready to be called again.
+    # @return [EventBus] the EventBus, ready to be called again.
     #
     def subscribe(pattern, listener = nil, method_name = nil, &blk)
-      if listener
-        raise ArgumentError.new('You cannot give both a listener and a block') if block_given?
-        raise ArgumentError.new('You must supply a method name') unless method_name
-        registrations.add_method(pattern, listener, method_name)
+      case pattern
+      when Regexp, String
+        subscribe_pattern(pattern, listener, method_name, &blk)
       else
-        raise ArgumentError.new('You must provide a listener or a block') unless block_given?
-        registrations.add_block(pattern, blk)
+        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
@@ -66,58 +90,26 @@ class EventBus
 
     private
 
-    def registrations
-      Registrations.instance
-    end
-
-  end
-
-  class Registrations
-    include Singleton
-
-    def initialize
-      clear
-    end
-
-    def announce(event_name, details)
-      info = {:event_name => event_name}.merge(details)
-      @listeners.each do |listener|
-        listener.respond(event_name, info)
-      end
-    end
-
-    def clear
-      @listeners = []
-    end
-
-    def add(pattern, listener, method_name, &blk)
+    def subscribe_pattern(pattern, listener, method_name, &blk)
       if listener
-        add_method(pattern, listener, method_name)
+        raise ArgumentError.new('You cannot give both a listener and a block') if block_given?
+        raise ArgumentError.new('You must supply a method name') unless method_name
+        registrations.add_method(pattern, listener, method_name)
       else
-        add_block(pattern, blk)
+        raise ArgumentError.new('You must provide a listener or a block') unless block_given?
+        registrations.add_block(pattern, &blk)
       end
     end
 
-    def add_method(pattern, listener, method_name)
-      @listeners << Registration.new(pattern, listener, method_name)
-    end
-
-    def add_block(pattern, blk)
-      @listeners << BlockRegistration.new(pattern, blk)
-    end
-
-    private
-
-    Registration = Struct.new(:pattern, :listener, :method_name) do
-      def respond(event_name, details)
-        listener.send(method_name, details) if pattern === event_name
+    def subscribe_obj(listener)
+      registrations.add_block(/.*/) do |payload|
+        method = payload[:event_name].to_sym
+        listener.send(method, payload) if listener.respond_to?(method)
       end
     end
 
-    BlockRegistration = Struct.new(:pattern, :block) do
-      def respond(event_name, details)
-        block.call(details) if pattern === event_name
-      end
+    def registrations
+      Registrations.instance
     end
 
   end

data/lib/event_bus/registrations.rb

@@ -0,0 +1,58 @@
+require 'singleton'
+
+class EventBus
+
+  private
+
+  class Registrations
+    include Singleton
+
+    def initialize
+      clear
+    end
+
+    def announce(event_name, payload)
+      full_payload = {event_name: event_name}.merge(payload)
+      @listeners.each do |listener|
+        listener.respond(event_name, full_payload)
+      end
+    end
+
+    def clear
+      @listeners = []
+    end
+
+    def add(pattern, listener, method_name, &blk)
+      if listener
+        add_method(pattern, listener, method_name)
+      else
+        add_block(pattern, blk)
+      end
+    end
+
+    def add_method(pattern, listener, method_name)
+      @listeners << Registration.new(pattern, listener, method_name)
+    end
+
+    def add_block(pattern, &blk)
+      @listeners << BlockRegistration.new(pattern, blk)
+    end
+
+    private
+
+    Registration = Struct.new(:pattern, :listener, :method_name) do
+      def respond(event_name, payload)
+        listener.send(method_name, payload) if pattern === event_name
+      end
+    end
+
+    BlockRegistration = Struct.new(:pattern, :block) do
+      def respond(event_name, payload)
+        block.call(payload) if pattern === event_name
+      end
+    end
+
+  end
+
+end
+

data/spec/lib/event_bus_spec.rb

@@ -9,93 +9,138 @@ describe EventBus do
     EventBus.clear
   end
 
-  describe '.publish' do
+  describe 'publishing' do
+
+    it 'accepts a string for the event name' do
+      EventBus.subscribe(/#{event_name}/, listener, receiving_method)
+      listener.should_receive(receiving_method).with(event_name: event_name)
+      EventBus.publish(event_name)
+    end
+
+    it 'accepts a symbol for the event name' do
+      event_sym = :abc_123
+      EventBus.subscribe(/#{event_sym}/, listener, receiving_method)
+      listener.should_receive(receiving_method).with(event_name: event_sym)
+      EventBus.publish(event_sym)
+    end
+
+    it 'rejects any other type as the event name' do
+      expect { EventBus.publish(123) }.to raise_error(ArgumentError)
+    end
 
     it 'returns itself, to facilitate cascades' do
       EventBus.publish(event_name, {}).should == EventBus
     end
 
-    it 'passes the event name in the details hash' do
+    it 'adds the event name to the payload' do
       EventBus.subscribe(event_name, listener, receiving_method)
-      listener.should_receive(receiving_method).with(:event_name => event_name)
-      EventBus.publish(event_name, {})
+      listener.should_receive(receiving_method).with(event_name: event_name, a: 56)
+      EventBus.publish(event_name, a: 56)
     end
 
-    it 'allows the details hash to be omitted' do
+    it 'allows the payload to be omitted' do
       EventBus.subscribe(event_name, listener, receiving_method)
-      listener.should_receive(receiving_method).with(:event_name => event_name)
+      listener.should_receive(receiving_method).with(event_name: event_name)
       EventBus.publish(event_name)
     end
 
   end
 
-  describe '.subscribe' do
+  describe 'subscribing' do
 
     it 'returns itself, to facilitate cascades' do
       EventBus.subscribe(event_name, listener, receiving_method).should == EventBus
     end
 
-    context 'accepts a string event name' do
+    context 'with a regex pattern' do
       it 'sends the event to a matching listener' do
-        EventBus.subscribe(event_name, listener, receiving_method)
-        listener.should_receive(receiving_method).with(:a => 1, :b => 2, :event_name => event_name)
-        EventBus.publish(event_name, :a => 1, :b => 2)
+        EventBus.subscribe(/123b/, listener, receiving_method)
+        listener.should_receive(receiving_method).with(a: 1, b: 2, event_name: event_name)
+        EventBus.publish(event_name, a: 1, b: 2)
       end
 
       it 'does not send the event to non-matching listeners' do
-        EventBus.subscribe('blah', listener, receiving_method)
+        EventBus.subscribe(/123a/, listener, receiving_method)
         listener.should_not_receive(receiving_method)
-        EventBus.publish(event_name, :a => 1, :b => 2, :event_name => event_name)
+        EventBus.publish(event_name, a: 1, b: 2, event_name: event_name)
       end
     end
 
-    context 'accepts a regex event name' do
+    context 'with a string pattern' do
       it 'sends the event to a matching listener' do
-        EventBus.subscribe(/123b/, listener, receiving_method)
-        listener.should_receive(receiving_method).with(:a => 1, :b => 2, :event_name => event_name)
-        EventBus.publish(event_name, :a => 1, :b => 2)
+        EventBus.subscribe(event_name, listener, receiving_method)
+        listener.should_receive(receiving_method).with(a: 1, b: 2, event_name: event_name)
+        EventBus.publish(event_name, a: 1, b: 2)
       end
 
       it 'does not send the event to non-matching listeners' do
-        EventBus.subscribe(/123a/, listener, receiving_method)
+        EventBus.subscribe('blah', listener, receiving_method)
         listener.should_not_receive(receiving_method)
-        EventBus.publish(event_name, :a => 1, :b => 2, :event_name => event_name)
+        EventBus.publish(event_name, a: 1, b: 2, event_name: event_name)
+      end
+    end
+
+    context 'with a listener method' do
+      it 'will not accept a block too' do
+        expect { EventBus.subscribe('blah', listener, receiving_method) {|info| }}.to raise_error(ArgumentError)
+      end
+
+      it 'expects a method name' do
+        expect { EventBus.subscribe('blah', listener) }.to raise_error(ArgumentError)
       end
     end
 
-    context 'can take a block or a receiver' do
+    context 'with a block' do
+      it 'requires a block when no listener method is supplied' do
+        expect { EventBus.subscribe('blah') }.to raise_error(ArgumentError)
+      end
+
       it 'calls the block when the event matches' do
         block_called = false
         EventBus.subscribe(event_name) do |info|
           block_called = true
-          info.should == {:a => 1, :b => 2, :event_name => event_name}
+          info.should == {a: 1, b: 2, event_name: event_name}
         end
-        EventBus.publish(event_name, :a => 1, :b => 2)
+        EventBus.publish(event_name, a: 1, b: 2)
         block_called.should be_true
       end
 
       it 'does not call the block when the event does not match' do
         block_called = false
         EventBus.subscribe('blah') {|_| block_called = true }
-        EventBus.publish(event_name, :a => 1, :b => 2)
+        EventBus.publish(event_name)
         block_called.should be_false
       end
     end
 
-    context 'listener variant' do
-      it 'will not accept a block too' do
-        expect { EventBus.subscribe('blah', listener, receiving_method) {|info| }}.to raise_error(ArgumentError)
+    context 'with a listener object' do
+
+      it 'calls a listener method whose name matches the event name' do
+        listener.should_receive(:a_method).with(a: 2, b: 3, event_name: 'a_method')
+        EventBus.subscribe(listener)
+        EventBus.publish('a_method', a: 2, b: 3)
       end
 
-      it 'expects a method name' do
-        expect { EventBus.subscribe('blah', listener)}.to raise_error(ArgumentError)
+      it 'calls a listener method with symbol whose name matches the event name' do
+        listener.should_receive(:a_method).with(a: 2, b: 3, event_name: :a_method)
+        EventBus.subscribe(listener)
+        EventBus.publish(:a_method, a: 2, b: 3)
       end
-    end
 
-    context 'block variant' do
-      it 'requires a block when no listener method is supplied' do
-        expect { EventBus.subscribe('blah')}.to raise_error(ArgumentError)
+      it 'calls no method when there is no name match' do
+        listener.should_not_receive(:a_method)
+        EventBus.subscribe(listener)
+        EventBus.publish('b_method')
       end
+
+      it 'will not accept other arguments' do
+        expect { EventBus.subscribe(listener, double) }.to raise_error(ArgumentError)
+      end
+
+      it 'will not accept a block' do
+        expect { EventBus.subscribe(listener) {|info| }}.to raise_error(ArgumentError)
+      end
+
     end
 
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: event_bus
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-27 00:00:00.000000000 Z
+date: 2013-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -73,6 +73,7 @@ files:
 - README.md
 - Rakefile
 - lib/event_bus.rb
+- lib/event_bus/registrations.rb
 - spec/lib/event_bus_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/kevinrutherford/event_bus