matchi 4.2.0 → 6.0.0

data/lib/matchi/eq.rb

@@ -1,85 +1,44 @@
 # frozen_string_literal: true
 
 module Matchi
-  # Value equivalence matcher that checks if two objects have identical values.
+  # Equivalence matcher: passes when the actual value is of the same class as
+  # the expected value and `eql?` to it.
   #
-  # This matcher verifies value equality using Ruby's Object#eql? method, which
-  # compares the values of objects rather than their identity. This is different
-  # from identity comparison (equal?) which checks if objects are the same instance.
+  # The expected value receives the `eql?` call, so the actual value cannot
+  # lie. The class check comes first because a few core `eql?` methods, such
+  # as `Hash#eql?`, hand the comparison back to an operand of another class;
+  # it costs nothing, since `eql?` never holds across classes for core values.
   #
-  # @example Basic usage with strings
-  #   matcher = Matchi::Eq.new("test")
-  #   matcher.match? { "test" }         # => true
-  #   matcher.match? { "test".dup }     # => true
-  #   matcher.match? { "other" }        # => false
-  #
-  # @example With numbers
-  #   matcher = Matchi::Eq.new(42)
-  #   matcher.match? { 42 }             # => true
-  #   matcher.match? { 42.0 }           # => false  # Different types
-  #   matcher.match? { 43 }             # => false
-  #
-  # @example With collections
-  #   array = [1, 2, 3]
-  #   matcher = Matchi::Eq.new(array)
-  #   matcher.match? { array.dup }      # => true   # Same values
-  #   matcher.match? { array }          # => true   # Same object
-  #   matcher.match? { [1, 2, 3] }      # => true   # Same values
-  #   matcher.match? { [1, 2] }         # => false  # Different values
-  #
-  # @see https://ruby-doc.org/core/Object.html#method-i-eql-3F
-  # @see Matchi::Be
+  # @example
+  #   Matchi::Eq.new("foo").match? { "foo" } # => true
+  #   Matchi::Eq.new(1).match? { 1.0 }       # => false (eql? is strict on type)
   class Eq
-    # Initialize the matcher with a reference value.
-    #
-    # @api public
-    #
-    # @param expected [#eql?] The expected equivalent value
-    #
-    # @return [Eq] a new instance of the matcher
-    #
-    # @example
-    #   Eq.new("test")              # Match strings with same value
-    #   Eq.new([1, 2, 3])           # Match arrays with same elements
+    # @param expected [#eql?] the expected value
     def initialize(expected)
       @expected = expected
     end
 
-    # Checks if the yielded object has a value equivalent to the expected object.
-    #
-    # This method uses Ruby's Object#eql? method, which performs value comparison.
-    # Two objects are considered equivalent if they have the same value, even if
-    # they are different instances.
-    #
-    # @api public
-    #
-    # @yield [] Block that returns the object to check
-    # @yieldreturn [Object] The object to verify equivalence with
-    #
-    # @return [Boolean] true if both objects have equivalent values
-    #
-    # @raise [ArgumentError] if no block is provided
-    #
-    # @example
-    #   matcher = Eq.new([1, 2, 3])
-    #   matcher.match? { [1, 2, 3] }      # => true
-    #   matcher.match? { [1, 2, 3].dup }  # => true
+    # @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.eql?(yield)
+      Eq.eql?(@expected, yield)
     end
 
-    # Returns a human-readable description of the matcher.
-    #
-    # @api public
-    #
-    # @return [String] A string describing what this matcher verifies
-    #
-    # @example
-    #   Eq.new("test").to_s # => 'eq "test"'
+    # @return [String]
     def to_s
       "eq #{@expected.inspect}"
     end
+
+    # @param expected [#eql?] the value that receives the comparison
+    # @param actual [Object] a value from the code under test
+    # @return [Boolean] whether actual is of the class of expected and `eql?` to it
+    def self.eql?(expected, actual)
+      return false unless ::Kernel.instance_method(:class).bind_call(actual).equal?(expected.class)
+
+      expected.eql?(actual) ? true : false
+    end
   end
 end

data/lib/matchi/match.rb

@@ -1,83 +1,48 @@
 # frozen_string_literal: true
 
 module Matchi
-  # Pattern matching matcher that checks if a value matches a regular expression.
+  # Regular expression matcher: passes when the actual value is a String or a
+  # Symbol that the expected Regexp matches. Any other actual value fails, as
+  # does a string with an invalid or incompatible encoding.
   #
