matchi 4.2.0 → 5.0.0

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

data/lib/matchi/raise_exception.rb

@@ -1,133 +1,101 @@
 # frozen_string_literal: true
 
+require_relative "constant"
+
 module Matchi
-  # Exception matcher that verifies if a block of code raises a specific exception.
-  #
-  # This matcher ensures that code raises an expected exception by executing it within
-  # a controlled environment. It supports matching against specific exception classes
-  # and their subclasses, providing a reliable way to test error handling.
-  #
-  # @example Basic usage with standard exceptions
-  #   matcher = Matchi::RaiseException.new(ArgumentError)
-  #   matcher.match? { raise ArgumentError }    # => true
-  #   matcher.match? { raise RuntimeError }     # => false
-  #   matcher.match? { "no error" }             # => false
-  #
-  # @example Working with inheritance hierarchy
-  #   class CustomError < StandardError; end
-  #   class SpecificError < CustomError; end
-  #
-  #   matcher = Matchi::RaiseException.new(CustomError)
-  #   matcher.match? { raise CustomError }      # => true
-  #   matcher.match? { raise SpecificError }    # => true
-  #   matcher.match? { raise StandardError }    # => false
+  # Exception matcher: passes when evaluating the block raises an exception
+  # of the expected class or of one of its descendants (`Module#===`, so the
+  # exception cannot lie about its class), optionally with an expected
+  # message: a String the message must be `eql?` to, or a Regexp it must
+  # match.
   #
-  # @example Using string class names
-  #   matcher = Matchi::RaiseException.new("ArgumentError")
-  #   matcher.match? { raise ArgumentError }    # => true
+  # Every `Exception` is caught, including `SystemExit` and `Interrupt`: a
+  # specification must be able to assert on any of them, so an unexpected
+  # `exit` or Ctrl-C inside the block is reported as a failure, not
+  # propagated. The expected class can be given directly, or by name; see
+  # {Matchi::Constant}.
   #
-  # @example With custom exception hierarchies
-  #   module Api
-  #     class Error < StandardError; end
-  #     class AuthenticationError < Error; end
-  #   end
-  #
-  #   matcher = Matchi::RaiseException.new("Api::Error")
-  #   matcher.match? { raise Api::AuthenticationError } # => true
-  #
-  # @see https://ruby-doc.org/core/Exception.html
-  # @see https://ruby-doc.org/core/StandardError.html
+  # @example
+  #   Matchi::RaiseException.new(ZeroDivisionError).match? { 1 / 0 }              # => true
+  #   Matchi::RaiseException.new(:StandardError).match? { 1 / 0 }                 # => true
+  #   Matchi::RaiseException.new(ZeroDivisionError, /by 0/).match? { 1 / 0 }      # => true
+  #   Matchi::RaiseException.new(ZeroDivisionError, "nope").match? { 1 / 0 }      # => false
+  #   Matchi::RaiseException.new(IOError).match? { 1 / 0 }                        # => false
   class RaiseException
-    # Initialize the matcher with an exception class.
-    #
-    # @api public
-    #
-    # @param expected [Exception, #to_s] The expected exception class or its name
-    #   Can be provided as a Class, String, or Symbol
-    #
-    # @raise [ArgumentError] if the class name doesn't start with an uppercase letter
-    #
-    # @return [RaiseException] a new instance of the matcher
-    #
-    # @example
-    #   RaiseException.new(ArgumentError)         # Using class
-    #   RaiseException.new("ArgumentError")       # Using string
-    #   RaiseException.new(:ArgumentError)        # Using symbol
-    #   RaiseException.new("Api::CustomError")    # Using namespaced class
-    def initialize(expected)
-      @expected = String(expected)
-      return if /\A[A-Z]/.match?(@expected)
-
-      raise ::ArgumentError,
-            "expected must start with an uppercase letter (got: #{@expected})"
+    # @param expected [Class, String, Symbol] the expected exception class, or its name
+    # @param message [String, Regexp, nil] the expected message, exact or as a pattern
+    # @raise [ArgumentError] when expected is neither an Exception class nor a constant name,
+    #   or message is neither a String nor a Regexp
+    def initialize(expected, message = nil)
+      @expected = Constant.normalize(expected, ::Class)
+      @message = message
+      validate_class!
+      validate_message!
     end
 
