wisper 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b7eced3bc4dc2f86f783081e2a3e9f592078deb4
-  data.tar.gz: 3ce6be1cf3f79319bf8582c86eced10458c2e65f
+  metadata.gz: 9c7ce841a6cb6f5ea98bb85ff8c61b74ed007107
+  data.tar.gz: 57fd4d7de64134f55724e6bbf152b092312383e3
 SHA512:
-  metadata.gz: c680af80578aa1d5170d4334ccda9545be5c0cbcea4ad105e82d5a4e0d5d4ab24a8f835ba1d5e4b9a7c8eb723ca7ff36c2ec0dfdc2da8fcf2e51347a95316280
-  data.tar.gz: 5b6501efcf475b2a157e8975e6bf7c1ab83118b73313fd3ea7b8e2c5160bb93a301572f6aa30568b6d264c2fc4d779808dfd2b1ffc8395808274c7785712ecc6
+  metadata.gz: 37ab485a83aa173857edca6d8fd76911f4cda61bccf6fb3af5adb47e2503dd2a9fe182be75227d3f970d15e64933af16920319d2d47911e5e8d444d18df8ff55
+  data.tar.gz: 8cf79f4c35a792c87c97fc83fa6dcac78bfb60a70c3e80b6f052148b31a87618b4538b165ca71ef0a9b820f38bf3ec5f413055fbd0eaef36e0bd44d482ba694f

data/.travis.yml

@@ -7,7 +7,7 @@ rvm:
   - '2.0.0'
   - '2.1.2'
   - jruby
-  - rbx-2
+  #- rbx-2
   ### ALLOWED FAILURES ###
   # see how compatible we are with dev versions, but do not fail the build
   - ruby-head

data/CHANGELOG.md

@@ -1,4 +1,9 @@
-## Unreleased (no breaking changes)
+## 1.6.0 (25 Oct 2014)
+
+Authors: Kris Leech
+
+* deprecate: add_listener, add_block_listener and respond_to
+* internal: make method naming more consistent
 
 ## 1.5.0 (6th Oct 2014)
 

data/README.md

@@ -1,17 +1,18 @@
 # Wisper
 
