matchi 3.0.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16b38ee69034c01d5f2961a5d4e14b6c150cad89a9368f7c0cf84071761e2999
-  data.tar.gz: f76f7a3286443d49f6e449af9ffefdb2f38b9d974aada733e1a611d75c627199
+  metadata.gz: 5596c7ba2d1153eadaa1ba438b009c0cc17954a360b4192bb6419c674d864822
+  data.tar.gz: 0c717e7642961b8707433584c58a1e2369f810c11114caa7530c890563df78a3
 SHA512:
-  metadata.gz: ed8abd4dd002520dc4740fc80b91573098e3242319e74b807e6621482beb131d4a40e299584fc507bacbb806867a00691a3f4bdcebf611dd2c45eb1b90e9e76e
-  data.tar.gz: 3fd0b621816f91d0569fdebeb4a8c80c55890f83250ed87b0df2cd1b7683e02f390df159f372f6e87f62aab853b7d8042d438f1efc31f83fd3b169a12eab2b8e
+  metadata.gz: 8e89b77b4f7fd25fc53ea570b865b3479be5a3291bc437f55b3ea126111fdd120afd907439ec87c565bbb28b4fe6e7be34a932a218e55933bb3d4bb890b0edcf
+  data.tar.gz: f19a1f799d1b8f9c1f40dc747c00863ae1cd9bf1ed545aabdea774e4c658a242a74d2bd6f03709fe124786f327fd7401b104aa9e567496265b966937c61841e3

data/README.md

@@ -12,9 +12,9 @@
 
 ## Project goals
 
-* Provide a collection of useful generic matchers.
 * Adding matchers should be as simple as possible.
 * Being framework agnostic and easy to integrate.
+* Avoid false positives/negatives due to malicious actual values.
 
 ## Installation
 
@@ -52,16 +52,20 @@ All examples here assume that this has been done.
 
 ### Anatomy of a matcher
 
-A __Matchi__ matcher is just an object that responds to the `matches?` method with a block as argument, and returns a boolean. That's all it is.
+A __Matchi__ matcher is an object that must respond to the `matches?` method with a block as argument, and return a boolean.
 
-But let's see some examples.
+To facilitate the integration of the matchers in other tools, __Matchi__ matchers may expose expected values via the `expected` method.
 
 ### Built-in matchers
 
+Here is the collection of useful generic matchers.
+
 **Equivalence** matcher:
 
 ```ruby
 matcher = Matchi::Eq.new("foo")
+
+matcher.expected           # => "foo"
 matcher.matches? { "foo" } # => true
 ```
 
@@ -69,20 +73,35 @@ matcher.matches? { "foo" } # => true
 
 ```ruby
 matcher = Matchi::Be.new(:foo)
+
+matcher.expected          # => :foo
 matcher.matches? { :foo } # => true
 ```
 
+**Comparisons** matcher:
+
+```ruby
+matcher = Matchi::BeWithin.new(8).of(37)
+
+matcher.expected        # => 37
+matcher.matches? { 42 } # => true
+```
+
 **Regular expressions** matcher:
 
 ```ruby
 matcher = Matchi::Match.new(/^foo$/)
+
+matcher.expected           # => /^foo$/
 matcher.matches? { "foo" } # => true
 ```
 
 **Expecting errors** matcher:
 
 ```ruby
-matcher = Matchi::RaiseException.new(NameError)
+matcher = Matchi::RaiseException.new(:NameError)
+
+matcher.expected          # => "NameError"
 matcher.matches? { Boom } # => true
 ```
 
@@ -90,30 +109,56 @@ matcher.matches? { Boom } # => true
 
 ```ruby
 matcher = Matchi::BeAnInstanceOf.new(:String)
+
+matcher.expected           # => "String"
 matcher.matches? { "foo" } # => true
 ```
 