-  # This matcher verifies that a value matches a pattern using Ruby's Regexp#match? method.
-  # It's particularly useful for string validation, pattern matching, and text analysis.
-  # The matcher ensures secure pattern matching by requiring the pattern to respond to match?.
+  # Only a `Regexp` is accepted as pattern: with a `String` pattern,
+  # `String#match?` would turn the actual value into the regular expression,
+  # handing the comparison to the code under test. Use {Matchi::Satisfy} for
+  # other predicates.
   #
-  # @example Basic usage
-  #   matcher = Matchi::Match.new(/^test/)
-  #   matcher.match? { "test_string" }     # => true
-  #   matcher.match? { "other_string" }    # => false
-  #
-  # @example Case sensitivity
-  #   matcher = Matchi::Match.new(/^test$/i)
-  #   matcher.match? { "TEST" }            # => true
-  #   matcher.match? { "Test" }            # => true
-  #   matcher.match? { "testing" }         # => false
-  #
-  # @example Multiline patterns
-  #   matcher = Matchi::Match.new(/\A\d+\Z/m)
-  #   matcher.match? { "123" }             # => true
-  #   matcher.match? { "12.3" }            # => false
-  #
-  # @see https://ruby-doc.org/core/Regexp.html#method-i-match-3F
+  # @example
+  #   Matchi::Match.new(/^foo/).match? { "foobar" } # => true
+  #   Matchi::Match.new(/^foo/).match? { 42 }       # => false
   class Match
-    # Initialize the matcher with a pattern.
-    #
-    # @api public
-    #
-    # @param expected [#match?] A pattern that responds to match?
-    #
-    # @raise [ArgumentError] if the pattern doesn't respond to match?
-    #
-    # @return [Match] a new instance of the matcher
-    #
-    # @example
-    #   Match.new(/\d+/)           # Match digits
-    #   Match.new(/^test$/i)       # Case-insensitive match
-    #   Match.new(/\A\w+\Z/)       # Full string word characters
+    # @param expected [Regexp] the pattern
+    # @raise [ArgumentError] when expected is not a Regexp
     def initialize(expected)
-      raise ::ArgumentError, "expected must respond to match?" unless expected.respond_to?(:match?)
+      raise ::ArgumentError, "expected must be a Regexp (got: #{expected.inspect})" unless ::Regexp === expected
 
       @expected = expected
     end
 
-    # Checks if the yielded value matches the expected pattern.
-    #
-    # This method uses the pattern's match? method to perform the comparison.
-    # The match is performed on the entire string unless the pattern specifically
-    # allows partial matches.
-    #
-    # @api public
-    #
-    # @yield [] Block that returns the value to check
-    # @yieldreturn [#to_s] The value to match against the pattern
-    #
-    # @return [Boolean] true if the value matches the pattern
-    #
-    # @raise [ArgumentError] if no block is provided
-    #
-    # @example
-    #   matcher = Match.new(/^\d{3}-\d{2}-\d{4}$/)
-    #   matcher.match? { "123-45-6789" }   # => true
-    #   matcher.match? { "123456789" }     # => false
+    # @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.match?(yield)
+      actual = yield
+      return false unless ::String === actual || ::Symbol === actual
+
+      # A plain copy: a subclass of String has no say in the comparison.
+      string = ::String.new(::Symbol === actual ? actual.name : actual)
+      return false unless string.valid_encoding?
+
+      begin
+        @expected.match?(string)
+      rescue ::Encoding::CompatibilityError
+        false
+      end
     end
 
-    # Returns a human-readable description of the matcher.
-    #
-    # @api public
-    #
-    # @return [String] A string describing what this matcher verifies
-    #
-    # @example
-    #   Match.new(/^test/).to_s # => "match /^test/"
+    # @return [String]
     def to_s
       "match #{@expected.inspect}"
     end

data/lib/matchi/number.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Matchi
+  # Validation of the numbers given to matchers: deltas and expected values
+  # must be finite and real, so that a `NaN`, an infinity or a `Complex`
+  # cannot build a matcher that never, or always, passes.
+  #
+  # @api private
+  module Number
+    # @param value [Object]
+    # @return [Boolean] whether value is a finite real Numeric
+    def self.finite_real?(value)
+      ::Numeric === value && value.real? && value.finite?
+    end
+
+    # @param value [Object]
+    # @param role [String] the argument name, for the error message
+    # @return [Numeric] value
+    # @raise [ArgumentError] when value is not a finite real Numeric
+    def self.finite_real!(value, role)
+      raise ::ArgumentError, "#{role} must be a finite real Numeric (got: #{value.inspect})" unless finite_real?(value)
+
+      value
+    end
+
+    # @param value [Object]
+    # @param role [String] the argument name, for the error message
+    # @return [Numeric] value
+    # @raise [ArgumentError] when value is not a finite real non-negative Numeric
+    def self.non_negative!(value, role)
+      finite_real!(value, role)
+      raise ::ArgumentError, "#{role} must be non-negative (got: #{value.inspect})" if value.negative?
+
+      value
+    end
+  end
+end

