matchi 4.1.1 → 5.0.0

data/lib/matchi/be_an_instance_of.rb

@@ -1,119 +1,42 @@
 # frozen_string_literal: true
 
+require_relative "constant"
+
 module Matchi
-  # *Type/class* matcher with enhanced class checking.
-  #
-  # This matcher aims to provide a more reliable way to check if an object is an exact
-  # instance of a specific class (not a subclass). While not foolproof, it uses a more
-  # robust method to get the actual class of an object that helps resist common
-  # attempts at type checking manipulation.
-  #
-  # @example Basic usage
-  #   require "matchi/be_an_instance_of"
-  #
-  #   matcher = Matchi::BeAnInstanceOf.new(String)
-  #   matcher.match? { "foo" }  # => true
-  #   matcher.match? { :foo }   # => false
-  #
-  # @example Enhanced class checking in practice
-  #   # Consider a class that attempts to masquerade as String by overriding
-  #   # common type checking methods:
-  #   class MaliciousString
-  #     def class
-  #       ::String
-  #     end
-  #
-  #     def instance_of?(klass)
-  #       self.class == klass
-  #     end
-  #
-  #     def is_a?(klass)
-  #       "".is_a?(klass)  # Delegates to a real String
-  #     end
+  # Exact type matcher: passes when the class of the actual value is the
+  # expected class itself, not a descendant.
   #
-  #     def kind_of?(klass)
-  #       is_a?(klass)     # Maintains Ruby's kind_of? alias for is_a?
-  #     end
-  #   end
+  # The class of the actual value is read with `Kernel#class` bound to it, so
+  # an object that redefines `class` cannot lie, and a `BasicObject` is
+  # handled. The expected class can be given directly, or by name; see
+  # {Matchi::Constant}.
   #
-  #   obj = MaliciousString.new
-  #   obj.class                                             # => String
-  #   obj.is_a?(String)                                     # => true
-  #   obj.kind_of?(String)                                  # => true
-  #   obj.instance_of?(String)                              # => true
-  #
-  #   # Using our enhanced checking approach:
-  #   matcher = Matchi::BeAnInstanceOf.new(String)
-  #   matcher.match? { obj }                                # => false
+  # @example
+  #   Matchi::BeAnInstanceOf.new(Integer).match? { 42 }   # => true
+  #   Matchi::BeAnInstanceOf.new(:Numeric).match? { 42 }  # => false
   class BeAnInstanceOf
-    # Initialize the matcher with (the name of) a class or module.
-    #
-    # @example
-    #   require "matchi/be_an_instance_of"
-    #
-    #   Matchi::BeAnInstanceOf.new(String)
-    #   Matchi::BeAnInstanceOf.new("String")
-    #   Matchi::BeAnInstanceOf.new(:String)
-    #
-    # @param expected [Class, #to_s] The expected class name
-    # @raise [ArgumentError] if the class name doesn't start with an uppercase letter
+    # @param expected [Class, String, Symbol] the expected class, or its name
+    # @raise [ArgumentError] when expected is neither a Class nor a constant name
     def initialize(expected)
-      @expected = String(expected)
-      return if /\A[A-Z]/.match?(@expected)
-
-      raise ::ArgumentError,
-            "expected must start with an uppercase letter (got: #{@expected})"
+      @expected = Constant.normalize(expected, ::Class)
     end
 
-    # Securely checks if the yielded object is an instance of the expected class.
-    #
-    # This method uses a specific Ruby reflection technique to get the true class of
-    # an object, bypassing potential method overrides:
-    #
-    # 1. ::Object.instance_method(:class) retrieves the original, unoverridden 'class'
-    #    method from the Object class
-    # 2. .bind_call(obj) binds this original method to our object and calls it,
-    #    ensuring we get the real class regardless of method overrides
-    #
-    # This approach is more reliable than obj.class because it uses Ruby's method
-    # binding mechanism to call the original implementation directly. While not
-    # completely foolproof, it provides better protection against type check spoofing
-    # than using regular method calls which can be overridden.
-    #
-    # @example Basic class check
-    #   matcher = Matchi::BeAnInstanceOf.new(String)
-    #   matcher.match? { "test" }        # => true
-    #   matcher.match? { StringIO.new }  # => false
-    #
-    # @see https://ruby-doc.org/core/Method.html#method-i-bind_call
-    # @see https://ruby-doc.org/core/UnboundMethod.html
-    #
-    # @yieldreturn [Object] the actual value to check
-    # @return [Boolean] true if the object's actual class is exactly the expected class
-    # @raise [ArgumentError] if no block is provided
+    # @yieldreturn [Object] the actual value
+    # @return [Boolean]
+    # @raise [ArgumentError] when no block is given
+    # @raise [NameError] when the name is not defined
+    # @raise [TypeError] when the name does not resolve to a Class
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
-      actual_class = ::Object.instance_method(:class).bind_call(yield)
-      expected_class == actual_class
-    end
+      actual_class = ::Kernel.instance_method(:class).bind_call(yield)
 
