event_bus 0.0.3 → 0.0.4

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/Gemfile

@@ -3,7 +3,7 @@ gemspec
 
 group :test do
   gem 'rspec', '~> 2.12'
-  gem 'rake', '~> 0.9.2'
+  gem 'rake', '~> 10.0.1'
   gem 'simplecov', :require => false
 end
 

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    event_bus (0.0.2)
+    event_bus (0.0.3)
 
 GEM
   remote: http://rubygems.org/
   specs:
     diff-lcs (1.1.3)
     multi_json (1.5.0)
-    rake (0.9.2.2)
+    rake (10.0.3)
     rspec (2.12.0)
       rspec-core (~> 2.12.0)
       rspec-expectations (~> 2.12.0)
@@ -27,6 +27,6 @@ PLATFORMS
 
 DEPENDENCIES
   event_bus!
-  rake (~> 0.9.2)
+  rake (~> 10.0.1)
   rspec (~> 2.12)
   simplecov

data/README.md

@@ -3,6 +3,8 @@
 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)
 
 * <https://rubygems.org/gems/event_bus>
 * <http://rubydoc.info/gems/event_bus/frames>
@@ -35,29 +37,38 @@ gem 'event_bus'
 Subscribe to an event in your application's initialization code:
 
 ```ruby
-EventBus.listen_for('order-placed', StatsRecorder.new, :order_placed)
+EventBus.subscribe('order-placed', StatsRecorder.new, :order_placed)
 ```
 
-Fire the event whenever something significant happens in your application:
+```ruby
+class StatsRecorder
+  def order_placed(details)
+    order = details[:order]
+    //...
+  end
+end
+```
+
+Or subscribe a block:
 
 ```ruby
-class PlaceOrder
+EventBus.subscribe('order-placed') do |details|
+  order = details[:order]
   //...
-  EventBus.listen_for('order-placed', :order => current_order, :customer => current_user)
 end
 ```
 
-Handle the event without coupling the publisher or subscriber:
+Fire the event 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
 ```
 
+See the specs for more detailed usage scenarios.
+
 ## Compatibility
 
 Tested with Ruby 1.8.7, 1.9.x, JRuby, Rubinius.

data/lib/event_bus.rb

@@ -2,52 +2,75 @@ require 'singleton'
 
 class EventBus
 
-  #
-  # Announce an event to any waiting 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.
-  #
-  def self.announce(event_name, details)
-    Registrations.instance.announce(event_name, details)
-    self
-  end
+  class << self
+
+    #
+    # 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.
+    #
+    # @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.
+    #
+    def publish(event_name, details = {})
+      registrations.announce(event_name, details)
+      self
+    end
 
-  #
-  # Register a single listener.
-  #
-  # @param pattern [String, Regex] 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.
-  #
-  def self.listen_for(pattern, listener, method_name)
-    Registrations.instance.register(pattern, listener, method_name)
-    self
-  end
+    alias :announce :publish
+    alias :broadcast :publish
+
+    #
+    # Register a single listener.
+    #
+    # @param pattern [String, Regex] 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.
+    #
+    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)
+      else
+        raise ArgumentError.new('You must provide a listener or a block') unless block_given?
+        registrations.add_block(pattern, blk)
+      end
+      self
+    end
 
-  #
-  # Delete all current listener registrations
-  #
-  # @return the EventBus, ready to be called again.
-  #
-  def self.clear
-    Registrations.instance.clear
-    self
-  end
+    alias :listen_for :subscribe
 
-  #
-  # (experimental)
-  #
-  def self.register(listener)
-    listener.events_map.each do |pattern, method_name|
-      Registrations.instance.register(pattern, listener, method_name)
+    #
+    # Delete all current listener registrations
+    #
+    # @return the EventBus, ready to be called again.
+    #
+    def clear
+      registrations.clear
+      self
+    end
+
+    #
+    # (experimental)
+    #
+    def register(listener)
+      listener.events_map.each do |pattern, method_name|
+        registrations.add(pattern, listener, method_name)
+      end
+      self
     end
-    self
-  end
 
-  private
+    private
+
+    def registrations
+      Registrations.instance
+    end
+
+  end
 
   class Registrations
     include Singleton
@@ -57,8 +80,9 @@ class EventBus
     end
 
     def announce(event_name, details)
+      info = {:event_name => event_name}.merge(details)
       @listeners.each do |listener|
-        listener.respond(event_name, details)
+        listener.respond(event_name, info)
       end
     end
 
@@ -66,10 +90,22 @@ class EventBus
       @listeners = []
     end
 
-    def register(pattern, listener, method_name)
+    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
@@ -78,6 +114,12 @@ class EventBus
       end
     end
 
+    BlockRegistration = Struct.new(:pattern, :block) do
+      def respond(event_name, details)
+        block.call(details) if pattern === event_name
+      end
+    end
+
   end
 
 end

data/spec/lib/event_bus_spec.rb

@@ -9,52 +9,103 @@ describe EventBus do
     EventBus.clear
   end
 
-  describe '.announce' do
+  describe '.publish' do
 
     it 'returns itself, to facilitate cascades' do
-      EventBus.clear.should == EventBus
+      EventBus.publish(event_name, {}).should == EventBus
     end
 
-    context 'when the listener is specific about the event name' do
-      it 'sends the event to the listener' do
-        EventBus.listen_for(event_name, listener, receiving_method)
-        listener.should_receive(receiving_method).with({:a => 1, :b => 2})
-        EventBus.announce(event_name, {:a => 1, :b => 2})
-      end
+    it 'passes the event name in the details hash' do
+      EventBus.subscribe(event_name, listener, receiving_method)
+      listener.should_receive(receiving_method).with(:event_name => event_name)
+      EventBus.publish(event_name, {})
     end
 
-    context 'when the listener uses a regex that matches' do
-      it 'sends the event to the listener' do
-        EventBus.listen_for(/123b/, listener, receiving_method)
-        listener.should_receive(receiving_method).with({:a => 1, :b => 2})
-        EventBus.announce(event_name, {:a => 1, :b => 2})
-      end
+    it 'allows the details hash to be omitted' do
+      EventBus.subscribe(event_name, listener, receiving_method)
+      listener.should_receive(receiving_method).with(:event_name => event_name)
+      EventBus.publish(event_name)
     end
 
-    context 'when the listener listens for a different event' do
-      it 'does not send the event to the listener' do
-        EventBus.listen_for('blah', listener, receiving_method)
+  end
+
+  describe '.subscribe' 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
+      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)
+      end
+
+      it 'does not send the event to non-matching listeners' do
+        EventBus.subscribe('blah', listener, receiving_method)
         listener.should_not_receive(receiving_method)
-        EventBus.announce(event_name, {:a => 1, :b => 2})
+        EventBus.publish(event_name, :a => 1, :b => 2, :event_name => event_name)
       end
     end
 
-    context 'when the listener listens for a non-matching regex' do
-      it 'does not send the event to the listener' do
-        EventBus.listen_for(/123a/, listener, receiving_method)
+    context 'accepts a regex event name' 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)
+      end
+
+      it 'does not send the event to non-matching listeners' do
+        EventBus.subscribe(/123a/, listener, receiving_method)
         listener.should_not_receive(receiving_method)
-        EventBus.announce(event_name, {:a => 1, :b => 2})
+        EventBus.publish(event_name, :a => 1, :b => 2, :event_name => event_name)
+      end
+    end
+
+    context 'can take a block or a receiver' do
+      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}
+        end
+        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)
+        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)
+      end
+
+      it 'expects a method name' do
+        expect { EventBus.subscribe('blah', listener)}.to raise_error(ArgumentError)
+      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)
       end
     end
 
   end
 
   describe '.clear' do
-    it 'sends no event to previous registrants' do
-      EventBus.listen_for(event_name, listener, receiving_method)
+    it 'removes all previous registrants' do
+      EventBus.subscribe(event_name, listener, receiving_method)
       EventBus.clear
       listener.should_not_receive(receiving_method)
-      EventBus.announce(event_name, {})
+      EventBus.publish(event_name, {})
     end
 
     it 'returns itself, to facilitate cascades' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: event_bus
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-24 00:00:00.000000000 Z
+date: 2013-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -18,7 +18,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.9.2
+        version: 10.0.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.9.2
+        version: 10.0.1
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +66,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- .rspec
+- .yardopts
 - Gemfile
 - Gemfile.lock
 - README.md