data/lib/matchi/predicate.rb

@@ -1,172 +1,73 @@
 # frozen_string_literal: true
 
+require_relative "constant"
+
 module Matchi
-  # Predicate matcher that checks if an object responds to a predicate method with a truthy value.
-  #
-  # This matcher converts a predicate name (starting with 'be_' or 'have_') into a method call
-  # ending with '?' and verifies that calling this method returns a boolean value. It's useful
-  # for testing state-checking methods and collection properties. The matcher supports two types
-  # of predicate formats: 'be_*' which converts to '*?' and 'have_*' which converts to 'has_*?'.
-  #
-  # @example Basic empty check
-  #   matcher = Matchi::Predicate.new(:be_empty)
-  #   matcher.match? { [] }        # => true
-  #   matcher.match? { [1, 2] }    # => false
-  #
-  # @example Object property check with arguments
-  #   matcher = Matchi::Predicate.new(:have_key, :name)
-  #   matcher.match? { { name: "Alice" } }  # => true
-  #   matcher.match? { { age: 30 } }        # => false
-  #
-  # @example Using keyword arguments
-  #   class Record
-  #     def complete?(status: nil)
-  #       status.nil? || status == :validated
-  #     end
-  #   end
+  # Predicate matcher: passes when a predicate method of the actual value
+  # returns `true`. The matcher name `be_xxx` calls `xxx?`, and `have_xxx`
+  # calls `has_xxx?`, with `Kernel#public_send` bound to the actual value.
+  # The predicate must return `true` or `false`; any other value is an error,
+  # not a truthy pass.
   #
-  #   matcher = Matchi::Predicate.new(:be_complete, status: :validated)
-  #   matcher.match? { Record.new }  # => true
+  # Since the actual value answers the call, this matcher depends on the
+  # honesty of the object under test. Use it for the object's own documented
+  # predicates.
   #
-  # @example With block arguments
-  #   class List
-  #     def all?(&block)
-  #       block ? super : empty?
-  #     end
-  #   end
-  #
-  #   matcher = Matchi::Predicate.new(:be_all) { |x| x.positive? }
-  #   matcher.match? { [1, 2, 3] }    # => true
-  #   matcher.match? { [-1, 2, 3] }   # => false
-  #
-  # @see https://ruby-doc.org/core/Object.html#method-i-respond_to-3F
+  # @example
+  #   Matchi::Predicate.new(:be_empty).match? { [] }           # => true
+  #   Matchi::Predicate.new(:have_key, :a).match? { { a: 1 } } # => true
   class Predicate
-    # Mapping of predicate prefixes to their method name transformations.
-    # Each entry defines how a prefix should be converted to its method form.
-    #
-    # @api private
-    PREFIXES = {
-      "be_"   => ->(name) { "#{name.gsub(/\A(?:be_)/, "")}?" },
-      "have_" => ->(name) { "#{name.gsub(/\A(?:have_)/, "has_")}?" }
-    }.freeze
+    # A matcher name: `be_` or `have_`, then a letter, then letters, digits
+    # or underscores, in any script. It never ends with `?` or `!`.
+    NAME = /\A(be|have)_\p{Alpha}[\p{Alnum}_]*\z/
 
-    # Initialize the matcher with a predicate name and optional arguments.
-    #
-    # @api public
-    #
-    # @param name [#to_s] A matcher name starting with 'be_' or 'have_'
-    # @param args [Array] Optional positional arguments to pass to the predicate method
-    # @param kwargs [Hash] Optional keyword arguments to pass to the predicate method
-    # @param block [Proc] Optional block to pass to the predicate method
-    #
-    # @raise [ArgumentError] if the predicate name format is invalid
-    #
-    # @return [Predicate] a new instance of the matcher
-    #
-    # @example With simple predicate
-    #   Predicate.new(:be_empty)                # Empty check
-    #
-    # @example With arguments
-    #   Predicate.new(:have_key, :id)           # Key presence check
-    #
-    # @example With keyword arguments
-    #   Predicate.new(:be_valid, status: true)  # Conditional validation
+    # @param name [Symbol, String] `be_xxx` or `have_xxx`
+    # @param args [Array] positional arguments for the predicate
+    # @param kwargs [Hash] keyword arguments for the predicate
+    # @param block [Proc, nil] a block for the predicate
+    # @raise [ArgumentError] when the name does not start with be_ or have_
     def initialize(name, *args, **kwargs, &block)
       @name = String(name)
