matchi 4.2.0 → 5.0.0

data/lib/matchi/be_an_instance_of.rb

@@ -1,131 +1,42 @@
 # frozen_string_literal: true
 
+require_relative "constant"
+
 module Matchi
-  # Type matcher that checks if an object is an exact instance of a specific class.
-  #
-  # This matcher provides a secure way to verify an object's exact type, ensuring it
-  # matches a specific class without including subclasses. It uses Ruby's method binding
-  # mechanism to bypass potential method overrides, providing better protection against
-  # type check spoofing than standard instance_of? checks.
-  #
-  # @example Basic usage
-  #   matcher = Matchi::BeAnInstanceOf.new(String)
-  #   matcher.match? { "test" }      # => true
-  #   matcher.match? { :test }       # => false
-  #
-  # @example Inheritance behavior
-  #   class Animal; end
-  #   class Dog < Animal; end
-  #
-  #   matcher = Matchi::BeAnInstanceOf.new(Animal)
-  #   matcher.match? { Animal.new }  # => true
-  #   matcher.match? { Dog.new }     # => false  # Subclass doesn't match
-  #
-  # @example Secure type checking
-  #   # Consider a class that attempts to masquerade as String:
-  #   class MaliciousString
-  #     def class; String; end
-  #     def instance_of?(klass); true; end
-  #   end
-  #
-  #   obj = MaliciousString.new
-  #   obj.instance_of?(String)                           # => true (spoofed)
-  #
-  #   matcher = Matchi::BeAnInstanceOf.new(String)
-  #   matcher.match? { obj }                             # => false (secure)
+  # Exact type matcher: passes when the class of the actual value is the
+  # expected class itself, not a descendant.
   #
-  # @example Different ways to specify the class
-  #   # Using class directly
-  #   Matchi::BeAnInstanceOf.new(String)
+  # 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}.
   #
-  #   # Using class name as string
-  #   Matchi::BeAnInstanceOf.new("String")
-  #
-  #   # Using class name as symbol
-  #   Matchi::BeAnInstanceOf.new(:String)
-  #
-  #   # Using namespaced class
-  #   Matchi::BeAnInstanceOf.new("MyModule::MyClass")
-  #
-  # @see Matchi::BeAKindOf
-  # @see https://ruby-doc.org/core/Object.html#method-i-instance_of-3F
-  # @see https://ruby-doc.org/core/Module.html#method-i-bind_call
+  # @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.
-    #
-    # @api public
-    #
-    # @param expected [Class, #to_s] The expected class or its name
-    #   Can be provided as a Class object, String, or Symbol
-    #
-    # @raise [ArgumentError] if the class name doesn't start with an uppercase letter
-    #
-    # @return [BeAnInstanceOf] a new instance of the matcher
-    #
-    # @example
-    #   BeAnInstanceOf.new(String)          # Using class
-    #   BeAnInstanceOf.new("String")        # Using string
-    #   BeAnInstanceOf.new(:String)         # Using symbol
+    # @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 Ruby's method binding mechanism to get the true class of an object,
-    # bypassing potential method overrides. While not completely foolproof, it provides
-    # better protection against type check spoofing than using regular method calls which
-    # can be overridden.
-    #
-    # @api public
-    #
-    # @yield [] Block that returns the object to check
-    # @yieldreturn [Object] The object to verify the type of
-    #
-    # @return [Boolean] true if the object's actual class is exactly the expected class
-    #
-    # @raise [ArgumentError] if no block is provided
-    # @raise [NameError] if the expected class cannot be found
-    #
-    # @example Simple type check
-    #   matcher = BeAnInstanceOf.new(String)
-    #   matcher.match? { "test" }        # => true
-    #   matcher.match? { StringIO.new }  # => false
+    # @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 human-readable description of the matcher.
-    #
-    # @api public
-    #
-    # @return [String] A string describing what this matcher verifies
-    #
-    # @example
-    #   BeAnInstanceOf.new(String).to_s # => "be an instance of String"
-    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.
-    #
-    # @api private
-    #
-    # @return [Class] The resolved class object
-    # @raise [NameError] If the class name cannot be resolved to an actual class
-    #
-    # @note This method handles both string and symbol class names through constant resolution
-    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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "../number"
+
+module Matchi
+  class BeWithin
+    # 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
+      # @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)
+        @delta = Number.non_negative!(delta, "delta")
+        @expected = Number.finite_real!(expected, "expected")
+      end
+
+      # @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?
+
+        actual = yield
+        return false unless core_number?(actual)
+
+        (@expected - actual).abs <= @delta
+      end
+
+      # @return [String]
+      def to_s
+        "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
+end

data/lib/matchi/be_within.rb

@@ -1,149 +1,32 @@
 # frozen_string_literal: true
 
+require_relative "be_within/of"
+require_relative "number"
+
 module Matchi
-  # Delta comparison matcher that checks if a numeric value is within a specified range.
-  #
-  # This matcher verifies that a numeric value falls within a certain distance (delta)
-  # of an expected value. It's particularly useful for floating-point comparisons or
-  # when checking if a value is approximately equal to another within a given tolerance.
-  #
-  # @example Basic usage with integers
-  #   matcher = Matchi::BeWithin.new(1).of(10)
-  #   matcher.match? { 9 }    # => true
-  #   matcher.match? { 10 }   # => true
-  #   matcher.match? { 11 }   # => true
-  #   matcher.match? { 12 }   # => false
+  # 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 Floating point comparisons
-  #   matcher = Matchi::BeWithin.new(0.1).of(3.14)
-  #   matcher.match? { 3.1 }   # => true
-  #   matcher.match? { 3.2 }   # => true
-  #   matcher.match? { 3.0 }   # => false
-  #
-  # @example Working with percentages
-  #   matcher = Matchi::BeWithin.new(5).of(100)  # 5% margin
-  #   matcher.match? { 95 }    # => true
-  #   matcher.match? { 105 }   # => true
-  #   matcher.match? { 110 }   # => false
-  #
-  # @see https://ruby-doc.org/core/Numeric.html#method-i-abs
+  # @example
+  #   Matchi::BeWithin.new(0.5).of(3).match? { 3.2 } # => true
   class BeWithin