-    # Checks if the yielded block raises the expected exception.
-    #
-    # This method executes the provided block within a begin/rescue clause and verifies
-    # that it raises an exception of the expected type. It also handles inheritance,
-    # allowing subclasses of the expected exception to match.
-    #
-    # @api public
-    #
-    # @yield [] Block that should raise an exception
-    # @yieldreturn [Object] The result of the block (if it doesn't raise)
-    #
-    # @return [Boolean] true if the block raises the expected exception
-    #
-    # @raise [ArgumentError] if no block is provided
-    # @raise [ArgumentError] if expected exception class doesn't inherit from Exception
-    # @raise [NameError] if the expected exception class cannot be found
-    #
-    # @example Standard usage
-    #   matcher = RaiseException.new(ArgumentError)
-    #   matcher.match? { raise ArgumentError }     # => true
-    #
-    # @example With inheritance
-    #   matcher = RaiseException.new(StandardError)
-    #   matcher.match? { raise ArgumentError }     # => true
-    #
-    # @example Without exception
-    #   matcher = RaiseException.new(StandardError)
-    #   matcher.match? { "no error" }             # => false
+    # @yieldreturn [Object] ignored, the block is evaluated for its exception
+    # @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 an Exception class
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
+      # Resolved before the block, so that a NameError from the name is not
+      # mistaken for an exception raised by the block.
       klass = expected_class
-      raise ::ArgumentError, "expected exception class must inherit from Exception" unless klass <= ::Exception
 
       begin
         yield
         false
       rescue ::Exception => e # rubocop:disable Lint/RescueException
-        e.class <= klass
+        klass === e && message?(e)
       end
     end
 
-    # Returns a human-readable description of the matcher.
-    #
-    # @api public
-    #
-    # @return [String] A string describing what this matcher verifies
-    #
-    # @example
-    #   RaiseException.new(ArgumentError).to_s  # => "raise exception ArgumentError"
+    # @return [String]
     def to_s
-      "raise exception #{@expected}"
+      return "raise exception #{Constant.label(@expected)}" if @message.nil?
+
+      "raise exception #{Constant.label(@expected)} with message #{@message.inspect}"
     end
 
     private
 
-    # Resolves the expected class name to an actual Exception class.
-    #
-    # @api private
-    #
-    # @return [Class] The resolved exception class
-    # @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 validate_class!
+      return unless ::Class === @expected
+      return if @expected <= ::Exception
+
+      raise ::ArgumentError, "expected must inherit from Exception (got: #{@expected.inspect})"
+    end
+
+    def validate_message!
+      return if @message.nil? || ::String === @message || ::Regexp === @message
+
+      raise ::ArgumentError, "message must be a String or a Regexp (got: #{@message.inspect})"
+    end
+
     def expected_class
-      ::Object.const_get(@expected)
+      return @expected if ::Class === @expected
+
+      klass = Constant.resolve(@expected, ::Class)
+      raise ::TypeError, "#{@expected} is not an Exception class" unless klass <= ::Exception
+
+      klass
+    end
+
+    # The message is whatever the exception answers to `message`, which is
+    # its own data, as with any exception; it must be a valid String. The
+    # expected String or Regexp receives the comparison.
+    def message?(exception)
+      return true if @message.nil?
+
+      message = exception.message
+      return false unless ::String === message && message.valid_encoding?
+
+      ::String === @message ? @message.eql?(message) : @message.match?(message)
+    rescue ::Encoding::CompatibilityError
+      false
     end
   end
 end

data/lib/matchi/satisfy.rb

@@ -1,114 +1,39 @@
 # frozen_string_literal: true
 
+require_relative "constant"
+
 module Matchi
