mcmire-rr 1.0.5.rc1

data/lib/rr/times_called_matchers/at_most_matcher.rb

@@ -0,0 +1,23 @@
+module RR
+  module TimesCalledMatchers #:nodoc:
+    class AtMostMatcher < TimesCalledMatcher
+      include Terminal
+
+      def possible_match?(times_called)
+        times_called <= @times
+      end
+
+      def matches?(times_called)
+        times_called <= @times
+      end
+
+      def attempt?(times_called)
+        times_called < @times
+      end
+
+      def expected_times_message
+        "at most #{@times.inspect} times"
+      end
+    end
+  end
+end

data/lib/rr/times_called_matchers/integer_matcher.rb

@@ -0,0 +1,19 @@
+module RR
+  module TimesCalledMatchers #:nodoc:
+    class IntegerMatcher < TimesCalledMatcher
+      include Terminal
+
+      def possible_match?(times_called)
+        times_called <= @times
+      end
+
+      def matches?(times_called)
+        times_called == @times
+      end
+
+      def attempt?(times_called)
+        times_called < @times
+      end
+    end
+  end
+end

data/lib/rr/times_called_matchers/never_matcher.rb

@@ -0,0 +1,23 @@
+module RR
+  module TimesCalledMatchers #:nodoc:
+    class NeverMatcher < TimesCalledMatcher
+      include Terminal
+
+      def initialize
+        super 0
+      end
+
+      def possible_match?(times_called)
+        true
+      end
+
+      def matches?(times_called)
+        true
+      end
+
+      def attempt?(times_called)
+        raise RR::Errors::TimesCalledError, error_message(1)
+      end
+    end
+  end
+end

data/lib/rr/times_called_matchers/non_terminal.rb

@@ -0,0 +1,27 @@
+module RR
+  module TimesCalledMatchers
+    # Including this module marks the TimesCalledMatcher as NonTerminal.
+    # Being NonTerminal means the Double will not "terminate" even when
+    # called infinite times.
+    #
+    # The Double that uses a NonTerminal TimesCalledMatcher will
+    # continue using the Double when passed the matching arguments.
+    # This is done by the attempt? always returning true.
+    #
+    # This is in opposition to Terminal TimesCalledMatchers, where
+    # attempt? will eventually return false.
+    module NonTerminal #:nodoc:
+      def terminal?
+        false
+      end
+
+      def possible_match?(times_called)
+        true
+      end
+
+      def attempt?(times_called)
+        true
+      end
+    end
+  end
+end

data/lib/rr/times_called_matchers/proc_matcher.rb

@@ -0,0 +1,11 @@
+module RR
+  module TimesCalledMatchers
+    class ProcMatcher < TimesCalledMatcher #:nodoc:
+      include NonTerminal
+
+      def matches?(times_called)
+        @times.call(times_called)
+      end
+    end
+  end
+end

data/lib/rr/times_called_matchers/range_matcher.rb

@@ -0,0 +1,21 @@
+module RR
+  module TimesCalledMatchers
+    class RangeMatcher < TimesCalledMatcher #:nodoc:
+      include Terminal
+
+      def possible_match?(times_called)
+        return true if times_called < @times.begin
+        return true if @times.include?(times_called)
+        return false
+      end
+
+      def matches?(times_called)
+        @times.include?(times_called)
+      end
+
+      def attempt?(times_called)
+        possible_match?(times_called)
+      end
+    end
+  end
+end

data/lib/rr/times_called_matchers/terminal.rb

@@ -0,0 +1,20 @@
+module RR
+  module TimesCalledMatchers
+    # Including this module marks the TimesCalledMatcher as Terminal.
+    # Being Terminal the Double will "terminate" when times called is
+    # finite.
+    #
+    # The Double that uses a Terminal TimesCalledMatcher will
+    # eventually be passed over to the next Double when passed
+    # the matching arguments enough times. This is done by the attempt?
+    # method returning false when executed a finite number of times.
+    #
+    # This is in opposition to NonTerminal TimesCalledMatchers, where
+    # attempt? will always return true.
+    module Terminal #:nodoc:
+      def terminal?
+        true
+      end
+    end
+  end
+end

data/lib/rr/times_called_matchers/times_called_matcher.rb