+**Predicate** matcher:
+
+```ruby
+matcher = Matchi::Predicate.new(:be_empty)
+
+matcher.expected        # => [:empty?, [], {}, nil]
+matcher.matches? { [] } # => true
+
+matcher = Matchi::Predicate.new(:have_key, :foo)
+
+matcher.expected                 # => [:has_key?, [:foo], {}, nil]
+matcher.matches? { { foo: 42 } } # => true
+```
+
 **Change** matcher:
 
 ```ruby
 object = []
 matcher = Matchi::Change.new(object, :length).by(1)
+
+matcher.expected                 # => 1
 matcher.matches? { object << 1 } # => true
 
 object = []
 matcher = Matchi::Change.new(object, :length).by_at_least(1)
+
+matcher.expected                 # => 1
 matcher.matches? { object << 1 } # => true
 
 object = []
 matcher = Matchi::Change.new(object, :length).by_at_most(1)
+
+matcher.expected                 # => 1
 matcher.matches? { object << 1 } # => true
 
 object = "foo"
 matcher = Matchi::Change.new(object, :to_s).from("foo").to("FOO")
+
+matcher.expected                    # => "FOO"
 matcher.matches? { object.upcase! } # => true
 
 object = "foo"
 matcher = Matchi::Change.new(object, :to_s).to("FOO")
+
+matcher.expected                    # => "FOO"
 matcher.matches? { object.upcase! } # => true
 ```
 
@@ -121,6 +166,8 @@ matcher.matches? { object.upcase! } # => true
 
 ```ruby
 matcher = Matchi::Satisfy.new { |value| value == 42 }
+
+matcher.expected        # => #<Proc:0x00007fbaafc65540>
 matcher.matches? { 42 } # => true
 ```
 
@@ -133,13 +180,19 @@ A **Be the answer** matcher:
 ```ruby
 module Matchi
   class BeTheAnswer
+    def expected
+      42
+    end
+
     def matches?
-      42.equal?(yield)
+      expected.equal?(yield)
     end
   end
 end
 
 matcher = Matchi::BeTheAnswer.new
+
+matcher.expected        # => 42
 matcher.matches? { 42 } # => true
 ```
 
@@ -157,6 +210,7 @@ module Matchi
 end
 
 matcher = Matchi::BePrime.new
+
 matcher.matches? { 42 } # => false
 ```
 
@@ -178,6 +232,8 @@ module Matchi
 end
 
 matcher = Matchi::StartWith.new("foo")
+
+matcher.expected              # => "foo"
 matcher.matches? { "foobar" } # => true
 ```
 

data/lib/matchi/be.rb

@@ -3,6 +3,9 @@
 module Matchi
   # *Identity* matcher.
   class Be
+    # @return [#equal?] The expected identical object.
+    attr_reader :expected
+
     # Initialize the matcher with an object.
     #
     # @example
@@ -21,24 +24,26 @@ module Matchi
     #   require "matchi/be"
     #
     #   matcher = Matchi::Be.new(:foo)
+    #
+    #   matcher.expected          # => :foo
     #   matcher.matches? { :foo } # => true
     #
     # @yieldreturn [#object_id] The actual value to compare to the expected
     #   one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?(*, **)
-      @expected.equal?(yield)
+    def matches?
+      expected.equal?(yield)
     end
 
     # A string containing a human-readable representation of the matcher.
     def inspect
-      "#{self.class}(#{@expected.inspect})"
+      "#{self.class}(#{expected.inspect})"
     end
 
     # Returns a string representing the matcher.
     def to_s
-      "be #{@expected.inspect}"
+      "be #{expected.inspect}"
     end
   end
 end

data/lib/matchi/be_an_instance_of.rb

@@ -3,6 +3,9 @@
 module Matchi
   # *Type/class* matcher.
   class BeAnInstanceOf
+    # @return [String] The expected class name.
+    attr_reader :expected
+
     # Initialize the matcher with (the name of) a class or module.
     #
     # @example
@@ -10,9 +13,9 @@ module Matchi
     #
     #   Matchi::BeAnInstanceOf.new(String)
     #
-    # @param expected [#to_s] A (name of a) class or module.
+    # @param expected [Class, #to_s] The expected class name.
     def initialize(expected)
-      @expected = String(expected).to_sym
+      @expected = String(expected)
     end
 
     # Boolean comparison between the class of the actual value and the
@@ -22,23 +25,25 @@ module Matchi
     #   require "matchi/be_an_instance_of"
     #
     #   matcher = Matchi::BeAnInstanceOf.new(String)
+    #
+    #   matcher.expected           # => "String"
     #   matcher.matches? { "foo" } # => true
     #
     # @yieldreturn [#class] the actual value to compare to the expected one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?(*, **)
-      self.class.const_get(@expected).equal?(yield.class)
+    def matches?
+      self.class.const_get(expected).equal?(yield.class)
     end
 
     # A string containing a human-readable representation of the matcher.
     def inspect