-      raise ::ArgumentError, "invalid predicate name format" unless valid_name?
+      raise ::ArgumentError, "name must match #{NAME.inspect} (got: #{name.inspect})" unless NAME.match?(@name)
 
+      @method_name = method_name
       @args = args
       @kwargs = kwargs
       @block = block
     end
 
-    # Checks if the yielded object responds to and returns true for the predicate.
-    #
-    # This method converts the predicate name into a method name according to the prefix
-    # mapping and calls it on the yielded object with any provided arguments. The method
-    # must return a boolean value, or a TypeError will be raised.
-    #
-    # @api public
-    #
-    # @yield [] Block that returns the object to check
-    # @yieldreturn [Object] The object to call the predicate method on
-    #
-    # @return [Boolean] true if the predicate method returns true
-    #
-    # @raise [ArgumentError] if no block is provided
-    # @raise [TypeError] if predicate method returns non-boolean value
-    #
-    # @example Basic usage
-    #   matcher = Predicate.new(:be_empty)
-    #   matcher.match? { [] }                # => true
-    #   matcher.match? { [1] }               # => false
-    #
-    # @example With arguments
-    #   matcher = Predicate.new(:have_key, :id)
-    #   matcher.match? { { id: 1 } }         # => true
+    # @yieldreturn [Object] the actual value
+    # @return [Boolean]
+    # @raise [ArgumentError] when no block is given
+    # @raise [TypeError] when the predicate returns something other than true or false
+    # @raise [NoMethodError] when the actual value has no such public predicate
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
-      value = yield.send(method_name, *@args, **@kwargs, &@block)
-      return value if [false, true].include?(value)
+      result = ::Kernel.instance_method(:public_send).bind_call(yield, @method_name, *@args, **@kwargs, &@block)
+      return result if true.equal?(result) || false.equal?(result)
 
-      raise ::TypeError, "Boolean expected, but #{value.class} instance returned."
+      raise ::TypeError, "#{@method_name} must return true or false (got a #{Constant.label(result_class(result))})"
     end
 
-    # Returns a human-readable description of the matcher.
-    #
-    # @api public
-    #
-    # @return [String] A string describing what this matcher verifies
-    #
-    # @example Simple predicate
-    #   Predicate.new(:be_empty).to_s                # => "be empty"
-    #
-    # @example With arguments
-    #   Predicate.new(:have_key, :id).to_s           # => "have key :id"
-    #
-    # @example With keyword arguments
-    #   Predicate.new(:be_valid, active: true).to_s  # => "be valid active: true"
+    # @return [String]
     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
+      arguments = @args.map(&:inspect) + @kwargs.map { |key, value| "#{key}: #{value.inspect}" }
+      arguments << "&block" if @block
+
+      [@name.tr("_", " "), arguments.join(", ")].reject(&:empty?).join(" ")
     end
 
     private
 
-    # Converts the predicate name into the actual method name to call.
-    #
-    # @api private
-    #
-    # @return [Symbol] The method name to call on the object
-    # @raise [ArgumentError] if the predicate prefix is unknown
-    #
-    # @example
-    #   # With be_ prefix
-    #   method_name                   # => :empty? (from be_empty)
-    #   # With have_ prefix
-    #   method_name                   # => :has_key? (from have_key)
     def method_name
-      _, transform = PREFIXES.find { |prefix, _| @name.start_with?(prefix) }
-      return transform.call(@name) if transform
+      return "#{@name.delete_prefix("be_")}?" if @name.start_with?("be_")
 
-      raise ::ArgumentError, "unknown prefix in predicate name: #{@name}"
+      "has_#{@name.delete_prefix("have_")}?"
     end
 
-    # Verifies that the predicate name follows the required format.
-    #
-    # @api private
-    #
-    # @return [Boolean] true if the name follows the required format
-    def valid_name?
-      return false if @name.match?(/[?!]\z/)
-
-      PREFIXES.keys.any? { |prefix| @name.start_with?(prefix) }
+    def result_class(result)
+      ::Kernel.instance_method(:class).bind_call(result)
     end
   end
 end