@@ -0,0 +1,44 @@
+module RR
+  module TimesCalledMatchers
+    class TimesCalledMatcher #:nodoc:
+      extend(Module.new do
+        def create(value)
+          return value if value.is_a?(TimesCalledMatcher)
+          return IntegerMatcher.new(value) if value.is_a?(Integer)
+          return RangeMatcher.new(value) if value.is_a?(Range )
+          return ProcMatcher.new(value) if value.is_a?(Proc)
+          raise ArgumentError, "There is no TimesCalledMatcher for #{value.inspect}."
+        end
+      end)
+
+      attr_reader :times
+
+      def initialize(times)
+        @times = times
+      end
+
+      def matches?(times_called)
+      end
+
+      def attempt?(times_called)
+      end
+
+      def error_message(times_called)
+        "Called #{times_called.inspect} #{pluralized_time(times_called)}.\nExpected #{expected_times_message}."
+      end
+
+      def ==(other)
+        self.class == other.class && self.times == other.times
+      end
+
+      def expected_times_message
+        "#{@times.inspect} times"
+      end
+
+      protected
+      def pluralized_time(times_called)
+        (times_called == 1) ? "time" : "times"
+      end
+    end
+  end
+end

data/lib/rr/wildcard_matchers.rb

@@ -0,0 +1,158 @@
+=begin rdoc
+
+= Writing your own custom wildcard matchers.
+Writing new wildcard matchers is not too difficult.  If you've ever written
+a custom expectation in RSpec, the implementation is very similar.
+
+As an example, let's say that you want a matcher that will match any number
+divisible by a certain integer.  In use, it might look like this:
+
+  # Will pass if BananaGrabber#bunch_bananas is called with an integer
+  # divisible by 5.
+
+  mock(BananaGrabber).bunch_bananas(divisible_by(5))
+
+To implement this, we need a class RR::WildcardMatchers::DivisibleBy with 
+these instance methods:
+
+* ==(other)
+* eql?(other) (usually aliased to #==)
+* inspect
+* wildcard_match?(other)
+
+and optionally, a sensible initialize method.  Let's look at each of these.
+
+=== .initialize
+
+Most custom wildcard matchers will want to define initialize to store
+some information about just what should be matched.  DivisibleBy#initialize
+might look like this:
+
+  class RR::WildcardMatchers::DivisibleBy
+    def initialize(divisor)
+      @expected_divisor = divisor
+    end
+  end
+
+=== #==(other)
+DivisibleBy#==(other) should return true if other is a wildcard matcher that
+matches the same things as self, so a natural way to write DivisibleBy#== is:
+
+  
+  class RR::WildcardMatchers::DivisibleBy
+    def ==(other)
+      # Ensure that other is actually a DivisibleBy
+      return false unless other.is_a?(self.class)
+
+      # Does other expect to match the same divisor we do?
+      self.expected_divisor = other.expected_divisor
+    end
+  end
+
+Note that this implementation of #== assumes that we've also declared
+  attr_reader :expected_divisor
+
+=== #inspect
+
+Technically we don't have to declare DivisibleBy#inspect, since inspect is
+defined for every object already.  But putting a helpful message in inspect
+will make test failures much clearer, and it only takes about two seconds to
+write it, so let's be nice and do so:
+
+  class RR::WildcardMatchers::DivisibleBy
+    def inspect
+      "integer divisible by #{expected.divisor}"
+    end
+  end
+
+Now if we run the example from above:
+
+  mock(BananaGrabber).bunch_bananas(divisible_by(5))
+
+and it fails, we get a helpful message saying
+
+  bunch_bananas(integer divisible by 5)
+  Called 0 times.
+  Expected 1 times.
+
+=== #wildcard_matches?(other)
+
+wildcard_matches? is the method that actually checks the argument against the
+expectation.  It should return true if other is considered to match,
+false otherwise.  In the case of DivisibleBy, wildcard_matches? reads:
+
+  class RR::WildcardMatchers::DivisibleBy
+    def wildcard_matches?(other)
+      # If other isn't a number, how can it be divisible by anything?
+      return false unless other.is_a?(Numeric)
+
+      # If other is in fact divisible by expected_divisor, then 
+      # other modulo expected_divisor should be 0.
+
+      other % expected_divisor == 0
+    end
+  end
+
+=== A finishing touch: wrapping it neatly
+
+We could stop here if we were willing to resign ourselves to using
+DivisibleBy this way:
+
+  mock(BananaGrabber).bunch_bananas(DivisibleBy.new(5))
+
+But that's less expressive than the original:
+
+  mock(BananaGrabber).bunch_bananas(divisible_by(5))
+
+To be able to use the convenient divisible_by matcher rather than the uglier
+DivisibleBy.new version, re-open the module RR::Adapters::RRMethods and
+define divisible_by there as a simple wrapper around DivisibleBy.new:
+
+  module RR::Adapters::RRMethods
+    def divisible_by(expected_divisor)
+      RR::WildcardMatchers::DivisibleBy.new(expected_divisor)
+    end
+  end
+
+== Recap
+
+Here's all the code for DivisibleBy in one place for easy reference:
+
+  class RR::WildcardMatchers::DivisibleBy
+    def initialize(divisor)
+      @expected_divisor = divisor
+    end
+
+    def ==(other)
+      # Ensure that other is actually a DivisibleBy
+      return false unless other.is_a?(self.class)
+
+      # Does other expect to match the same divisor we do?
+      self.expected_divisor = other.expected_divisor
+    end
+
+    def inspect
+      "integer divisible by #{expected.divisor}"
+    end
+  
+    def wildcard_matches?(other)
+      # If other isn't a number, how can it be divisible by anything?
+      return false unless other.is_a?(Numeric)
+
+      # If other is in fact divisible by expected_divisor, then 
+      # other modulo expected_divisor should be 0.
+
+      other % expected_divisor == 0
+    end
+  end
+  
+  module RR::Adapters::RRMethods
+    def divisible_by(expected_divisor)
+      RR::WildcardMatchers::DivisibleBy.new(expected_divisor)
+    end
+  end
+
+=end
+
+module RR::WildcardMatchers
+end

data/lib/rr/wildcard_matchers/anything.rb

@@ -0,0 +1,18 @@
+module RR
+  module WildcardMatchers
+    class Anything
+      def wildcard_match?(other)
+        true
+      end
+
+      def ==(other)
+        other.is_a?(self.class)
+      end
+      alias_method :eql?, :==
+
+      def inspect
+        'anything'
+      end
+    end
+  end
+end

data/lib/rr/wildcard_matchers/boolean.rb

@@ -0,0 +1,23 @@
+module RR
+  module WildcardMatchers
+    class Boolean
+      def wildcard_match?(other)
+        self == other || is_a_boolean?(other)
+      end
+
+      def ==(other)
+        other.is_a?(self.class)
+      end
+      alias_method :eql?, :==
+
+      def inspect
+        'boolean'
+      end
+
+      protected
+      def is_a_boolean?(subject)
+        subject.is_a?(TrueClass) || subject.is_a?(FalseClass)
+      end
+    end
+  end
+end

data/lib/rr/wildcard_matchers/duck_type.rb

@@ -0,0 +1,32 @@
+module RR
+  module WildcardMatchers
+    class DuckType
+      attr_accessor :required_methods
+
+      def initialize(*required_methods)
+        @required_methods = required_methods
+      end
+
+      def wildcard_match?(other)
+        return true if self == other
+        required_methods.each do |m|
+          return false unless other.respond_to?(m)
+        end
+        return true
+      end
+
+      def inspect
+        formatted_required_methods = required_methods.collect do |method_name|
+          method_name.inspect
+        end.join(', ')
+        "duck_type(#{formatted_required_methods})"
+      end
+
+      def ==(other)
+        return false unless other.is_a?(self.class)
+        self.required_methods == other.required_methods
+      end
+      alias_method :eql?, :==
+    end
+  end
+end

data/lib/rr/wildcard_matchers/hash_including.rb

@@ -0,0 +1,29 @@
+module RR
+  module WildcardMatchers
+    class HashIncluding
+      attr_reader :expected_hash
+
+      def initialize(expected_hash)
+        @expected_hash = expected_hash.clone
+      end
+
+      def wildcard_match?(other)
+        return true if self == other
+        expected_hash.each_pair do |key, value|
+          return false unless other.has_key?(key) && other[key] == expected_hash[key]
+        end
+        return true
+      end
+
+      def inspect
+        "hash_including(#{expected_hash.inspect})"
+      end
+
+      def ==(other)
+        return false unless other.is_a?(self.class)
+        self.expected_hash == other.expected_hash
+      end
+      alias_method :eql?, :==
+    end
+  end
+end