-    # Returns a string representing the matcher.
-    #
-    # @return [String] a human-readable description of the matcher
-    def to_s
-      "be an instance of #{@expected}"
+      Constant.resolve(@expected, ::Class).equal?(actual_class)
     end
 
-    private
-
-    # Resolves the expected class name to an actual Class object.
-    # This method handles both string and symbol class names through constant resolution.
-    #
-    # @return [Class] the resolved class
-    # @raise [NameError] if the class doesn't exist
-    def expected_class
-      ::Object.const_get(@expected)
+    # @return [String]
+    def to_s
+      "be an instance of #{Constant.label(@expected)}"
     end
   end
 end

data/lib/matchi/be_within/of.rb

@@ -1,50 +1,56 @@
 # frozen_string_literal: true
 
+require_relative "../number"
+
 module Matchi
   class BeWithin
-    # *BeWithin of* matcher.
+    # Numeric proximity matcher: passes when the actual value is a core number
+    # whose distance to the expected value is at most delta.
+    #
+    # The actual value must be an `Integer`, a `Float`, a `Rational` or a
+    # `BigDecimal` (its class is read with `Kernel#class` bound to it). Any
+    # other value fails, including a user-defined `Numeric` subclass: such an
+    # object would control the subtraction through `coerce`.
+    #
+    # @example
+    #   Matchi::BeWithin::Of.new(1, 42).match? { 41 }   # => true
+    #   Matchi::BeWithin::Of.new(1, 42).match? { "42" } # => false
     class Of
-      # 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.
+      # @param delta [Numeric] the tolerance: a finite, real, non-negative number
+      # @param expected [Numeric] the center of the interval: a finite, real number
+      # @raise [ArgumentError] when an argument is not such a number
       def initialize(delta, expected)