-  # Custom predicate matcher that validates values against an arbitrary condition.
-  #
-  # This matcher provides a flexible way to test values against custom conditions
-  # defined in a block. Unlike specific matchers that test for predetermined
-  # conditions, Satisfy allows you to define any custom validation logic at runtime.
-  # This makes it particularly useful for complex or composite conditions that
-  # aren't covered by other matchers.
-  #
-  # @example Basic numeric validation
-  #   matcher = Matchi::Satisfy.new { |n| n.positive? && n.even? }
-  #   matcher.match? { 2 }             # => true
-  #   matcher.match? { -2 }            # => false
-  #   matcher.match? { 3 }             # => false
-  #
-  # @example String pattern validation
-  #   matcher = Matchi::Satisfy.new { |s| s.start_with?("test") && s.length < 10 }
-  #   matcher.match? { "test_123" }    # => true
-  #   matcher.match? { "test_12345" }  # => false
-  #   matcher.match? { "other" }       # => false
+  # Custom matcher: passes when the given block, called with the actual value,
+  # returns `true`. The block must return `true` or `false`; any other value
+  # is an error, not a truthy pass.
   #
-  # @example Complex object validation
-  #   class User
-  #     attr_reader :age, :name
-  #     def initialize(name, age)
-  #       @name, @age = name, age
-  #     end
-  #   end
-  #
-  #   matcher = Matchi::Satisfy.new { |user|
-  #     user.age >= 18 && user.name.length >= 2
-  #   }
-  #   matcher.match? { User.new("Alice", 25) }  # => true
-  #   matcher.match? { User.new("B", 20) }      # => false
-  #
-  # @example Using with collections
-  #   matcher = Matchi::Satisfy.new { |arr|
-  #     arr.all? { |x| x.is_a?(Integer) } && arr.sum.even?
-  #   }
-  #   matcher.match? { [2, 4, 6] }      # => true
-  #   matcher.match? { [1, 3, 5] }      # => false
-  #   matcher.match? { [1, "2", 3] }    # => false
-  #
-  # @see https://ruby-doc.org/core/Proc.html
-  # @see Matchi::Predicate  For testing existing predicate methods
+  # @example
+  #   Matchi::Satisfy.new { |value| value > 41 }.match? { 42 } # => true
   class Satisfy
-    # Initialize the matcher with a validation block.
-    #
-    # @api public
-    #
-    # @yield [Object] Block that defines the validation condition
-    # @yieldparam value The value to validate
-    # @yieldreturn [Boolean] true if the value meets the condition
-    #
-    # @raise [ArgumentError] if no block is provided
-    #
-    # @return [Satisfy] a new instance of the matcher
-    #
-    # @example Simple numeric validation
-    #   Satisfy.new { |n| n > 0 }
-    #
-    # @example Complex condition
-    #   Satisfy.new { |obj|
-    #     obj.respond_to?(:length) && obj.length.between?(2, 10)
-    #   }
+    # @yieldparam actual [Object] the actual value
+    # @yieldreturn [Boolean]
+    # @raise [ArgumentError] when no block is given
     def initialize(&block)
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
-      @expected = block
+      @predicate = block
     end
 
-    # Checks if the yielded value satisfies the validation block.
-    #
-    # This method passes the value returned by the provided block to the
-    # validation block defined at initialization. The matcher succeeds if
-    # the validation block returns a truthy value.
-    #
-    # @api public
-    #
-    # @yield [] Block that returns the value to validate
-    # @yieldreturn [Object] The value to check against the condition
-    #
-    # @return [Boolean] true if the value satisfies the condition
-    #
-    # @raise [ArgumentError] if no block is provided
-    #
-    # @example Using with direct values
-    #   matcher = Satisfy.new { |n| n.positive? }
-    #   matcher.match? { 42 }    # => true
-    #   matcher.match? { -1 }    # => false
-    #
-    # @example Using with computed values
-    #   matcher = Satisfy.new { |s| s.length.even? }
-    #   matcher.match? { "test".upcase }  # => true
-    #   matcher.match? { "a" * 3 }        # => false
+    # @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
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
-      @expected.call(yield)
+      result = @predicate.call(yield)
+      return result if true.equal?(result) || false.equal?(result)
+
+      klass = ::Kernel.instance_method(:class).bind_call(result)
+      raise ::TypeError, "the block must return true or false (got a #{Constant.label(klass)})"
     end
 
-    # Returns a human-readable description of the matcher.
-    #
-    # @api public
-    #
-    # @return [String] A string describing what this matcher verifies
-    #
-    # @example
-    #   Satisfy.new { |n| n > 0 }.to_s  # => "satisfy &block"
+    # @return [String]
     def to_s
       "satisfy &block"
     end