-      "#{self.class}(#{@expected})"
+      "#{self.class}(#{expected})"
     end
 
     # Returns a string representing the matcher.
     def to_s
-      "be an instance of #{@expected}"
+      "be an instance of #{expected}"
     end
   end
 end

data/lib/matchi/be_within.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative File.join("be_within", "of")
+
+module Matchi
+  # Wraps the target of a be_within matcher.
+  class BeWithin
+    # Initialize a wrapper of the be_within matcher with a numeric value.
+    #
+    # @example
+    #   require "matchi/be_within"
+    #
+    #   Matchi::BeWithin.new(1)
+    #
+    # @param delta [Numeric] A numeric value.
+    def initialize(delta)
+      @delta = delta
+    end
+
+    # Specifies an expected numeric value.
+    #
+    # @example
+    #   require "matchi/be_within"
+    #
+    #   be_within_wrapper = Matchi::BeWithin.new(1)
+    #   be_within_wrapper.of(41)
+    #
+    # @param expected [Numeric] The expected value.
+    #
+    # @return [#matches?] A *be_within of* matcher.
+    def of(expected)
+      Of.new(@delta, expected)
+    end
+  end
+end

data/lib/matchi/be_within/of.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Matchi
+  class BeWithin
+    # *BeWithin of* matcher.
+    class Of
+      # @return [Numeric] An expected value.
+      attr_reader :expected
+
+      # Initialize the matcher with a delta and an expected value.
+      #
+      # @example
+      #   require "matchi/be_within/of"
+      #
+      #   Matchi::BeWithin::Of.new(1, 41)
+      #
+      # @param delta    [Numeric] The accepted variation of the actual value.
+      # @param expected [Numeric] The expected value.
+      def initialize(delta, expected)
+        @delta    = delta
+        @expected = expected
+      end
+
+      # Boolean comparison on the expected be_within by comparing the actual
+      # value and the expected value.
+      #
+      # @example
+      #   require "matchi/be_within/of"
+      #
+      #   matcher = Matchi::BeWithin::Of.new(1, 41)
+      #
+      #   matcher.expected        # => 41
+      #   matcher.matches? { 42 } # => true
+      #
+      # @yieldreturn [Numeric] The block of code to execute.
+      #
+      # @return [Boolean] Comparison between the actual and the expected values.
+      def matches?
+        (expected - yield).abs <= @delta
+      end
+
+      # A string containing a human-readable representation of the matcher.
+      def inspect
+        "#{self.class}(#{@delta}, #{expected})"
+      end
+
+      # Returns a string representing the matcher.
+      def to_s
+        "be within #{@delta} of #{expected}"
+      end
+    end
+  end
+end

data/lib/matchi/change.rb

@@ -32,14 +32,14 @@ module Matchi
     #
     #   object = []
     #
-    #   change = Matchi::Change.new(object, :length)
-    #   change.by_at_least(1)
+    #   change_wrapper = Matchi::Change.new(object, :length)
+    #   change_wrapper.by_at_least(1)
     #
-    # @param expected [#object_id] The minimum delta of the expected change.
+    # @param minimum_delta [#object_id] The minimum delta of the expected change.
     #
     # @return [#matches?] A *change by at least* matcher.
-    def by_at_least(expected)
-      ByAtLeast.new(expected, &@state)
+    def by_at_least(minimum_delta)
+      ByAtLeast.new(minimum_delta, &@state)
     end
 
     # Specifies a maximum delta of the expected change.
@@ -49,14 +49,14 @@ module Matchi
     #
     #   object = []
     #
-    #   change = Matchi::Change.new(object, :length)
-    #   change.by_at_most(1)
+    #   change_wrapper = Matchi::Change.new(object, :length)
+    #   change_wrapper.by_at_most(1)
     #
-    # @param expected [#object_id] The maximum delta of the expected change.
+    # @param maximum_delta [#object_id] The maximum delta of the expected change.
     #
     # @return [#matches?] A *change by at most* matcher.
-    def by_at_most(expected)
-      ByAtMost.new(expected, &@state)
+    def by_at_most(maximum_delta)
+      ByAtMost.new(maximum_delta, &@state)
     end
 
     # Specifies the delta of the expected change.
@@ -66,14 +66,14 @@ module Matchi
     #
     #   object = []
     #