-Wisper is a Ruby library for decoupling and managing the dependencies of your
-Ruby objects using Pub/Sub.
+*A micro library providing Ruby objects with Publish-Subscribe capabilities*
 
 [![Gem Version](https://badge.fury.io/rb/wisper.png)](http://badge.fury.io/rb/wisper)
 [![Code Climate](https://codeclimate.com/github/krisleech/wisper.png)](https://codeclimate.com/github/krisleech/wisper)
 [![Build Status](https://travis-ci.org/krisleech/wisper.png?branch=master)](https://travis-ci.org/krisleech/wisper)
 [![Coverage Status](https://coveralls.io/repos/krisleech/wisper/badge.png?branch=master)](https://coveralls.io/r/krisleech/wisper?branch=master)
 
-Wisper was extracted from a Rails codebase but is not dependant on Rails.
+* Decouple core business logic from external concerns in Hexagonal style architectures
+* Use as an alternative to ActiveRecord callbacks and Observers in Rails apps
+* Connect objects based on context without permanence
+* React to events synchronously or asynchronously
 
-It is commonly used as an alternative to ActiveRecord callbacks and Observers
-to reduce coupling between data and domain layers.
+Note: Wisper was originally extracted from a Rails codebase but is not dependant on Rails.
 
 ## Installation
 
@@ -29,188 +30,131 @@ to subscribed listeners. Listeners subscribe, at runtime, to the publisher.
 ### Publishing
 
 ```ruby
-class MyPublisher
+class CancelOrder
   include Wisper::Publisher
-
-  def do_something
-    # ...
-    publish(:done_something)
+  
+  def call(order_id)
+    order = Order.find_by_id(order_id)
+    
+    # business logic...
+
+    if order.cancelled?
+      broadcast(:cancel_order_successful, order.id)
+    else
+      broadcast(:cancel_order_failed, order.id)
+    end
   end
 end
 ```
 
-When a publisher broadcasts an event it can pass any number of arguments which 
-are to be passed on to the listeners.
+When a publisher broadcasts an event it can include number of arguments. 
 
-```ruby
-publish(:done_something, 'hello', 'world')
-```
+The `broadcast` method is also aliased as `publish` and `announce`.
+
+You can also include `Wisper.publisher` instead of `Wisper::Publisher`.
 
 ### Subscribing
 
-#### Listeners
+#### Objects
 
-Any object can be a listener and only receives events it can respond to.
+Any object can be subscribed as a listener.
 
 ```ruby
-my_publisher = MyPublisher.new
-my_publisher.subscribe(MyListener.new)
-```
+cancel_order = CancelOrder.new
 
-#### Blocks
+cancel_order.subscribe(OrderNotifier.new)
 
-Blocks are subscribed to single events only.
+cancel_order.call(order_id)
+```
+
+The listener would need to implement a method for every event it wishes to receive.
 
 ```ruby
-my_publisher = MyPublisher.new
-my_publisher.on(:done_something) do |publisher|
-  # ...
+class OrderNotifier
+  def cancel_order_successful(order_id)
+    order = Order.find_by_id(order_id)
+       
+    # notify someone ...    
+  end
 end
 ```
 
-### Asynchronous Publishing
+#### Blocks
+
+Blocks can be subscribed to single events and can be chained.
 
 ```ruby
-my_publisher.subscribe(MyListener.new, async: true)
-```
+cancel_order = CancelOrder.new
 
-Please refer to
-[wisper-celluloid](https://github.com/krisleech/wisper-celluloid) or
-[wisper-sidekiq](https://github.com/krisleech/wisper-sidekiq).
+cancel_order.on(:cancel_order_successful) { |order_id| ... }
+            .on(:cancel_order_failed)     { |order_id| ... }
+            
+cancel_order.call(order_id)
+```
 
-### ActiveRecord
+### Handling Events Asynchronously
 
 ```ruby
-class Bid < ActiveRecord::Base
-  include Wisper::Publisher
+cancel_order.subscribe(OrderNotifier.new, async: true)
+```
 
-  validates :amount, presence: true
+Wisper has various adapters for asynchronous event handling, please refer to
+[wisper-celluloid](https://github.com/krisleech/wisper-celluloid),
+[wisper-sidekiq](https://github.com/krisleech/wisper-sidekiq) or
+[wisper-activejob](https://github.com/krisleech/wisper-activejob).
 
-  def commit(_attrs = nil)
-    assign_attributes(_attrs) if _attrs.present?
-    if valid?
-      save!
-      publish(:create_bid_successful, self)
-    else
-      publish(:create_bid_failed, self)
-    end
-  end
-end
-```
+Depending on the adapter used the listener may need to be a class instead of an object.
 
 ### ActionController
 
 ```ruby
-class BidsController < ApplicationController
-  def new
-    @bid = Bid.new
-  end
-
+class CancelOrderController < ApplicationController
+ 
   def create
-    @bid = Bid.new(params[:bid])
+    cancel_order = CancelOrder.new
 
-    @bid.subscribe(PusherListener.new)
-    @bid.subscribe(ActivityListener.new)
-    @bid.subscribe(StatisticsListener.new)
+    cancel_order.subscribe(OrderMailer,        async: true)
+    cancel_order.subscribe(ActivityRecorder,   async: true)
+    cancel_order.subscribe(StatisticsRecorder, async: true)
 
-    @bid.on(:create_bid_successful) { |bid| redirect_to bid }
-    @bid.on(:create_bid_failed)     { |bid| render action: :new }
+    cancel_order.on(:cancel_order_successful) { |order_id| redirect_to order_path(order_id) }
+    cancel_order.on(:cancel_order_failed)     { |order_id| render action: :new }
 
-    @bid.commit
+    cancel_order.call(order_id)
   end
 end
 ```
 
-A full CRUD example is shown in the [Wiki](https://github.com/krisleech/wisper/wiki).
-
-### Service/Use Case/Command objects
+### ActiveRecord
 
-A Service object is useful when an operation is complex, interacts with more
-than one model, accesses an external API or would burden a model with too much
-responsibility.
+If you wish to publish directly from ActiveRecord models you can broadcast events from callbacks:
 
 ```ruby
-class PlayerJoiningTeam
+class Order < ActiveRecord::Base
   include Wisper::Publisher
-
-  attr_reader :player, :team
-
-  def initialize(player, team)
-    @player = player
-    @team   = team
-  end
-
-  def execute
-    membership = Membership.new(player, team)
-
-    if membership.valid?
-      membership.save!
-      email_player
-      assign_first_mission
-      publish(:player_joining_team_successful, player, team)
-    else
-      publish(:player_joining_team_failed, player, team)
-    end
-  end
+  
+  after_commit     :publish_creation_successful, on: :create
+  after_validation :publish_creation_failed,     on: :create
 
   private
 
-  def email_player
-    # ...
+  def publish_creation_successful
+    broadcast(:order_creation_successful, self)
   end
 
-  def assign_first_mission
-    # ...
+  def publish_creation_failed
+    broadcast(:order_creation_failed, self) if errors.any?
   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)
-    # ...
-  end
-end
+There are more examples in the [Wiki](https://github.com/krisleech/wisper/wiki).
 
-class ActivityListener
-  def create_thing_successful(thing)
-    # ...
-  end
-end
+## Global Listeners
 
-class StatisticsListener
-  def create_thing_successful(thing)
-    # ...
-  end
-end
+Global listeners receive all broadcast events which they can respond to.
 
-class CacheListener
-  def create_thing_successful(thing)
-    # ...
-  end
-end
-
-class IndexingListener
-  def create_thing_successful(thing)
-    # ...
-  end
-end
-```
-
-## Global listeners
-
-If you become tired of adding the same listeners to _every_ publisher you can
-add listeners globally. They receive all broadcast events which they can respond
-to.
-
-Global listeners should be used with caution, the execution path becomes less
-obvious on reading the code and of course you are introducing global state and
-'always on' behaviour. This may not desirable.
+This is useful for cross cutting concerns such as recording statistics, indexing, caching and logging.
 
 ```ruby
 Wisper.subscribe(MyListener.new)
@@ -220,7 +164,7 @@ In a Rails app you might want to add your global listeners in an initalizer.
 
 Global listeners are threadsafe.
 
-### Scoping to publisher class
+### Scoping by publisher class
 
 You might want to globally subscribe a listener to publishers with a certain
 class.
@@ -232,7 +176,7 @@ Wisper.subscribe(MyListener.new, scope: :MyPublisher)
 This will subscribe the listener to all instances of `MyPublisher` and its
 subclasses.
 
-Alternatively you can also do exactly the same with a publisher class:
+Alternatively you can also do exactly the same with a publisher class itself:
 
 ```ruby
 MyPublisher.subscribe(MyListener.new)
@@ -249,8 +193,9 @@ end
 ```
 
 Any events broadcast within the block by any publisher will be sent to the
-listeners. This is useful if you have a child object which publishes an event
-which is not bubbled down to a parent publisher.
+listeners. 
+
+This is useful for capturing events published by objects to which you do not have access in a given context.
 
 Temporary Global Listeners are threadsafe.
 
@@ -307,12 +252,8 @@ 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 } }
-```
+You could also alias the method within your listener, as such
+`alias successful create_report_successful`.
 
 ## RSpec
 
@@ -346,18 +287,19 @@ publisher.execute
 
 ### Stubbing publishers
 
-Wisper comes with a method for stubbing event publishers so that you can create 
-isolation tests that only care about reacting to events.
+You can stub publishers and their events in unit (isolated) tests that only care about reacting to events.
 
 Given this piece of code:
 
 ```ruby
-class CodeThatReactsToEvents
-  def do_something
+class MyController
+  def create
     publisher = MyPublisher.new
+    
     publisher.on(:some_event) do |variable|
       return "Hello with #{variable}!"
     end
+    
     publisher.execute
   end
 end
@@ -368,24 +310,21 @@ You can test it like this:
 ```ruby
 require 'wisper/rspec/stub_wisper_publisher'
 
-describe CodeThatReactsToEvents do
+describe MyController do
   context "on some_event" do
     before do
       stub_wisper_publisher("MyPublisher", :execute, :some_event, "foo")
     end
 
     it "renders" do
-      response = CodeThatReactsToEvents.new.do_something
+      response = MyController.new.create
       expect(response).to eq "Hello with foo!"
     end
   end
 end
 ```
 
-This becomes important when testing, for example, Rails controllers in
-isolation from the business logic.  This technique is used at the controller
-layer to isolate testing the controller from testing the encapsulated business
-logic.
+This is useful when testing Rails controllers in isolation from the business logic.  
 
 You can use any number of args to pass to the event:
 
@@ -395,6 +334,15 @@ stub_wisper_publisher("MyPublisher", :execute, :some_event, "foo1", "foo2", ...)
 
 See `spec/lib/rspec_extensions_spec.rb` for a runnable example.
 
+## Clearing Global Listeners
+
+If you use global listeners in non-feature tests you _might_ want to clear them
+in a hook to prevent global subscriptions persisting between tests.
+
+```ruby
+after { Wisper.clear }
+```
+
 ## Compatibility
 
 Tested with MRI 1.9.x, MRI 2.0.0, JRuby (1.9 and 2.0 mode) and Rubinius (1.9

data/lib/wisper.rb

@@ -26,17 +26,36 @@ module Wisper
     self.subscribe(listener, options)
   end
 
+  # Examples:
+  #
+  #   Wisper.subscribe(AuditRecorder.new)
+  #
+  #   Wisper.subscribe(AuditRecorder.new, StatsRecorder.new)
+  #
+  #   Wisper.subscribe(AuditRecorder.new, on: 'order_created')
+  #
+  #   Wisper.subscribe(AuditRecorder.new, scope: 'MyPublisher')
+  #
+  #   Wisper.subscribe(AuditRecorder.new, StatsRecorder.new) do
+  #     # ..
+  #   end
+  #
   def self.subscribe(*args, &block)
     if block_given?
-      TemporaryListeners.with(*args, &block)
+      TemporaryListeners.subscribe(*args, &block)
     else
-      options = args.last.is_a?(Hash) ? args.pop : {}
-      args.each do |listener|
-        GlobalListeners.add(listener, options)
-      end
+      GlobalListeners.subscribe(*args)
     end
   end
 
+  def self.publisher
+    Publisher
+  end
+
+  def self.clear
+    GlobalListeners.clear
+  end
+
   def self.configure
     yield(configuration)
   end

data/lib/wisper/configuration.rb

@@ -1,3 +1,5 @@
+require 'forwardable'
+
 module Wisper
   class Configuration
     attr_reader :broadcasters

data/lib/wisper/global_listeners.rb

@@ -1,18 +1,24 @@
 require 'singleton'
 
+# Handles global subscriptions
+
 module Wisper
   class GlobalListeners
     include Singleton
-    attr_reader :mutex
-    private :mutex
 
     def initialize
       @registrations = Set.new
       @mutex         = Mutex.new
     end
 
-    def add(listener, options = {})
-      with_mutex { @registrations << ObjectRegistration.new(listener, options) }
+    def subscribe(*listeners)
+      options = listeners.last.is_a?(Hash) ? listeners.pop : {}
+
+      with_mutex do
+        listeners.each do |listener|
+          @registrations << ObjectRegistration.new(listener, options)
+        end
+      end
       self
     end
 
@@ -28,8 +34,8 @@ module Wisper
       with_mutex { @registrations.clear }
     end
 
-    def self.add(listener, options = {})
-      instance.add(listener, options)
+    def self.subscribe(*listeners)
+      instance.subscribe(*listeners)
     end
 
     def self.registrations
@@ -44,16 +50,15 @@ module Wisper
       instance.clear
     end
 
-    # remain backwards compatible
-    def self.add_listener(listener, options = {})
-      warn "[DEPRECATION] use `add` instead of `add_listener`"
-      add(listener, options)
+    def self.add_listener(listener, options = {}) # deprecated
+      warn "[DEPRECATION] use `subscribe` instead of `add_listener`"
+      subscribe(listener, options)
     end
 
     private
 
     def with_mutex
-      mutex.synchronize { yield }
+      @mutex.synchronize { yield }
     end
   end
 end

data/lib/wisper/publisher.rb

@@ -4,31 +4,42 @@ module Wisper
       registrations.map(&:listener).freeze
     end
 
-    def add_listener(listener, options = {})
+    def subscribe(listener, options = {})
       local_registrations << ObjectRegistration.new(listener, options)
       self
     end
 
-    alias :subscribe :add_listener
+    def on(*events, &block)
+      raise ArgumentError, 'must give at least one event' if events.empty?
+      local_registrations << BlockRegistration.new(block, on: events)
+      self
+    end
 
     def add_block_listener(options = {}, &block)
+      warn "[DEPRECATED] use `on` instead of `add_block_listener`"
       local_registrations << BlockRegistration.new(block, options)
       self
     end
 
-    # sugar
-    def respond_to(*events, &block)
-      add_block_listener({:on => events}, &block)
+    def add_listener(listener, options = {})
+      warn "[DEPRECATED] use `subscribe` instead of `add_listener`"
+      subscribe(listener, options)
     end
 
-    alias :on :respond_to
+    def respond_to(*events, &block)
+      warn '[DEPRECATED] use `on` instead of `respond_to`'
+      on(*events, &block)
+    end
 
     module ClassMethods
-      def add_listener(listener, options = {})
-        GlobalListeners.add(listener, options.merge(:scope => self))
+      def subscribe(listener, options = {})
+        GlobalListeners.subscribe(listener, options.merge(:scope => self))
       end
 
-      alias :subscribe :add_listener
+      def add_listener(listener, options = {})
+        warn "[DEPRECATED] use `subscribe` instead of `add_listener`"
+        subscribe(listener, options)
+      end
     end
 
     private

data/lib/wisper/temporary_listeners.rb

@@ -1,22 +1,25 @@
+# Handles temporary global subscriptions
+
 module Wisper
   class TemporaryListeners
 
-    def self.with(*listeners, &block)
-      options = listeners.last.is_a?(Hash) ? listeners.pop : {}
-      new.with(listeners, options, &block)
+    def self.subscribe(*listeners, &block)
+      new.subscribe(*listeners, &block)
     end
 
     def self.registrations
       new.registrations
     end
 
-    def with(listeners, options, &block)
+    def subscribe(*listeners, &block)
+      options = listeners.last.is_a?(Hash) ? listeners.pop : {}
       begin
-        add_listeners(listeners, options)
+        listeners.each { |listener| registrations << ObjectRegistration.new(listener, options) }
         yield
       ensure
         clear
       end
+      self
     end
 
     def registrations
@@ -29,14 +32,6 @@ module Wisper
       registrations.clear
     end
 
-    def add_listeners(listeners, options)
-      listeners.each { |listener| add_listener(listener, options)}
-    end
-
-    def add_listener(listener, options)
-      registrations << ObjectRegistration.new(listener, options)
-    end
-
     def key
       '__wisper_temporary_listeners'
     end

data/lib/wisper/version.rb

@@ -1,3 +1,3 @@
 module Wisper
-  VERSION = "1.5.0"
+  VERSION = "1.6.0"
 end

data/spec/lib/global_subscribers_spec.rb

@@ -3,15 +3,15 @@ describe Wisper::GlobalListeners do
   let(:local_listener)   { double('listener') }
   let(:publisher)        { publisher_class.new }
 
-  describe '.add' do
+  describe '.subscribe' do
     it 'adds given listener to every publisher' do
-      Wisper::GlobalListeners.add(global_listener)
+      Wisper::GlobalListeners.subscribe(global_listener)
       expect(global_listener).to receive(:it_happened)
       publisher.send(:broadcast, :it_happened)
     end
 
     it 'works with options' do
-      Wisper::GlobalListeners.add(global_listener, :on => :it_happened,
+      Wisper::GlobalListeners.subscribe(global_listener, :on => :it_happened,
                                                    :with => :woot)
       expect(global_listener).to receive(:woot).once
       expect(global_listener).not_to receive(:it_happened_again)
@@ -21,10 +21,10 @@ describe Wisper::GlobalListeners do
 
     it 'works along side local listeners' do
       # global listener
-      Wisper::GlobalListeners.add(global_listener)
+      Wisper::GlobalListeners.subscribe(global_listener)
 
       # local listener
-      publisher.add_listener(local_listener)
+      publisher.subscribe(local_listener)
 
       expect(global_listener).to receive(:it_happened)
       expect(local_listener).to receive(:it_happened)
@@ -37,7 +37,7 @@ describe Wisper::GlobalListeners do
       publisher_2 = publisher_class.new
       publisher_3 = publisher_class.new
 
-      Wisper::GlobalListeners.add(global_listener, :scope => [publisher_1.class,
+      Wisper::GlobalListeners.subscribe(global_listener, :scope => [publisher_1.class,
                                                               publisher_2.class])
 
       expect(global_listener).to receive(:it_happened_1).once
@@ -53,7 +53,7 @@ describe Wisper::GlobalListeners do
       num_threads = 100
       (1..num_threads).to_a.map do
         Thread.new do
-          Wisper::GlobalListeners.add(Object.new)
+          Wisper::GlobalListeners.subscribe(Object.new)
           sleep(rand) # a little chaos
         end
       end.each(&:join)
@@ -64,7 +64,7 @@ describe Wisper::GlobalListeners do
 
   describe '.listeners' do
     it 'returns collection of global listeners' do
-      Wisper::GlobalListeners.add(global_listener)
+      Wisper::GlobalListeners.subscribe(global_listener)
       expect(Wisper::GlobalListeners.listeners).to eq [global_listener]
     end
 
@@ -75,17 +75,16 @@ describe Wisper::GlobalListeners do
   end
 
   it '.clear clears all global listeners' do
-    Wisper::GlobalListeners.add(global_listener)
+    Wisper::GlobalListeners.subscribe(global_listener)
     Wisper::GlobalListeners.clear
     expect(Wisper::GlobalListeners.listeners).to be_empty
   end
 
   describe 'backwards compatibility' do
-    it '.add_listener adds a listener' do
+    it '.add_listener is aliased to .add' do
       silence_warnings do
+        expect(Wisper::GlobalListeners).to receive(:subscribe)
         Wisper::GlobalListeners.add_listener(global_listener)
-        expect(global_listener).to receive(:it_happened)
-        publisher.send(:broadcast, :it_happened)
       end
     end
   end

data/spec/lib/integration_spec.rb

@@ -19,20 +19,7 @@ describe Wisper do
 
     command = MyCommand.new
 
-    command.add_listener(listener)
-
-    command.execute(true)
-  end
-
-  it 'subscribes block to all published events' do
-    insider = double('Insider')
-    expect(insider).to receive(:render).with('hello')
-
-    command = MyCommand.new
-
-    command.add_block_listener do |message|
-      insider.render(message)
-    end
+    command.subscribe(listener)
 
     command.execute(true)
   end
@@ -45,8 +32,8 @@ describe Wisper do
 
     command = MyCommand.new
 
-    command.add_listener(listener_1, :on => :success, :with => :happy_days)
-    command.add_listener(listener_2, :on => :failure, :with => :sad_days)
+    command.subscribe(listener_1, :on => :success, :with => :happy_days)
+    command.subscribe(listener_2, :on => :failure, :with => :sad_days)
 
     command.execute(true)
     command.execute(false)

data/spec/lib/simple_example_spec.rb

@@ -15,7 +15,7 @@ describe 'simple publishing' do
     expect(listener).to receive(:bar).with instance_of MyPublisher
 
     my_publisher = MyPublisher.new
-    my_publisher.add_listener(listener)
+    my_publisher.subscribe(listener)
     my_publisher.do_something
   end
 end

data/spec/lib/temporary_global_listeners_spec.rb

@@ -3,13 +3,13 @@ describe Wisper::TemporaryListeners do
   let(:listener_2) { double('listener', :to_a => nil) }
   let(:publisher)  { Object.class_eval { include Wisper::Publisher } }
 
-  describe '.with' do
+  describe '.subscribe' do
     it 'globally subscribes listener for duration of given block' do
 
       expect(listener_1).to receive(:success)
       expect(listener_1).to_not receive(:failure)
 
-      Wisper::TemporaryListeners.with(listener_1) do
+      Wisper::TemporaryListeners.subscribe(listener_1) do
         publisher.instance_eval { broadcast(:success) }
       end
 
@@ -24,7 +24,7 @@ describe Wisper::TemporaryListeners do
       expect(listener_2).to receive(:success)
       expect(listener_2).to_not receive(:failure)
 
-      Wisper::TemporaryListeners.with(listener_1, listener_2) do
+      Wisper::TemporaryListeners.subscribe(listener_1, listener_2) do
         publisher.instance_eval { broadcast(:success) }
       end
 
@@ -45,7 +45,7 @@ describe Wisper::TemporaryListeners do
 
     it 'ensures registrations are cleared after exception raised in block' do
       begin
-        Wisper::TemporaryListeners.with(listener_1) do
+        Wisper::TemporaryListeners.subscribe(listener_1) do
           raise StandardError
         end
       rescue StandardError
@@ -54,6 +54,10 @@ describe Wisper::TemporaryListeners do
       expect(Wisper::TemporaryListeners.registrations.size).to eql 0
     end
   end
+
+  it 'returns self so methods can be chained' do
+    expect(Wisper::TemporaryListeners.subscribe {}).to be_an_instance_of(Wisper::TemporaryListeners)
+  end
 end
 
 # [1] stubbing `to_a` prevents `Double "listener" received unexpected message

data/spec/lib/wisper/publisher_spec.rb

@@ -2,12 +2,12 @@ describe Wisper::Publisher do
   let(:listener)  { double('listener') }
   let(:publisher) { publisher_class.new }
 
-  describe '.add_listener' do
+  describe '.subscribe' do
     it 'subscribes given listener to all published events' do
       expect(listener).to receive(:this_happened)
       expect(listener).to receive(:so_did_this)
 
-      publisher.add_listener(listener)
+      publisher.subscribe(listener)
 
       publisher.send(:broadcast, 'this_happened')
       publisher.send(:broadcast, 'so_did_this')
@@ -21,7 +21,7 @@ describe Wisper::Publisher do
 
         expect(listener).to respond_to(:so_did_this)
 
-        publisher.add_listener(listener, :on => 'this_happened')
+        publisher.subscribe(listener, :on => 'this_happened')
 
         publisher.send(:broadcast, 'this_happened')
         publisher.send(:broadcast, 'so_did_this')
@@ -35,7 +35,7 @@ describe Wisper::Publisher do
 
         expect(listener).to respond_to(:so_did_this)
 
-        publisher.add_listener(listener, :on => ['this_happened', 'and_this'])
+        publisher.subscribe(listener, :on => ['this_happened', 'and_this'])
 
         publisher.send(:broadcast, 'this_happened')
         publisher.send(:broadcast, 'so_did_this')
@@ -47,7 +47,7 @@ describe Wisper::Publisher do
       it 'sets method to call listener with on event' do
         expect(listener).to receive(:different_method).twice
 
-        publisher.add_listener(listener, :with => :different_method)
+        publisher.subscribe(listener, :with => :different_method)
 
         publisher.send(:broadcast, 'this_happened')
         publisher.send(:broadcast, 'so_did_this')
@@ -59,7 +59,7 @@ describe Wisper::Publisher do
         expect(listener).to receive(:after_it_happened)
         expect(listener).not_to receive(:it_happened)
 
-        publisher.add_listener(listener, :prefix => :after)
+        publisher.subscribe(listener, :prefix => :after)
 
         publisher.send(:broadcast, 'it_happened')
       end
@@ -68,7 +68,7 @@ describe Wisper::Publisher do
         expect(listener).to receive(:on_it_happened)
         expect(listener).not_to receive(:it_happened)
 
-        publisher.add_listener(listener, :prefix => true)
+        publisher.subscribe(listener, :prefix => true)
 
         publisher.send(:broadcast, 'it_happened')
       end
@@ -83,16 +83,16 @@ describe Wisper::Publisher do
       it 'scopes listener to given class' do
         expect(listener_1).to receive(:it_happended)
         expect(listener_2).not_to receive(:it_happended)
-        publisher.add_listener(listener_1, :scope => publisher.class)
-        publisher.add_listener(listener_2, :scope => Class.new)
+        publisher.subscribe(listener_1, :scope => publisher.class)
+        publisher.subscribe(listener_2, :scope => Class.new)
         publisher.send(:broadcast, 'it_happended')
       end
 
       it 'scopes listener to given class string' do
         expect(listener_1).to receive(:it_happended)
         expect(listener_2).not_to receive(:it_happended)
-        publisher.add_listener(listener_1, :scope => publisher.class.to_s)
-        publisher.add_listener(listener_2, :scope => Class.new.to_s)
+        publisher.subscribe(listener_1, :scope => publisher.class.to_s)
+        publisher.subscribe(listener_2, :scope => Class.new.to_s)
         publisher.send(:broadcast, 'it_happended')
       end
 
@@ -105,7 +105,7 @@ describe Wisper::Publisher do
 
         publisher = publisher_sub_klass.new
 
-        publisher.add_listener(listener, :scope => publisher_super_klass)
+        publisher.subscribe(listener, :scope => publisher_super_klass)
         publisher.send(:broadcast, 'it_happended')
       end
     end
@@ -171,7 +171,7 @@ describe Wisper::Publisher do
     end
 
     it 'returns publisher so methods can be chained' do
-      expect(publisher.add_listener(listener, :on => 'so_did_this')).to \
+      expect(publisher.subscribe(listener, :on => 'so_did_this')).to \
         eq publisher
     end
 
@@ -180,14 +180,61 @@ describe Wisper::Publisher do
     end
   end
 
+  describe '.on' do
+    let(:insider) { double('insider') }
+
+    it 'subscribes block to given event' do
+      expect(insider).to receive(:yes).once
+
+      publisher.on(:something_happened) do
+        insider.yes
+      end
+
+      publisher.send(:broadcast, :something_happened)
+      publisher.send(:broadcast, :and_so_did_this)
+    end
+
+    it 'subscribes block to given events' do
+      expect(insider).to receive(:yes).twice
+
+      publisher.on(:something_happened, :and_so_did_this) do
+        insider.yes
+      end
+
+      publisher.send(:broadcast, :something_happened)
+      publisher.send(:broadcast, :and_so_did_this)
+    end
+
+    it 'raise an error if no events given' do
+      expect { publisher.on() {} }.to raise_error(ArgumentError)
+    end
+
+    it 'returns publisher so methods can be chained' do
+      expect(publisher.on(:foo) {}).to eq publisher
+    end
+  end
+
+  # @deprecated
+  describe '.add_listener' do
+    it 'is aliased to .subscribe' do
+      expect(publisher).to receive(:subscribe)
+      silence_warnings do
+        publisher.add_listener(listener)
+      end
+    end
+  end
+
+  # @deprecated
   describe '.add_block_listener' do
     let(:insider) { double('insider') }
 
     it 'subscribes given block to all events' do
       expect(insider).to receive(:it_happened).twice
 
-      publisher.add_block_listener do
-        insider.it_happened
+      silence_warnings do
+        publisher.add_block_listener do
+          insider.it_happened
+        end
       end
 
       publisher.send(:broadcast, 'something_happened')
@@ -198,8 +245,10 @@ describe Wisper::Publisher do
       it '.add_block_listener subscribes block to an event' do
         expect(insider).not_to receive(:it_happened).once
 
-        publisher.add_block_listener(:on => 'something_happened') do
-          insider.it_happened
+        silence_warnings do
+          publisher.add_block_listener(:on => 'something_happened') do
+            insider.it_happened
+          end
         end
 
         publisher.send(:broadcast, 'something_happened')
@@ -209,9 +258,11 @@ describe Wisper::Publisher do
       it '.add_block_listener subscribes block to all listed events' do
         expect(insider).to receive(:it_happened).twice
 
-        publisher.add_block_listener(
-          :on => ['something_happened', 'and_so_did_this']) do
-          insider.it_happened
+        silence_warnings do
+          publisher.add_block_listener(
+            :on => ['something_happened', 'and_so_did_this']) do
+            insider.it_happened
+          end
         end
 
         publisher.send(:broadcast, 'something_happened')
@@ -221,34 +272,20 @@ describe Wisper::Publisher do
     end
 
     it 'returns publisher so methods can be chained' do
-      expect(publisher.add_block_listener(:on => 'this_thing_happened') do
-      end).to eq publisher
-    end
-  end
-
-  describe '.on (alternative block syntax)' do
-    let(:insider) { double('insider') }
-
-    it 'subscribes given block to an event' do
-      expect(insider).to receive(:it_happened)
-
-      publisher.on(:something_happened) do
-        insider.it_happened
+      silence_warnings do
+        expect(publisher.add_block_listener(:on => 'this_thing_happened') do
+        end).to eq publisher
       end
-
-      publisher.send(:broadcast, 'something_happened')
     end
+  end
 
-    it 'subscribes given block to multiple events' do
-      expect(insider).to receive(:it_happened).twice
-
-      publisher.on(:something_happened, :and_so_did_this) do
-        insider.it_happened
+  # @deprecated
+  describe '.respond_to (alternative block syntax)' do
+    it 'delegates to .on' do
+      expect(publisher).to receive(:on).with(:foobar)
+      silence_warnings do
+        publisher.respond_to(:foobar) {  }
       end
-
-      publisher.send(:broadcast, 'something_happened')
-      publisher.send(:broadcast, 'and_so_did_this')
-      publisher.send(:broadcast, 'but_not_this')
     end
   end
 
@@ -257,7 +294,7 @@ describe Wisper::Publisher do
       expect(listener).not_to receive(:so_did_this)
       allow(listener).to receive(:respond_to?).and_return(false)
 
-      publisher.add_listener(listener, :on => 'so_did_this')
+      publisher.subscribe(listener, :on => 'so_did_this')
 
       publisher.send(:broadcast, 'so_did_this')
     end
@@ -266,7 +303,7 @@ describe Wisper::Publisher do
       it 'is indifferent to string and symbol' do
         expect(listener).to receive(:this_happened).twice
 
-        publisher.add_listener(listener)
+        publisher.subscribe(listener)
 
         publisher.send(:broadcast, 'this_happened')
         publisher.send(:broadcast, :this_happened)
@@ -275,7 +312,7 @@ describe Wisper::Publisher do
       it 'is indifferent to dasherized and underscored strings' do
         expect(listener).to receive(:this_happened).twice
 
-        publisher.add_listener(listener)
+        publisher.subscribe(listener)
 
         publisher.send(:broadcast, 'this_happened')
         publisher.send(:broadcast, 'this-happened')
@@ -290,25 +327,30 @@ describe Wisper::Publisher do
     end
 
     it 'returns local listeners' do
-       publisher.add_listener(listener)
+       publisher.subscribe(listener)
        expect(publisher.listeners).to eq [listener]
        expect(publisher.listeners.size).to eq 1
     end
   end
 
-  describe '#add_listener' do
+  describe '#subscribe' do
     let(:publisher_klass_1) { publisher_class }
     let(:publisher_klass_2) { publisher_class }
 
-    it 'subscribes listeners to all instances of publisher' do
-      publisher_klass_1.add_listener(listener)
+    it 'subscribes listener to all instances of publisher' do
+      publisher_klass_1.subscribe(listener)
       expect(listener).to receive(:it_happened).once
       publisher_klass_1.new.send(:broadcast, 'it_happened')
       publisher_klass_2.new.send(:broadcast, 'it_happened')
     end
+  end
 
+  describe '#add_listener' do # deprecated
     it 'is aliased to #subscribe' do
-      expect(publisher_klass_1).to respond_to(:subscribe)
+      expect(publisher).to receive(:subscribe)
+      silence_warnings do
+        publisher.add_listener(listener)
+      end
     end
   end
 end

data/spec/lib/wisper_spec.rb

@@ -78,6 +78,16 @@ describe Wisper do
     end
   end
 
+  it '.publisher returns the Publisher module' do
+    expect(Wisper.publisher).to eq Wisper::Publisher
+  end
+
+  it '.clear clears all global listeners' do
+    10.times { Wisper.subscribe(double) }
+    Wisper.clear
+    expect(Wisper::GlobalListeners.listeners).to be_empty
+  end
+
   it '.configuration returns configuration' do
     expect(Wisper.configuration).to be_an_instance_of(Wisper::Configuration)
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wisper
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Kris Leech
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-06 00:00:00.000000000 Z
+date: 2014-10-25 00:00:00.000000000 Z
 dependencies: []
 description: pub/sub for Ruby objects
 email: