wisper 0.0.2 → 1.0.0

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - '1.9.2'
+  - '1.9.3'
+  - jruby-19mode
+  - rbx-19mode

data/README.md

@@ -2,6 +2,9 @@
 
 Simple pub/sub for Ruby objects
 
+[![Code Climate](https://codeclimate.com/github/krisleech/wisper.png)](https://codeclimate.com/github/krisleech/wisper)
+[![Build Status](https://travis-ci.org/krisleech/wisper.png)](https://travis-ci.org/krisleech/wisper)
+
 While this is not dependent on Rails in any way it was extracted from a Rails
 project and is used as an alternative to ActiveRecord callbacks and Observers.
 
@@ -20,42 +23,123 @@ Add this line to your application's Gemfile:
 
 ## Usage
 
+Any class with the Wisper module included can broadcast events to subscribed
+listeners. Listeners are added, at runtime, to the publishing object.
+
+### Publishing
+
 ```ruby
-class CreateThing
+class MyPublisher
   include Wisper
 
-  def execute(attributes)
-    thing = Thing.new(attributes)
-    if thing.valid?
-      thing.save!
-      broadcast(:create_thing_successful, thing)
+  def do_something
+    publish(:done_something, self)
+  end
+end
+```
+
+When the publisher publishes an event it can pass any number of arguments which 
+are passed on to the listeners.
+
+```ruby
+publish(:done_something, self, 'hello', 'world')
+```
+
+### Subscribing
+
+#### Listeners
+
+The listener is subscribed to all events it responds to.
+
+```ruby
+listener = Object.new # any object
+my_publisher = MyPublisher.new
+my_publisher.subscribe(listener)
+```
+
+#### Blocks
+
+The block is subscribed to a single event.
+
+```ruby
+my_publisher = MyPublisher.new
+my_publisher.on(:done_something) do |publisher|
+  # ...
+end
+```
+
+### ActiveRecord
+
+```ruby
+class Post < ActiveRecord::Base
+  include Wisper
+
+  def create
+    if save
+      publish(:create_post_successful, self)
     else
-      broadcast(:create_thing_failed, thing)
+      publish(:create_post_failed, self)
     end
   end
 end
+```
+
+### ActionController
 
-class ThingsController < ApplicationController
+```ruby
+class PostsController < ApplicationController
   def create
-    command = CreateThing.new
+    @post = Post.new(params[:post])
 
-    command.add_listener(PusherListener.new)
-    command.add_listener(ActivityListener.new)
-    command.add_listener(StatisticsListener.new)
+    @post.subscribe(PusherListener.new)
+    @post.subscribe(ActivityListener.new)
+    @post.subscribe(StatisticsListener.new)
 
-    command.respond_to(:create_thing_successful) do |thing|
-      redirect_to thing
-    end
+    @post.on(:create_post_successful) { |post| redirect_to post }
+    @post.on(:create_post_failed)     { |post| render :action => :new }
 
-    command.respond_to(:create_thing_failed) do |thing|
-      @thing = thing
-      render :action => :new
-    end
+    @post.create
+  end
+end
+```
+
+### Service/Use case object
+
+The downside to publishing directly from ActiveRecord models is that an event
+can get fired and then rolled back if a transaction fails.
 
-    command.execute(params[:thing])
+Since I am trying to make my models dumb I tend to use a separate service 
+object which contains all the logic and wraps it all in a transaction.
+
+The follow is contrived, but you can imagine it doing more than just updating a
+record, maybe sending an email or updating other records.
+
+```ruby
+class CreateThing
+  include Wisper
+
+  def execute(attributes)
+    thing = Thing.new(attributes)
+
+    if thing.valid?
+      ActiveRecord::Base.transaction do
+        thing.save
+        # ...
+      end
+      publish(:create_thing_successful, thing)
+    else
+      publish(:create_thing_failed, thing)
+    end
   end
 end
+```
+
+### Example listeners
 
+These are typical app wide listeners which have a method for pretty much every
+event which is broadcast.
+
+```ruby
 class PusherListener
   def create_thing_successful(thing)
     # ...
@@ -75,6 +159,59 @@ class StatisticsListener
 end
 ```
 
+## Subscribing to selected events
+
+By default a listener will get notified of all events it responds to. You can
+limit which events a listener is notified of by passing an event or array of
+events to `:on`.
+
+```ruby
+post_creater.subscribe(PusherListener.new, :on => :create_post_successful)
+```
+
+## Mapping event to a different method
+
+By default the method called on the subscriber is the same as the event
+broadcast. However it can be mapped to a different method using `:with`.
+
+```ruby
+report_creator.subscribe(MailResponder.new, :with => :successful)
+```
+
+In the above case it is pretty useless unless used in conjuction with `:on`
+since all events will get mapped to `:successful`. Instead you might do
+something like this:
+
+```ruby
+report_creator.subscribe(MailResponder.new, :on   => :create_report_successful,
+                                            :with => :successful)
+```
+
+If you pass an array of events to `:on` each event will be mapped to the same
+method when `:with` is specified. If you need to listen for select events
+_and_ map each one to a different method subscribe the listener once for
+each mapping:
+
+```ruby
+report_creator.subscribe(MailResponder.new, :on   => :create_report_successful,
+                                            :with => :successful)
+
+report_creator.subscribe(MailResponder.new, :on   => :create_report_failed,
+                                            :with => :failed)
+```
+
+## Chaining subscriptions
+
+```ruby
+post.on(:success) { |post| redirect_to post }
+    .on(:failure) { |post| render :action => :edit, :locals => :post => post }
+```
+
+## Compatibility
+
+Tested with 1.9.x on MRI, JRuby and Rubinius.
+See the [build status](https://travis-ci.org/krisleech/wisper) for details.
+
 ## License
 
 (The MIT License)

data/Rakefile

@@ -1 +1,7 @@
 require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec

data/lib/wisper.rb

@@ -1,4 +1,7 @@
 require "wisper/version"
+require "wisper/registration/registration"
+require "wisper/registration/object"
+require "wisper/registration/block"
 
 module Wisper
   def listeners
@@ -7,56 +10,34 @@ module Wisper
 
   def add_listener(listener, options = {})
     listeners << ObjectRegistration.new(listener, options)
+    self
   end
 
+  alias :subscribe :add_listener
+
   def add_block_listener(options = {}, &block)
     listeners << BlockRegistration.new(block, options)
+    self
   end
 
   # sugar
   def respond_to(event, &block)
-    listeners << BlockRegistration.new(block, :on => event)
-  end
-
-  class BlockRegistration
-    attr_reader :on, :listener
-
-    def initialize(block, options)
-      @listener   = block
-      @on = Array(options.fetch(:on) { 'all' }).map(&:to_s)
-    end
-
-    def broadcast(event, *args)
-      if on.include?(event) || on.include?('all')
-        listener.call(*args)
-      end
-    end
+    add_block_listener({:on => event}, &block)
   end
 
-  class ObjectRegistration
-    attr_reader :on, :listener
-
-    def initialize(listener, options)
-      @listener   = listener
-      @method     = options[:method]
-      @on = Array(options.fetch(:on) { 'all' }).map(&:to_s)
-    end
-
-    def broadcast(event, *args)
-      if (on.include?(event) || on.include?('all')) && listener.respond_to?(event)
-        listener.public_send(event, *args) 
-      end
-    end
-  end
+  alias :on :respond_to
 
   private
 
   def broadcast(event, *args)
     listeners.each do | listener |
-      listener.broadcast(clean_event(event), *args) 
+      listener.broadcast(clean_event(event), *args)
     end
   end
 
+  alias :publish  :broadcast
+  alias :announce :broadcast
+
   def clean_event(event)
     event.to_s.gsub('-', '_')
   end

data/lib/wisper/registration/block.rb

@@ -0,0 +1,9 @@
+module Wisper
+  class BlockRegistration < Registration
+    def broadcast(event, *args)
+      if should_broadcast?(event)
+        listener.call(*args)
+      end
+    end
+  end
+end

data/lib/wisper/registration/object.rb

@@ -0,0 +1,23 @@
+module Wisper
+  class ObjectRegistration < Registration
+    attr_reader :with
+
+    def initialize(listener, options)
+      super(listener, options)
+      @with = options[:with]
+    end
+
+    def broadcast(event, *args)
+      method_to_call = map_event_to_method(event)
+      if should_broadcast?(event) && listener.respond_to?(method_to_call)
+        listener.public_send(method_to_call, *args)
+      end
+    end
+
+    private
+
+    def map_event_to_method(event)
+      with || event
+    end
+  end
+end

data/lib/wisper/registration/registration.rb

@@ -0,0 +1,16 @@
+module Wisper
+  class Registration
+    attr_reader :on, :listener
+
+    def initialize(listener, options)
+      @listener   = listener
+      @on         = Array(options.fetch(:on) { 'all' }).map(&:to_s)
+    end
+
+    private
+
+    def should_broadcast?(event)
+      on.include?(event) || on.include?('all')
+    end
+  end
+end

data/lib/wisper/version.rb

@@ -1,3 +1,3 @@
 module Wisper
-  VERSION = "0.0.2"
+  VERSION = "1.0.0"
 end

data/spec/lib/integration_spec.rb

@@ -38,4 +38,31 @@ describe Wisper do
 
     command.execute(true)
   end
+
+  it 'maps events to different methods' do
+    listener_1 = double('listener')
+    listener_2 = double('listener')
+    listener_1.should_receive(:happy_days).with('hello')
+    listener_2.should_receive(:sad_days).with('world')
+
+    command = MyCommand.new
+
+    command.add_listener(listener_1, :on => :success, :with => :happy_days)
+    command.add_listener(listener_2, :on => :failure, :with => :sad_days)
+
+    command.execute(true)
+    command.execute(false)
+  end
+
+  it 'subscribes block can be chained' do
+    insider = double('Insider')
+    insider.should_receive(:render).with('success')
+
+    command = MyCommand.new
+
+    command.on(:success) { |message| insider.render('success') }
+           .on(:failure) { |message| insider.render('failure') }
+
+    command.execute(true)
+  end
 end

data/spec/lib/simple_example_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+
+class MyPublisher
+  include Wisper
+
+  def do_something
+    # ...
+    broadcast(:bar, self)
+    broadcast(:foo, self)
+  end
+end
+
+describe 'simple publishing' do
+  it 'subscribes listener to events' do
+    listener = double('listener')
+    listener.should_receive(:foo).with instance_of MyPublisher
+    listener.should_receive(:bar).with instance_of MyPublisher
+
+    my_publisher = MyPublisher.new
+    my_publisher.add_listener(listener)
+    my_publisher.do_something
+  end
+end

data/spec/lib/wisper_spec.rb

@@ -5,7 +5,7 @@ describe Wisper do
   let(:publisher) { Object.new.extend(Wisper) }
 
   describe '.add_listener' do
-    it 'subscribes listener to all published events' do
+    it 'subscribes given listener to all published events' do
       listener.should_receive(:this_happened)
       listener.should_receive(:so_did_this)
 
@@ -15,52 +15,126 @@ describe Wisper do
       publisher.send(:broadcast, 'so_did_this')
     end
 
-    it 'subscribes listener to selected events' do
-      listener.should_receive(:this_happened)
-      listener.stub(:so_did_this)
-      listener.should_not_receive(:so_did_this)
+    describe ':on argument' do
+      it 'subscribes given listener to a single event' do
+        listener.should_receive(:this_happened)
+        listener.stub(:so_did_this)
+        listener.should_not_receive(:so_did_this)
 
-      listener.respond_to?(:so_did_this).should be_true
+        listener.respond_to?(:so_did_this).should be_true
 
-      publisher.add_listener(listener, :on => 'this_happened')
+        publisher.add_listener(listener, :on => 'this_happened')
 
-      publisher.send(:broadcast, 'this_happened')
-      publisher.send(:broadcast, 'so_did_this')
+        publisher.send(:broadcast, 'this_happened')
+        publisher.send(:broadcast, 'so_did_this')
+      end
+
+      it 'subscribes given listener to many events' do
+        listener.should_receive(:this_happened)
+        listener.should_receive(:and_this)
+        listener.stub(:so_did_this)
+        listener.should_not_receive(:so_did_this)
+
+        listener.respond_to?(:so_did_this).should be_true
+
+        publisher.add_listener(listener, :on => ['this_happened', 'and_this'])
+
+        publisher.send(:broadcast, 'this_happened')
+        publisher.send(:broadcast, 'so_did_this')
+        publisher.send(:broadcast, 'and_this')
+      end
     end
 
-    it 'does not receive events it can not respond to' do
-      listener.should_not_receive(:so_did_this)
-      listener.stub(:respond_to?, false)
+    describe ':with argument' do
+      it 'sets method to call listener with on event' do
+        listener.should_receive(:different_method).twice
 
-      listener.respond_to?(:so_did_this).should be_false
+        publisher.add_listener(listener, :with => :different_method)
 
-      publisher.add_listener(listener, :on => 'so_did_this')
+        publisher.send(:broadcast, 'this_happened')
+        publisher.send(:broadcast, 'so_did_this')
+      end
+    end
 
-      publisher.send(:broadcast, 'so_did_this')
+    it 'returns publisher so methods can be chained' do
+      publisher.add_listener(listener, :on => 'so_did_this').should == publisher
     end
   end
 
-  describe 'Block listeners' do
-    it 'subscribes block to all events' do
+  describe '.add_block_listener' do
+    it 'subscribes given block to all events' do
       insider = double('insider')
-      insider.should_receive(:it_happened)
+      insider.should_receive(:it_happened).twice
 
       publisher.add_block_listener do
         insider.it_happened
       end
 
       publisher.send(:broadcast, 'something_happened')
+      publisher.send(:broadcast, 'and_so_did_this')
     end
 
-    it 'subscribes block to selected events' do
-      insider = double('insider')
-      insider.should_not_receive(:it_happened)
+    describe ':on argument' do
+      it '.add_block_listener subscribes block to an event' do
+        insider = double('insider')
+        insider.should_not_receive(:it_happened).once
 
+        publisher.add_block_listener(:on => 'something_happened') do
+          insider.it_happened
+        end
+
+        publisher.send(:broadcast, 'something_happened')
+        publisher.send(:broadcast, 'and_so_did_this')
+      end
+    end
+
+    it 'returns publisher so methods can be chained' do
       publisher.add_block_listener(:on => 'this_thing_happened') do
+      end.should == publisher
+    end
+  end
+
+  describe '.on (alternative block syntax)' do
+    it 'subscribes given block to an event' do
+      insider = double('insider')
+      insider.should_receive(:it_happened)
+
+      publisher.on(:something_happened) do
         insider.it_happened
       end
 
       publisher.send(:broadcast, 'something_happened')
     end
   end
+
+  describe '.broadcast' do
+    it 'does not publish events which cannot be responded to' do
+      listener.should_not_receive(:so_did_this)
+      listener.stub(:respond_to?, false)
+
+      publisher.add_listener(listener, :on => 'so_did_this')
+
+      publisher.send(:broadcast, 'so_did_this')
+    end
+
+    describe ':event argument' do
+      it 'is indifferent to string and symbol' do
+        listener.should_receive(:this_happened).twice
+
+        publisher.add_listener(listener)
+
+        publisher.send(:broadcast, 'this_happened')
+        publisher.send(:broadcast, :this_happened)
+      end
+
+      it 'is indifferent to dasherized and underscored strings' do
+        listener.should_receive(:this_happened).twice
+
+        publisher.add_listener(listener)
+
+        publisher.send(:broadcast, 'this_happened')
+        publisher.send(:broadcast, 'this-happened')
+      end
+    end
+  end
 end

data/wisper.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |gem|
   gem.email         = ["kris.leech@gmail.com"]
   gem.description   = %q{pub/sub for Ruby objects}
   gem.summary       = %q{pub/sub for Ruby objects}
-  gem.homepage      = ""
+  gem.homepage      = "https://github.com/krisleech/wisper"
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wisper
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-30 00:00:00.000000000 Z
+date: 2013-04-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -68,17 +68,22 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .rspec
+- .travis.yml
 - Gemfile
 - Guardfile
 - README.md
 - Rakefile
 - lib/wisper.rb
+- lib/wisper/registration/block.rb
+- lib/wisper/registration/object.rb
+- lib/wisper/registration/registration.rb
 - lib/wisper/version.rb
 - spec/lib/integration_spec.rb
+- spec/lib/simple_example_spec.rb
 - spec/lib/wisper_spec.rb
 - spec/spec_helper.rb
 - wisper.gemspec
-homepage: ''
+homepage: https://github.com/krisleech/wisper
 licenses: []
 post_install_message: 
 rdoc_options: []
@@ -92,7 +97,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1275527942572696193
+      hash: -3667309302433800657
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -101,7 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1275527942572696193
+      hash: -3667309302433800657
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -110,5 +115,6 @@ specification_version: 3
 summary: pub/sub for Ruby objects
 test_files:
 - spec/lib/integration_spec.rb
+- spec/lib/simple_example_spec.rb
 - spec/lib/wisper_spec.rb
 - spec/spec_helper.rb