-    #   change = Matchi::Change.new(object, :length)
-    #   change.by(1)
+    #   change_wrapper = Matchi::Change.new(object, :length)
+    #   change_wrapper.by(1)
     #
-    # @param expected [#object_id] The delta of the expected change.
+    # @param delta [#object_id] The delta of the expected change.
     #
     # @return [#matches?] A *change by* matcher.
-    def by(expected)
-      By.new(expected, &@state)
+    def by(delta)
+      By.new(delta, &@state)
     end
 
     # Specifies the original value.
@@ -81,14 +81,14 @@ module Matchi
     # @example
     #   require "matchi/change"
     #
-    #   change = Matchi::Change.new("foo", :to_s)
-    #   change.from("foo")
+    #   change_wrapper = Matchi::Change.new("foo", :to_s)
+    #   change_wrapper.from("foo")
     #
-    # @param expected [#object_id] The original value.
+    # @param old_value [#object_id] The original value.
     #
     # @return [#matches?] A *change from* wrapper.
-    def from(expected)
-      From.new(expected, &@state)
+    def from(old_value)
+      From.new(old_value, &@state)
     end
 
     # Specifies the new value to expect.
@@ -96,14 +96,14 @@ module Matchi
     # @example
     #   require "matchi/change"
     #
-    #   change = Matchi::Change.new("foo", :to_s)
-    #   change.to("FOO")
+    #   change_wrapper = Matchi::Change.new("foo", :to_s)
+    #   change_wrapper.to("FOO")
     #
-    # @param expected [#object_id] The new value to expect.
+    # @param new_value [#object_id] The new value to expect.
     #
     # @return [#matches?] A *change to* matcher.
-    def to(expected)
-      To.new(expected, &@state)
+    def to(new_value)
+      To.new(new_value, &@state)
     end
   end
 end

data/lib/matchi/change/by.rb

@@ -4,6 +4,9 @@ module Matchi
   class Change
     # *Change by* matcher.
     class By
+      # @return [#object_id] An expected delta.
+      attr_reader :expected
+
       # Initialize the matcher with an object and a block.
       #
       # @example
@@ -30,28 +33,30 @@ module Matchi
       #   object = []
       #
       #   matcher = Matchi::Change::By.new(1) { object.length }
+      #
+      #   matcher.expected                     # => 1
       #   matcher.matches? { object << "foo" } # => true
       #
       # @yieldreturn [#object_id] The block of code to execute.
       #
       # @return [Boolean] Comparison between the value before and after the
       #   code execution.
-      def matches?(*, **)
+      def matches?
         value_before = @state.call
         yield
         value_after = @state.call
 
-        @expected == (value_after - value_before)
+        expected == (value_after - value_before)
       end
 
       # A string containing a human-readable representation of the matcher.
       def inspect
-        "#{self.class}(#{@expected.inspect})"
+        "#{self.class}(#{expected.inspect})"
       end
 
       # Returns a string representing the matcher.
       def to_s
-        "change by #{@expected.inspect}"
+        "change by #{expected.inspect}"
       end
     end
   end

data/lib/matchi/change/by_at_least.rb

@@ -4,6 +4,9 @@ module Matchi
   class Change
     # *Change by at least* matcher.
     class ByAtLeast
+      # @return [#object_id] An expected delta.
+      attr_reader :expected
+
       # Initialize the matcher with an object and a block.
       #
       # @example
@@ -30,28 +33,30 @@ module Matchi
       #   object = []
       #
       #   matcher = Matchi::Change::ByAtLeast.new(1) { object.length }
+      #
+      #   matcher.expected                     # => 1
       #   matcher.matches? { object << "foo" } # => true
       #
       # @yieldreturn [#object_id] The block of code to execute.
       #
       # @return [Boolean] Comparison between the value before and after the
       #   code execution.
-      def matches?(*, **)
+      def matches?
         value_before = @state.call
         yield
         value_after = @state.call
 
-        @expected <= (value_after - value_before)
+        expected <= (value_after - value_before)
       end
 
       # A string containing a human-readable representation of the matcher.
       def inspect
-        "#{self.class}(#{@expected.inspect})"
+        "#{self.class}(#{expected.inspect})"
       end
 
       # Returns a string representing the matcher.
       def to_s
-        "change by at least #{@expected.inspect}"
+        "change by at least #{expected.inspect}"
       end
     end
   end

data/lib/matchi/change/by_at_most.rb

@@ -4,6 +4,9 @@ module Matchi
   class Change
     # *Change by at most* matcher.
     class ByAtMost
+      # @return [#object_id] An expected delta.
+      attr_reader :expected
+
       # Initialize the matcher with an object and a block.
       #
       # @example
@@ -30,28 +33,30 @@ module Matchi
       #   object = []
       #
       #   matcher = Matchi::Change::ByAtMost.new(1) { object.length }
+      #
+      #   matcher.expected                     # => 1
       #   matcher.matches? { object << "foo" } # => true
       #
       # @yieldreturn [#object_id] The block of code to execute.
       #
       # @return [Boolean] Comparison between the value before and after the
       #   code execution.
-      def matches?(*, **)
+      def matches?
         value_before = @state.call
         yield
         value_after = @state.call
 
-        @expected >= (value_after - value_before)
+        expected >= (value_after - value_before)
       end
 
       # A string containing a human-readable representation of the matcher.
       def inspect
-        "#{self.class}(#{@expected.inspect})"
+        "#{self.class}(#{expected.inspect})"
       end
 
       # Returns a string representing the matcher.
       def to_s
-        "change by at most #{@expected.inspect}"
+        "change by at most #{expected.inspect}"
       end
     end
   end

data/lib/matchi/change/from.rb

@@ -30,8 +30,8 @@ module Matchi
       #
       #   object = "foo"
       #
-      #   change = Matchi::Change::From.new("foo") { object.to_s }
-      #   change.to("FOO")
+      #   change_from_wrapper = Matchi::Change::From.new("foo") { object.to_s }
+      #   change_from_wrapper.to("FOO")
       #
       # @param expected_new_value [#object_id] The new value to expect.
       #

data/lib/matchi/change/from/to.rb

@@ -5,6 +5,9 @@ module Matchi
     class From
       # *Change from to* matcher.
       class To
+        # @return [#object_id] An expected new value.
+        attr_reader :expected
+
         # Initialize the matcher with two objects and a block.
         #
         # @example
@@ -33,30 +36,32 @@ module Matchi
         #   object = "foo"
         #
         #   matcher = Matchi::Change::From::To.new("foo", "FOO") { object.to_s }
+        #
+        #   matcher.expected                    # => "FOO"
         #   matcher.matches? { object.upcase! } # => true
         #
         # @yieldreturn [#object_id] The block of code to execute.
         #
         # @return [Boolean] Comparison between the value before and after the
         #   code execution.
-        def matches?(*, **)
+        def matches?
           value_before = @state.call
           return false unless @expected_init == value_before
 
           yield
           value_after = @state.call
 
-          @expected == value_after
+          expected == value_after
         end
 
         # A string containing a human-readable representation of the matcher.
         def inspect
-          "#{self.class}(#{@expected_init.inspect}, #{@expected.inspect})"
+          "#{self.class}(#{@expected_init.inspect}, #{expected.inspect})"
         end
 
         # Returns a string representing the matcher.
         def to_s
-          "change from #{@expected_init.inspect} to #{@expected.inspect}"
+          "change from #{@expected_init.inspect} to #{expected.inspect}"
         end
       end
     end

data/lib/matchi/change/to.rb

@@ -4,6 +4,9 @@ module Matchi
   class Change
     # *Change to* matcher.
     class To
+      # @return [#object_id] An expected new value.
+      attr_reader :expected
+
       # Initialize the matcher with an object and a block.
       #
       # @example
@@ -13,7 +16,7 @@ module Matchi
       #
       #   Matchi::Change::To.new("FOO") { object.to_s }
       #
-      # @param expected [#object_id]  An expected result value.
+      # @param expected [#object_id]  An expected new value.
       # @param state    [Proc]        A block of code to execute to get the
       #   state of the object.
       def initialize(expected, &state)
@@ -30,27 +33,29 @@ module Matchi
       #   object = "foo"
       #
       #   matcher = Matchi::Change::To.new("FOO") { object.to_s }
+      #
+      #   matcher.expected                    # => "FOO"
       #   matcher.matches? { object.upcase! } # => true
       #
       # @yieldreturn [#object_id] The block of code to execute.
       #
       # @return [Boolean] Comparison between the value before and after the
       #   code execution.
-      def matches?(*, **)
+      def matches?
         yield
         value_after = @state.call
 
-        @expected == value_after
+        expected == value_after
       end
 
       # A string containing a human-readable representation of the matcher.
       def inspect
