Merge pull request #11 from jdickey/issue-10

[Fix #10] Reworked `#payload_for` added `#payloads_for`.

README.md

@@ -54,21 +54,76 @@ describe SomeWisperPublishingClass do
   before :each do
     # some setup
     subscriber.define_message :success
-    subscriber.define_Message :failure
+    subscriber.define_message :failure
     command.subscribe subscriber
     command.do_something_that_broadcasts_a_success
   end
 
   it 'was successful' do
-    payload = subscriber.payload_for(:success).to_a.first
-    expect(payload).to be_a WhatYouExpectOnSuccess # as opposed to nil
+    payload = subscriber.payload_for(:success, 0)
+    expect(payload.first).to be_a WhatYouExpectOnSuccess # as opposed to nil
   end
 
   # ...
 end
 ```
 
-You get the idea. If not, open an issue or ask on our Gitter channel.
+You get the idea. If not, open an issue or ask on our
+[Gitter channel](https://gitter.im/jdickey/wisper_subscription).
+
+### Methods
+
+#### `initialize`
+
+Parameters: none.
+
+Initialises instance internal state.
+
+#### `define_message(message)`
+
+Parameters:
+
+1. `message` (a Symbol; e.g., `:bangbang`)
+
+Returns: `self`
+
+Defines a *listener method* (e.g., `#bangbang`) to receive events published by a
+[Wisper publisher](https://github.com/krisleech/wisper/#publishing) or similar
+mechaism. Any parameters a listener method is called with will be retreivaable
+by using the `#payload_for` or `#payloads_for` methods (see below).
+
+Defines a query method (e.g., `#bangbang?`) which returns `true` if payloads for
+the message have been received; `false` otherwise.
+
+#### `payloads_for(message)`
+
+Parameters:
+
+1. `message` (a Symbol, e.g., `:bangbang`)
+
+Returns: an Array
+
+Returns an Array of all *payloads* received by the listener method corresponding
+to the parameter. If no calls to the listener method have been made, *or* if the
+listener method has not been defined because `#define_message` has not been
+called using that `message`, then an empty Array is returned.
+
+#### `payload_for(message, index = 0)`
+
+Parameters:
+
+1. `message` (a Symbol, e.g., `:bangbang`)
+1. `index` (an integer, defaulting to 0)
+
+Returns: an Array or `nil`
+
+Returns an Array containing the *payload* received by the `index`th invocation
+of the listener method (zero-based). A *payload* is simply the set of (zero or)
+more) parameters sent to the listener method. If no calls to the listener method
+have been made, *or* if the listener method has not been defined because
+`#define_message` has not been called using that `message`, then this method
+returns `nil`. If the listener method *has* been defined but the specified index
+is outside the range of received payloads, then returns an empty Array.
 
 ## Contributing
 

lib/wisper_subscription.rb

@@ -1,6 +1,8 @@
 
 require 'wisper_subscription/version'
 
+require 'awesome_print'
+
 # Collects and reports on messages sent to an instance.
 class WisperSubscription
   def initialize
@@ -13,11 +15,16 @@ def define_message(message)
     @message = message
     add_internals_entry
     add_query_method
-    add_responder_method
+    add_listener_method
     self
   end
 
-  def payload_for(message)
+  def payload_for(message, index = 0)
+    return nil unless @internals.key? message
+    payloads_for(message)[index]
+  end
+
+  def payloads_for(message)
     return empty_payload unless @internals.key? message
     @internals[message]
   end
@@ -49,7 +56,7 @@ def add_query_method
     self
   end
 
-  def add_responder_method
+  def add_listener_method
     message = @message
     define_singleton_method @message.to_sym do |*params|
       @internals[message].push params

lib/wisper_subscription/version.rb

@@ -1,5 +1,5 @@
 
 # Collects and reports on messages sent to an instance.
 class WisperSubscription
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

spec/spec_helper.rb

@@ -7,4 +7,7 @@
 
 $LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
 
+require 'awesome_print'
+require 'pry'
+
 require 'wisper_subscription'

spec/wisper_subscription_spec.rb

@@ -69,16 +69,70 @@
   end # describe '#define_message'
 
   describe '#payload_for' do
+    describe 'accepts two parameters, with' do
+      let(:method) { described_class.new.method :payload_for }
+
+      it 'the first, :message, being required' do
+        expect(method.parameters.count).to eq 2
+        expect(method.parameters.first).to eq [:req, :message]
+      end
+
+      it 'the second, :index, being optional' do
+        expect(method.parameters.last).to eq [:opt, :index]
+      end
+    end # describe 'accepts two parameters, with'
+
+    describe 'returns nil when' do
+      it 'no messages have been defined' do
+        expect(obj.payload_for message).to eq nil
+      end
+
+      it 'the specified message has been defined but not received' do
+        obj.define_message other_message
+        expect(obj.payload_for message).to eq nil
+      end
+
+      it 'the specified index exceeds the range of received messages' do
+        obj.define_message message
+        obj.send message, 'foo'
+        expect(obj.payload_for message, 52).to eq nil
+      end
+    end # describe 'returns nil when'
+
+    context 'when the message was received and the index is in range' do
+      before :each do
+        obj.define_message message
+      end
+
+      it 'returns an Array containing the specified payload when supplied' do
+        obj.send message, 'foo'
+        expect(obj.payload_for message, 0).to eq ['foo']
+      end
+
+      it 'returns an empty Array if no payload for the message was specified' do
+        obj.send message
+        expect(obj.payload_for message, 0).to eq []
+      end
+    end # context 'when the message was received and the index is in range'
+
+    fit 'uses zero as a default for the second (index) parameter' do
+      obj.define_message message
+      [:foo, :bar, :baz].each { |payload| obj.send message, payload }
+      expect(obj.payload_for message).to eq [:foo]
+    end
+  end # describe '#payload_for'
+
+  describe '#payloads_for' do
     it 'takes a single parameter' do
-      method = obj.method :payload_for
+      method = obj.method :payloads_for
       expect(method.arity).to eq 1
     end
 
     describe 'returns a no-payloads-received indicator when' do
       let(:none_received) { [] }
 
       after :each do
-        expect(obj.payload_for message).to eq none_received
+        expect(obj.payloads_for message).to eq none_received
       end
 
       it 'no messages have been defined' do
@@ -94,14 +148,31 @@
     end # describe 'returns a no-payloads-received indicator when'
 
     describe 'returns the payload(s) received for the specified message when' do
-      it 'payloads for that message have been stored' do
+      before :each do
         obj.define_message message
-        expected = 'testing'
-        obj.instance_variable_get(:@internals)[message].push expected
-        expect(obj.payload_for message).to eq Array.new([expected])
+      end
+
+      it 'a single payload for that message has been stored' do
+        expected = %w(This is a test.)
+        obj.send message, *expected
+        payloads = obj.payloads_for message
+        expect(payloads).to be_an Array
+        expect(payloads.count).to eq 1 # One payload has been delivered
+        payload = payloads.first
+        expect(payload.count).to eq expected.count
+        expect(payload).to eq expected
+      end
+
+      it 'multiple payloads for that message have been stored' do
+        obj.send message, 'one'
+        obj.send message, 'two', 'three'
+        payloads = obj.payloads_for message
+        expect(payloads.count).to eq 2 # Two payloads delivered
+        expect(payloads.first).to eq ['one']
+        expect(payloads.last).to eq %w(two three)
       end
     end # describe 'returns the payload(s) received for the ... message when'
-  end # describe '#payload_for'
+  end # describe '#payloads_for'
 
   describe '#respond_to?' do
     it 'returns true for any query method' do

wisper_subscription.gemspec

@@ -23,9 +23,9 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'rubocop', '>= 0.28.0'
   spec.add_development_dependency 'simplecov', '>= 0.9.1'
-  # spec.add_development_dependency 'awesome_print'
-  # spec.add_development_dependency 'pry-byebug'
-  # spec.add_development_dependency 'pry-doc'
+  spec.add_development_dependency 'awesome_print'
+  spec.add_development_dependency 'pry-byebug'
+  spec.add_development_dependency 'pry-doc'
 
   spec.description   = %q{May be used to subscribe to Wisper broadcasts, or other
 similar mechanisms. Define what messages you want an instance to respond to and,