jmoses_event_bus 1.0.1

data/.rspec

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

data/.yardopts

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

data/Gemfile

@@ -0,0 +1,12 @@
+source 'https://rubygems.org'
+gemspec
+
+group :test do
+  gem 'rspec', '~> 2.12'
+  gem 'rspec-spies'
+  gem 'rspec-given'
+  gem 'rake', '~> 10.0.1'
+  gem 'simplecov', :require => false
+  gem 'json'
+end
+

data/Gemfile.lock

@@ -0,0 +1,42 @@
+PATH
+  remote: .
+  specs:
+    event_bus (1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.2.4)
+    json (1.8.0)
+    multi_json (1.7.3)
+    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-given (2.4.1)
+      rspec (>= 2.11)
+      sorcerer (>= 0.3.7)
+    rspec-mocks (2.13.1)
+    rspec-spies (2.1.4)
+      rspec (~> 2.0)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    sorcerer (0.3.10)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  event_bus!
+  json
+  rake (~> 10.0.1)
+  rspec (~> 2.12)
+  rspec-given
+  rspec-spies
+  simplecov

data/README.md

@@ -0,0 +1,153 @@
+# EventBus
+
+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)
+
+* 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
+
+* Simple, global support for the Observer pattern, aka Publisher-Subscriber.
+* Publish and subscribe to events throughout your Ruby application.
+* 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
+
+Install the gem
+
+```
+gem install event_bus
+```
+
+Or add it to your Gemfile and run `bundle`.
+
+``` ruby
+gem 'event_bus'
+```
+
+## Usage
+
+### Publishing events
+
+Publish events whenever something significant happens in your application:
+
+```ruby
+class PlaceOrder
+  //...
+  EventBus.announce(:order_placed, order: current_order, customer: current_user)
+end
+```
+
+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.
+
+(If you don't like the method name `announce` you can use `publish` or
+`broadcast` instead.)
+
+### Subscribing to events
+
+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.9.x, JRuby, Rubinius.
+See the [build status](https://travis-ci.org/kevinrutherford/event_bus)
+for details.
+
+## License
+
+(The MIT License)
+
+Copyright (c) 2013 Kevin Rutherford
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the 'Software'), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/Rakefile

@@ -0,0 +1,6 @@
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+task :default => :spec
+

data/lib/event_bus/registrations.rb

@@ -0,0 +1,74 @@
+require 'singleton'
+
+class EventBus
+
+  private
+
+  class Registrations
+    include Singleton
+
+    def announce(event_name, payload)
+      full_payload = {event_name: event_name}.merge(payload)
+      listeners.each do |listener|
+        pass_event_to listener, event_name, full_payload
+      end
+    end
+
+    def clear
+      listeners.clear
+    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
+
+    def on_error(&blk)
+      @error_handler = blk
+    end
+
+    private
+
+    def listeners
+      @listeners ||= []
+    end
+
+    def error_handler
+      @error_handler
+    end
+
+    def pass_event_to(listener, event_name, payload)
+      begin
+        listener.respond(event_name, payload)
+      rescue => error
+        error_handler.call(listener.receiver, payload.merge(error: error)) if error_handler
+      end
+    end
+
+    Registration = Struct.new(:pattern, :listener, :method_name) do
+      def respond(event_name, payload)
+        listener.send(method_name, payload) if pattern === event_name
+      end
+
+      def receiver
+        listener
+      end
+    end
+
+    BlockRegistration = Struct.new(:pattern, :block) do
+      def respond(event_name, payload)
+        block.call(payload) if pattern === event_name
+      end
+
+      def receiver
+        block
+      end
+    end
+
+  end
+
+end
+

data/lib/event_bus.rb

@@ -0,0 +1,124 @@
+require_relative 'event_bus/registrations'
+
+class EventBus
+
+  class << self
+
+    #
+    # 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.
+    #
+    # @param event_name [String, Symbol] the name of your event
+    # @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, 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
+
+    #
+    # 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.
+    #
+    # @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 [EventBus] the EventBus, ready to be called again.
+    #
+    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
+
+    alias :listen_for :subscribe
+
+    #
+    # 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.
+    #
+    # @param blk the block to be called when any unhandled error occurs in a listener
+    # @return [EventBus] the EventBus, ready to be called again
+    def on_error(&blk)
+      registrations.on_error &blk
+      self
+    end
+
+    #
+    # Delete all current listener registrations
+    #
+    # @return the EventBus, ready to be called again.
+    #
+    def clear
+      registrations.clear
+      self
+    end
+
+    private
+
+    def subscribe_pattern(pattern, listener, method_name, &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
+    end
+
+    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
+
+    def registrations
+      Registrations.instance
+    end
+
+  end
+
+end
+

data/spec/lib/event_bus_spec.rb

@@ -0,0 +1,227 @@
+require 'spec_helper'
+
+describe EventBus do
+  let(:listener) { double(:listener, handler: true) }
+
+  before do
+    EventBus.clear
+  end
+
+  describe 'publishing' do
+
+    context 'accepts a string for the event name' do
+      Given { EventBus.subscribe(/aa123bb/, listener, :handler) }
+      When { EventBus.publish('aa123bb') }
+      Then { listener.should have_received(:handler).with(event_name: 'aa123bb') }
+    end
+
+    context 'accepts a symbol for the event name' do
+      Given { EventBus.subscribe(/aa123bb/, listener, :handler) }
+      When { EventBus.publish(:aa123bb) }
+      Then { listener.should have_received(:handler).with(event_name: :aa123bb) }
+    end
+
+    context 'rejects any other type as the event name' do
+      When(:result) { EventBus.publish(123) }
+      Then { result.should have_failed(ArgumentError) }
+    end
+
+    context 'adds the event name to the payload' do
+      Given { EventBus.subscribe('aa123bb', listener, :handler) }
+      When { EventBus.publish('aa123bb', a: 56) }
+      Then { listener.should have_received(:handler).with(event_name: 'aa123bb', a: 56) }
+    end
+
+    context 'allows the payload to be omitted' do
+      Given { EventBus.subscribe('aa123bb', listener, :handler) }
+      When { EventBus.publish('aa123bb') }
+      Then { listener.should have_received(:handler).with(event_name: 'aa123bb') }
+    end
+
+  end
+
+  describe 'publishing with errors' do
+    Given(:error) { RuntimeError.new }
+    Given(:erroring_listener) { double(:erroring_listener) }
+    Given(:error_handler) { double(:error_handler, handle_error: true) }
+    Given { erroring_listener.stub(:handler) { raise error } }
+
+    context 'sends the event to the second listener when the first errors' do
+      Given { EventBus.subscribe('aa123bb', erroring_listener, :handler) }
+      Given { EventBus.subscribe('aa123bb', listener, :handler) }
+      When { EventBus.publish('aa123bb') }
+      Then { listener.should have_received(:handler).with(event_name: 'aa123bb') }
+    end
+
+    context 'with an error handler' do
+      Given { EventBus.on_error do |listener, payload|
+        error_handler.handle_error(listener, payload)
+      end }
+
+      context 'when the listener is an object' do
+        Given { EventBus.subscribe('aa123bb', erroring_listener, :handler) }
+        When { EventBus.publish('aa123bb') }
+        Then { error_handler.should have_received(:handle_error).with(erroring_listener, event_name: 'aa123bb', error: error ) }
+      end
+
+      context 'when the listener is a block' do
+        Given { EventBus.subscribe('aa123bb') {|info| raise error } }
+        When { EventBus.publish('aa123bb') }
+        Then { error_handler.should have_received(:handle_error).with(instance_of(Proc), event_name: 'aa123bb', error: error) }
+      end
+
+    end
+
+  end
+
+  describe 'subscribing' do
+
+    context 'with a regex pattern' do
+      context 'sends the event to a matching listener' do
+        Given { EventBus.subscribe(/123b/, listener, :handler) }
+        When { EventBus.publish('aa123bb', a: 1, b: 2) }
+        Then { listener.should have_received(:handler).with(a: 1, b: 2, event_name: 'aa123bb') }
+      end
+
+      context 'does not send the event to non-matching listeners' do
+        Given { EventBus.subscribe(/123a/, listener, :handler) }
+        When { EventBus.publish('aa123bb', a: 1, b: 2, event_name: 'aa123bb') }
+        Then { listener.should_not have_received(:handler) }
+      end
+    end
+
+    context 'with a string pattern' do
+      context 'sends the event to a matching listener' do
+        Given { EventBus.subscribe('aa123bb', listener, :handler) }
+        When { EventBus.publish('aa123bb', a: 1, b: 2) }
+        Then { listener.should have_received(:handler).with(a: 1, b: 2, event_name: 'aa123bb') }
+      end
+
+      context 'does not send the event to non-matching listeners' do
+        Given { EventBus.subscribe('blah', listener, :handler) }
+        When { EventBus.publish('aa123bb', a: 1, b: 2, event_name: 'aa123bb') }
+        Then { listener.should_not have_received(:handler) }
+      end
+    end
+
+    context 'with a symbol pattern' do
+      context 'sends the event to a matching listener' do
+        Given { EventBus.subscribe(:aa123bb, listener, :handler) }
+        When { EventBus.publish(:aa123bb, a: 1, b: 2) }
+        Then { listener.should have_received(:handler).with(a: 1, b: 2, event_name: :aa123bb) }
+      end
+
+      context 'does not send the event to non-matching listeners' do
+        Given { EventBus.subscribe(:blah, listener, :handler) }
+        When { EventBus.publish('aa123bb', a: 1, b: 2, event_name: 'aa123bb') }
+        Then { listener.should_not have_received(:handler) }
+      end
+    end
+
+    context 'subscribing a block' do
+      Given(:spy) { double(:spy, block_called: nil) }
+      Given {
+        EventBus.subscribe('aa123bb') {|info| spy.block_called(info) }
+      }
+
+      context 'calls the block when the event matches' do
+        When { EventBus.publish('aa123bb', a: 1, b: 2) }
+        Then { spy.should have_received(:block_called).with(a: 1, b: 2, event_name: 'aa123bb') }
+      end
+
+      context 'does not call the block when the event does not match' do
+        When { EventBus.publish('blah') }
+        Then { spy.should_not have_received(:block_called) }
+      end
+    end
+
+    context 'with a listener object' do
+      Given { EventBus.subscribe(listener) }
+
+      context 'calls a listener method whose name matches the event name' do
+        When { EventBus.publish('handler', a: 2, b: 3) }
+        Then { listener.should have_received(:handler).with(a: 2, b: 3, event_name: 'handler') }
+      end
+
+      context 'calls a listener method with symbol whose name matches the event name' do
+        When { EventBus.publish(:handler, a: 2, b: 3) }
+        Then { listener.should have_received(:handler).with(a: 2, b: 3, event_name: :handler) }
+      end
+
+      context 'calls no method when there is no name match' do
+        When { EventBus.publish('b_method') }
+        Then { listener.should_not have_received(:handler) }
+      end
+
+    end
+
+    context 'when called incorrectly' do
+
+      context 'when specifying the event name' do
+
+        context 'must provide a method or a block' do
+          When(:subscribe) { EventBus.subscribe('blah', listener) }
+          Then { subscribe.should have_failed(ArgumentError) }
+        end
+
+        context 'cannot provide a method AND a block' do
+          When(:subscribe) { EventBus.subscribe('blah', listener, :handler) {|info| }}
+          Then { subscribe.should have_failed(ArgumentError) }
+        end
+
+        context 'must provide a block when no method is supplied' do
+          When(:subscribe) { EventBus.subscribe('blah') }
+          Then { subscribe.should have_failed(ArgumentError) }
+        end
+
+      end
+
+      context 'when specifying a listener object' do
+
+        context 'when a method is also provided' do
+          When(:subscribe) { EventBus.subscribe(listener, double) }
+          Then { subscribe.should have_failed(ArgumentError) }
+        end
+
+        context 'when a block is also provided' do
+          When(:subscribe) { EventBus.subscribe(listener) {|info| } }
+          Then { subscribe.should have_failed(ArgumentError) }
+        end
+
+      end
+
+    end
+
+  end
+
+  describe '.clear' do
+    context 'removes all previous registrants' do
+      Given { EventBus.subscribe('aa123bb', listener, :handler) }
+      Given { EventBus.clear }
+      When { EventBus.publish('aa123bb', {}) }
+      Then { listener.should_not have_received(:handler) }
+    end
+
+  end
+
+  context 'EventBus methods cascade' do
+
+    context 'clear' do
+      When(:result) { EventBus.clear }
+      Then { result.should == EventBus }
+    end
+
+    context 'publish' do
+      When(:result) { EventBus.publish('aa123bb', {}) }
+      Then { result.should == EventBus }
+    end
+
+    context 'subscribe' do
+      When(:result) { EventBus.subscribe('aa123bb', listener, :handler) }
+      Then { result.should == EventBus }
+    end
+
+  end
+
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'simplecov'
+require 'rspec-spies'
+require 'rspec-given'
+
+SimpleCov.start
+
+require 'event_bus'
+
+

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: jmoses_event_bus
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Jon Moses
+- Kevin Rutherford
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-07-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 10.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 10.0.1
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.12'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: event_bus provides support for application-wide events, without coupling
+  the publishing and subscribing objects or classes to each other
+email:
+- jon@burningbus.us
+- kevin@rutherford-software.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .rspec
+- .yardopts
+- Gemfile
+- Gemfile.lock
+- 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/jmoses/event_bus
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: A simple pubsub event bus for Ruby applications (fork by jmoses)
+test_files:
+- spec/lib/event_bus_spec.rb
+- spec/spec_helper.rb