-        "#{self.class}(#{@expected.inspect})"
+        "#{self.class}(#{expected.inspect})"
       end
 
       # Returns a string representing the matcher.
       def to_s
-        "change to #{@expected.inspect}"
+        "change to #{expected.inspect}"
       end
     end
   end

data/lib/matchi/eq.rb

@@ -3,6 +3,9 @@
 module Matchi
   # *Equivalence* matcher.
   class Eq
+    # @return [#eql?] An expected equivalent object.
+    attr_reader :expected
+
     # Initialize the matcher with an object.
     #
     # @example
@@ -21,24 +24,26 @@ module Matchi
     #   require "matchi/eq"
     #
     #   matcher = Matchi::Eq.new("foo")
+    #
+    #   matcher.expected           # => "foo"
     #   matcher.matches? { "foo" } # => true
     #
     # @yieldreturn [#object_id] The actual value to compare to the expected
     #   one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?(*, **)
-      @expected.eql?(yield)
+    def matches?
+      expected.eql?(yield)
     end
 
     # A string containing a human-readable representation of the matcher.
     def inspect
-      "#{self.class}(#{@expected.inspect})"
+      "#{self.class}(#{expected.inspect})"
     end
 
     # Returns a string representing the matcher.
     def to_s
-      "eq #{@expected.inspect}"
+      "eq #{expected.inspect}"
     end
   end
 end

data/lib/matchi/match.rb

@@ -3,6 +3,9 @@
 module Matchi
   # *Regular expressions* matcher.
   class Match
+    # @return [#match] A regular expression.
+    attr_reader :expected
+
     # Initialize the matcher with an instance of Regexp.
     #
     # @example
@@ -21,24 +24,26 @@ module Matchi
     #   require "matchi/match"
     #
     #   matcher = Matchi::Match.new(/^foo$/)
+    #
+    #   matcher.expected           # => /^foo$/
     #   matcher.matches? { "foo" } # => true
     #
     # @yieldreturn [#object_id] The actual value to compare to the expected
     #   one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?(*, **)
-      @expected.match?(yield)
+    def matches?
+      expected.match?(yield)
     end
 
     # A string containing a human-readable representation of the matcher.
     def inspect
-      "#{self.class}(#{@expected.inspect})"
+      "#{self.class}(#{expected.inspect})"
     end
 
     # Returns a string representing the matcher.
     def to_s
-      "match #{@expected.inspect}"
+      "match #{expected.inspect}"
     end
   end
 end

data/lib/matchi/predicate.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Matchi
+  # *Predicate* matcher.
+  class Predicate
+    # Initialize the matcher with a name and arguments.
+    #
+    # @example
+    #   require "matchi/predicate"
+    #
+    #   Matchi::Predicate.new(:be_empty)
+    #
+    # @param name   [#to_s] A matcher name.
+    # @param args   [Array] A list of parameters.
+    # @param kwargs [Hash]  A list of keyword parameters.
+    # @param block  [Proc]  A block of code.
+    def initialize(name, *args, **kwargs, &block)
+      @name = String(name)
+
+      raise ::ArgumentError unless valid_name?
+
+      @args   = args
+      @kwargs = kwargs
+      @block  = block
+    end
+
+    # @return [Array] The method name with any arguments to send to the subject.
+    def expected
+      [method_name, @args, @kwargs, @block]
+    end
+
+    # Boolean comparison between the actual value and the expected value.
+    #
+    # @example
+    #   require "matchi/predicate"
+    #
+    #   matcher = Matchi::Predicate.new(:be_empty)
+    #
+    #   matcher.expected        # => [:empty?, [], {}, nil]
+    #   matcher.matches? { [] } # => true
+    #
+    # @example
+    #   require "matchi/predicate"
+    #
+    #   matcher = Matchi::Predicate.new(:have_key, :foo)
+    #
+    #   matcher.expected                 # => [:has_key?, [:foo], {}, nil]
+    #   matcher.matches? { { foo: 42 } } # => true
+    #
+    # @yieldreturn [#object_id] The actual value to receive the method request.
+    #
+    # @return [Boolean] A boolean returned by the actual value being tested.
+    def matches?
+      value = yield.send(method_name, *@args, **@kwargs, &@block)
+      return value if [false, true].include?(value)
+
+      raise ::TypeError, "Boolean expected, but #{value.class} instance returned."
+    end
+
+    # A string containing a human-readable representation of the matcher.
+    def inspect
+      "#{self.class}(#{@name}, *#{@args.inspect}, **#{@kwargs.inspect}, &#{@block.inspect})"
+    end
+
+    # Returns a string representing the matcher.
+    def to_s
+      (
+        "#{@name.tr('_', ' ')} " + [
+          @args.map(&:inspect).join(", "),
+          @kwargs.map { |k, v| "#{k}: #{v.inspect}" }.join(", "),
+          (@block.nil? ? "" : "&block")
+        ].reject { |i| i.eql?("") }.join(", ")
+      ).strip
+    end
+
+    private
+
+    # The name of the method to send to the object.
+    def method_name
+      if @name.start_with?("be_")
+        :"#{@name.gsub("be_", "")}?"
+      else
+        :"#{@name.gsub("have_", "has_")}?"
+      end
+    end
+
+    # Verify the matcher name structure.
+    def valid_name?
+      return false if @name.end_with?("?", "!")
+
+      @name.start_with?("be_", "have_")
+    end
+  end
+end