-    # Initialize the matcher with a delta value.
-    #
-    # @api public
-    #
-    # @param delta [Numeric] The maximum allowed difference from the expected value
-    #
-    # @raise [ArgumentError] if delta is not a Numeric
-    # @raise [ArgumentError] if delta is negative
-    #
-    # @return [BeWithin] a new instance of the matcher
-    #
-    # @example
-    #   BeWithin.new(0.5)           # Using float
-    #   BeWithin.new(2)             # Using integer
+    # @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
 
-    # Raises NotImplementedError as this is not a complete matcher.
-    #
-    # This class acts as a builder for the actual matcher, which is created
-    # by calling the #of method. Direct use of #match? is not supported.
-    #
-    # @api public
-    #
-    # @raise [NotImplementedError] always, as this method should not be used
-    #
-    # @example
-    #   # Don't do this:
-    #   BeWithin.new(0.5).match? { 42 }  # Raises NotImplementedError
-    #
-    #   # Do this instead:
-    #   BeWithin.new(0.5).of(42).match? { 41.8 }  # Works correctly
-    def match?
-      raise ::NotImplementedError, "BeWithin is not a complete matcher. Use BeWithin#of to create a valid matcher."
-    end
-
-    # Specifies the expected reference value.
-    #
-    # @api public
-    #
-    # @param expected [Numeric] The reference value to compare against
-    #
-    # @raise [ArgumentError] if expected is not a Numeric
-    #
-    # @return [#match?] A matcher that checks if a value is within the specified range
-    #
-    # @example
-    #   be_within_wrapper = BeWithin.new(0.5)
-    #   be_within_wrapper.of(3.14)  # Creates matcher for values in range 2.64..3.64
+    # @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
 
-    # Nested class that performs the actual comparison.
-    #
-    # This class implements the actual matching logic, comparing the provided value
-    # against the expected value using the specified delta.
-    class Of
-      # Initialize the matcher with a delta and an expected value.
-      #
-      # @api private
-      #
-      # @param delta [Numeric] The maximum allowed difference from the expected value
-      # @param expected [Numeric] The reference value to compare against
-      #
-      # @raise [ArgumentError] if delta is not a Numeric
-      # @raise [ArgumentError] if expected is not a Numeric
-      # @raise [ArgumentError] if delta is negative
-      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
-      end
-
-      # Checks if the yielded value is within the accepted range.
-      #
-      # The value is considered within range if its absolute difference from the
-      # expected value is less than or equal to the specified delta.
-      #
-      # @api public
-      #
-      # @yield [] Block that returns the value to check
-      # @yieldreturn [Numeric] The value to verify
-      #
-      # @return [Boolean] true if the value is within the accepted range
-      #
-      # @raise [ArgumentError] if no block is provided
-      #
-      # @example
-      #   matcher = BeWithin.new(0.5).of(3.14)
-      #   matcher.match? { 3.0 }   # => true
-      #   matcher.match? { 4.0 }   # => false
-      def match?
-        raise ::ArgumentError, "a block must be provided" unless block_given?
-
-        (@expected - yield).abs <= @delta
-      end
-
-      # Returns a human-readable description of the matcher.
-      #
-      # @api public
-      #
-      # @return [String] A string describing what this matcher verifies
-      #
-      # @example
-      #   BeWithin.new(0.5).of(3.14).to_s # => "be within 0.5 of 3.14"
-      def to_s
-        "be within #{@delta} of #{@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,75 +1,35 @@
 # frozen_string_literal: true
 
-require_relative File.join("from", "to")
+require_relative "from_to"
 
 module Matchi
   class Change
-    # Initial state wrapper for building a value transition matcher.
+    # 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.
     #
-    # This class acts as a wrapper that captures the expected initial state and
-    # provides methods to build a complete transition matcher. When combined with
-    # the 'to' method, it creates a matcher that verifies both the starting and
-    # ending values of a change operation. This is useful when you need to ensure
-    # not only the final state but also the initial state of a value.
-    #
-    # @example Basic string transformation
-    #   text = "hello"
-    #   Change.new(text, :to_s).from("hello").to("HELLO").match? { text.upcase! }  # => true
-    #
-    # @example Object state transition
-    #   class User
-    #     attr_accessor :status
-    #     def initialize
-    #       @status = "pending"
-    #     end
-    #   end
-    #
-    #   user = User.new
-    #   Change.new(user, :status).from("pending").to("active").match? {
-    #     user.status = "active"
-    #   }  # => true
-    #
-    # @see Matchi::Change::From::To For the complete transition matcher
+    # @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
+
+      # @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
 
-      # Specifies the new value to expect.
-      #
-      # Creates a complete transition matcher that verifies both the initial
-      # and final states of a value. The matcher will succeed only if the
-      # value starts at the expected initial state and changes to the specified
-      # new value after executing the test block.
-      #
-      # @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)
+      # @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