-        raise ::ArgumentError, "delta must be a Numeric" unless delta.is_a?(::Numeric)
-        raise ::ArgumentError, "expected must be a Numeric" unless expected.is_a?(::Numeric)
-        raise ::ArgumentError, "delta must be non-negative" if delta.negative?
-
-        @delta    = delta
-        @expected = expected
+        @delta = Number.non_negative!(delta, "delta")
+        @expected = Number.finite_real!(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.match? { 42 } # => true
-      #
-      # @yieldreturn [Numeric] The block of code to execute.
-      #
-      # @return [Boolean] Comparison between the actual and the expected values.
+      # @yieldreturn [Object] the actual value
+      # @return [Boolean]
+      # @raise [ArgumentError] when no block is given
       def match?
         raise ::ArgumentError, "a block must be provided" unless block_given?
 
-        (@expected - yield).abs <= @delta
+        actual = yield
+        return false unless core_number?(actual)
+
+        (@expected - actual).abs <= @delta
       end
 
-      # Returns a string representing the matcher.
-      #
-      # @return [String] a human-readable description of the matcher
+      # @return [String]
       def to_s
-        "be within #{@delta} of #{@expected}"
+        "be within #{@delta.inspect} of #{@expected.inspect}"
+      end
+
+      private
+
+      CORE = [::Integer, ::Float, ::Rational].freeze
+      private_constant :CORE
+
+      def core_number?(actual)
+        klass = ::Kernel.instance_method(:class).bind_call(actual)
+        return true if CORE.include?(klass)
+
+        defined?(::BigDecimal) ? klass.equal?(::BigDecimal) : false
       end
     end
   end

data/lib/matchi/be_within.rb

@@ -1,38 +1,32 @@
 # frozen_string_literal: true
 
-require_relative File.join("be_within", "of")
+require_relative "be_within/of"
+require_relative "number"
 
 module Matchi
-  # Wraps the target of a be_within matcher.
+  # Builder for the `be within DELTA of EXPECTED` matcher. It is not a matcher
+  # itself: it does not respond to `match?`, so a framework that checks the
+  # matcher interface rejects a forgotten `of`.
+  #
+  # @example
+  #   Matchi::BeWithin.new(0.5).of(3).match? { 3.2 } # => true
   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.
+    # @param delta [Numeric] the tolerance: a finite, real, non-negative number
+    # @raise [ArgumentError] when delta is not such a number
     def initialize(delta)
-      raise ::ArgumentError, "delta must be a Numeric" unless delta.is_a?(::Numeric)
-      raise ::ArgumentError, "delta must be non-negative" if delta.negative?
-
-      @delta = delta
+      @delta = Number.non_negative!(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 [#match?] A *be_within of* matcher.
+    # @param expected [Numeric] the center of the interval, a finite real number
+    # @return [Matchi::BeWithin::Of] the matcher
+    # @raise [ArgumentError] when expected is not a finite real Numeric
     def of(expected)
       Of.new(@delta, expected)
     end
+
+    # @return [String]
+    def to_s
+      "be within #{@delta.inspect}"
+    end
   end
 end

data/lib/matchi/change/delta.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../number"
+
+module Matchi
+  class Change
+    # Passes when the difference between the observed value after and before
+    # the block, `after - before`, is exactly the expected delta (`:by`), at
+    # least it (`:by_at_least`) or at most it (`:by_at_most`). The expected
+    # delta receives the comparison; the difference is computed by the
+    # observed values, so this matcher depends on their honesty.
+    #
+    # @example
+    #   list = []
+    #   Matchi::Change::Delta.new(:by, 2) { list.length }.match? { list.push(1, 2) } # => true
+    class Delta
+      # For each kind: the comparison the delta receives, and its description.
+      KINDS = {
+        by:          [:==, "by"],
+        by_at_least: [:<=, "by at least"],
+        by_at_most:  [:>=, "by at most"]
+      }.freeze
+
+      # @param kind [Symbol] `:by`, `:by_at_least` or `:by_at_most`
+      # @param delta [Numeric] a finite real number, non-negative unless kind is `:by`
+      # @yieldreturn [Object] the observed value
+      # @raise [ArgumentError] when the kind is unknown, delta is not such a number, or no block is given
+      def initialize(kind, delta, &state)
+        raise ::ArgumentError, "unknown kind #{kind.inspect}" unless KINDS.key?(kind)
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
+        @operator, @label = KINDS.fetch(kind)
+        @delta = kind == :by ? Number.finite_real!(delta, "delta") : Number.non_negative!(delta, "delta")
+        @state = state
+      end
+
+      # @yieldreturn [Object] ignored, the block is evaluated for its effect
+      # @return [Boolean]
+      # @raise [ArgumentError] when no block is given
+      def match?
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
+        value_before = @state.call
+        yield
+        value_after = @state.call
+
+        @delta.public_send(@operator, value_after - value_before) ? true : false
+      end
+
+      # @return [String]
+      def to_s
+        "change #{@label} #{@delta.inspect}"
+      end
+    end
+  end
+end

data/lib/matchi/change/from.rb

@@ -1,45 +1,35 @@
 # frozen_string_literal: true
 
-require_relative File.join("from", "to")
+require_relative "from_to"
 
 module Matchi
   class Change
-    # *Change from to* wrapper.
+    # Builder for the `change from OLD to NEW` matcher. It is not a matcher
+    # itself: it does not respond to `match?`, so a forgotten `to` is rejected
+    # by any framework that checks the matcher interface.
+    #
+    # @example
+    #   Matchi::Change.new(s, :to_s).from("a").to("b")
     class From
-      # Initialize the wrapper with an object and a block.
-      #
-      # @example
-      #   require "matchi/change/from"
-      #
-      #   object = "foo"
-      #
-      #   Matchi::Change::From.new("foo") { object.to_s }
-      #
-      # @param expected [#object_id]  An expected initial value.
-      # @param state    [Proc]        A block of code to execute to get the
-      #   state of the object.
-      def initialize(expected, &state)
+      # @param old_value [#eql?] the expected value before the block
+      # @yieldreturn [Object] the observed value
+      # @raise [ArgumentError] when no block is given
+      def initialize(old_value, &state)
         raise ::ArgumentError, "a block must be provided" unless block_given?
 
-        @expected = expected
-        @state    = state
+        @old_value = old_value
+        @state = state
       end
 
-      # Specifies the new value to expect.
-      #
-      # @example
-      #   require "matchi/change/from"
-      #
-      #   object = "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.
-      #
-      # @return [#match?] A *change from to* matcher.
-      def to(expected_new_value)
-        To.new(@expected, expected_new_value, &@state)
+      # @param new_value [#eql?] the expected value after the block
+      # @return [Matchi::Change::FromTo]
+      def to(new_value)
+        FromTo.new(@old_value, new_value, &@state)
+      end
+
+      # @return [String]
+      def to_s
+        "change from #{@old_value.inspect}"
       end
     end
   end

data/lib/matchi/change/from_to.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../eq"
+
+module Matchi
+  class Change
+    # Passes when the observed value is the old value before the block and
+    # the new value after it, both compared like {Matchi::Eq}. The block is
+    # always evaluated; a wrong initial value is a failure of the
+    # expectation, like a wrong final value.
+    #
+    # @example
+    #   s = +"a"
+    #   Matchi::Change.new(s, :to_s).from("a").to("b").match? { s.replace("b") } # => true
+    class FromTo
+      # @param old_value [#eql?] the expected value before the block
+      # @param new_value [#eql?] the expected value after the block
+      # @yieldreturn [Object] the observed value
+      # @raise [ArgumentError] when no block is given
+      def initialize(old_value, new_value, &state)
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
+        @old_value = old_value
+        @new_value = new_value
+        @state = state
+      end
+
+      # @yieldreturn [Object] ignored, the block is evaluated for its effect
+      # @return [Boolean]
+      # @raise [ArgumentError] when no block is given
+      def match?
+        raise ::ArgumentError, "a block must be provided" unless block_given?
+
+        initial = Eq.eql?(@old_value, @state.call)
+        yield
+
+        initial && Eq.eql?(@new_value, @state.call)
+      end
+
+      # @return [String]
+      def to_s
+        "change from #{@old_value.inspect} to #{@new_value.inspect}"
+      end
+    end
+  end
+end

data/lib/matchi/change/to.rb

@@ -1,55 +1,40 @@
 # frozen_string_literal: true
 
+require_relative "../eq"
+
 module Matchi
   class Change
-    # *Change to* matcher.
+    # Passes when the observed value is not the expected value before the
+    # block and is the expected value after it: the value must change to it.
+    # The block is always evaluated.
+    #
+    # @example
+    #   s = +"a"
+    #   Matchi::Change.new(s, :to_s).to("b").match? { s.replace("b") } # => true
     class To
-      # Initialize the matcher with an object and a block.
-      #
-      # @example
-      #   require "matchi/change/to"
-      #
-      #   object = "foo"
-      #
-      #   Matchi::Change::To.new("FOO") { object.to_s }
-      #
-      # @param expected [#object_id]  An expected new value.
-      # @param state    [Proc]        A block of code to execute to get the
-      #   state of the object.
+      # @param expected [#eql?] the expected value after the block
+      # @yieldreturn [Object] the observed value
+      # @raise [ArgumentError] when no block is given
       def initialize(expected, &state)
         raise ::ArgumentError, "a block must be provided" unless block_given?
 
         @expected = expected
-        @state    = state
+        @state = state
       end
 
-      # Boolean comparison on the expected change by comparing the value
-      # before and after the code execution.
-      #
-      # @example
-      #   require "matchi/change/to"
-      #
-      #   object = "foo"
-      #
-      #   matcher = Matchi::Change::To.new("FOO") { object.to_s }
-      #   matcher.match? { object.upcase! } # => true
-      #
-      # @yieldreturn [#object_id] The block of code to execute.
-      #
-      # @return [Boolean] Comparison between the value before and after the
-      #   code execution.
+      # @yieldreturn [Object] ignored, the block is evaluated for its effect
+      # @return [Boolean]
+      # @raise [ArgumentError] when no block is given
       def match?
         raise ::ArgumentError, "a block must be provided" unless block_given?
 
+        already = Eq.eql?(@expected, @state.call)
         yield
-        value_after = @state.call
 
-        @expected == value_after
+        !already && Eq.eql?(@expected, @state.call)
       end
 
-      # Returns a string representing the matcher.
-      #
-      # @return [String] a human-readable description of the matcher
+      # @return [String]
       def to_s
         "change to #{@expected.inspect}"
       end