data/lib/matchi/raise_exception.rb

@@ -3,6 +3,9 @@
 module Matchi
   # *Expecting errors* matcher.
   class RaiseException
+    # @return [String] The expected exception name.
+    attr_reader :expected
+
     # Initialize the matcher with a descendant of class Exception.
     #
     # @example
@@ -10,9 +13,9 @@ module Matchi
     #
     #   Matchi::RaiseException.new(NameError)
     #
-    # @param expected [Exception] The class of the expected exception.
+    # @param expected [Exception, #to_s] The expected exception name.
     def initialize(expected)
-      @expected = expected
+      @expected = String(expected)
     end
 
     # Boolean comparison between the actual value and the expected value.
@@ -21,15 +24,17 @@ module Matchi
     #   require "matchi/raise_exception"
     #
     #   matcher = Matchi::RaiseException.new(NameError)
+    #
+    #   matcher.expected          # => "NameError"
     #   matcher.matches? { Boom } # => true
     #
     # @yieldreturn [#object_id] The actual value to compare to the expected
     #   one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?(*, **)
+    def matches?
       yield
-    rescue @expected => _e
+    rescue self.class.const_get(expected) => _e
       true
     else
       false
@@ -37,12 +42,12 @@ module Matchi
 
     # A string containing a human-readable representation of the matcher.
     def inspect
-      "#{self.class}(#{@expected.inspect})"
+      "#{self.class}(#{expected})"
     end
 
     # Returns a string representing the matcher.
     def to_s
-      "raise exception #{@expected.inspect}"
+      "raise exception #{expected}"
     end
   end
 end

data/lib/matchi/satisfy.rb

@@ -3,6 +3,9 @@
 module Matchi
   # *Satisfy* matcher.
   class Satisfy
+    # @return [Proc] A block of code.
+    attr_reader :expected
+
     # Initialize the matcher with a block.
     #
     # @example
@@ -21,14 +24,16 @@ module Matchi
     #   require "matchi/satisfy"
     #
     #   matcher = Matchi::Satisfy.new { |value| value == 42 }
+    #
+    #   matcher.expected        # => #<Proc:0x00007fbaafc65540>
     #   matcher.matches? { 42 } # => true
     #
     # @yieldreturn [#object_id] The actual value to compare to the expected
     #   one.
     #
     # @return [Boolean] Comparison between actual and expected values.
-    def matches?(*, **)
-      @expected.call(yield)
+    def matches?
+      expected.call(yield)
     end
 
     # A string containing a human-readable representation of the matcher.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: matchi
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.3.0
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-07-22 00:00:00.000000000 Z
+date: 2021-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -133,6 +133,8 @@ files:
 - lib/matchi.rb
 - lib/matchi/be.rb
 - lib/matchi/be_an_instance_of.rb
+- lib/matchi/be_within.rb
+- lib/matchi/be_within/of.rb
 - lib/matchi/change.rb
 - lib/matchi/change/by.rb
 - lib/matchi/change/by_at_least.rb
@@ -142,6 +144,7 @@ files:
 - lib/matchi/change/to.rb
 - lib/matchi/eq.rb
 - lib/matchi/match.rb
+- lib/matchi/predicate.rb
 - lib/matchi/raise_exception.rb
 - lib/matchi/satisfy.rb
 homepage: https://github.com/fixrb/matchi