matchi 4.1.0 → 4.2.0

data/lib/matchi/change.rb

@@ -12,97 +12,171 @@ module Matchi
     # Initialize a wrapper of the change matcher with an object and the name of
     # one of its methods.
     #
-    # @example
-    #   require "matchi/change"
+    # @api public
+    #
+    # @param object [#object_id] The object whose state will be monitored
+    # @param method [Symbol] The name of the method to track
+    # @param args [Array] Additional positional arguments to pass to the method
+    # @param kwargs [Hash] Additional keyword arguments to pass to the method
+    # @param block [Proc] Optional block to pass to the method
+    #
+    # @raise [ArgumentError] if method is not a Symbol
+    # @raise [ArgumentError] if object doesn't respond to method
+    #
+    # @return [Change] a new instance of the change wrapper
+    #
+    # @example Basic initialization
+    #   array = []
+    #   Change.new(array, :length)              # Track array length changes
     #
-    #   Matchi::Change.new("foo", :to_s)
+    # @example With positional arguments
+    #   hash = { key: "value" }
+    #   Change.new(hash, :fetch, :key)          # Track specific key value
     #
-    # @param object [#object_id]  An object.
-    # @param method [Symbol]      The name of a method.
-    def initialize(object, method, ...)
+    # @example With keyword arguments
+    #   hash = { a: 1, b: 2 }
+    #   Change.new(hash, :fetch, default: 0)    # Track with default value
+    #
+    # @example With block
+    #   hash = { a: 1 }
+    #   Change.new(hash, :fetch, :b) { |k| k.to_s }  # Track with block default
+    def initialize(object, method, *args, **kwargs, &block)
       raise ::ArgumentError, "method must be a Symbol" unless method.is_a?(::Symbol)
       raise ::ArgumentError, "object must respond to method" unless object.respond_to?(method)
 
-      @state = -> { object.send(method, ...) }
+      @state = -> { object.send(method, *args, **kwargs, &block) }
     end
 
-    # Specifies a minimum delta of the expected change.
+    # Checks if the tracked method's return value changes when executing the block.
+    #
+    # This method verifies that the value changes in any way between the start and end
+    # of the block execution. It doesn't care about the type or magnitude of the change,
+    # only that it's different.
+    #
+    # @api public
+    #
+    # @yield [] Block during which the change should occur
+    # @yieldreturn [Object] Result of the block execution (not used)
+    #
+    # @return [Boolean] true if the value changed, false otherwise
+    #
+    # @raise [ArgumentError] if no block is provided
+    #
+    # @example Basic usage with array length
+    #   array = []
+    #   matcher = Change.new(array, :length)
+    #   matcher.match? { array << "item" }    # => true
+    #   matcher.match? { array.clear }        # => true (from 1 to 0)
+    #   matcher.match? { array.dup }          # => false (no change)
+    #
+    # @example With method parameters
+    #   hash = { key: "old" }
+    #   matcher = Change.new(hash, :fetch, :key)
+    #   matcher.match? { hash[:key] = "new" }  # => true
+    #   matcher.match? { hash[:key] = "new" }  # => false (same value)
+    #
+    # @example With computed values
+    #   text = "hello"
+    #   matcher = Change.new(text, :upcase)
+    #   matcher.match? { text.upcase! }        # => true
+    #   matcher.match? { text.upcase! }        # => false (already uppercase)
+    def match?
+      raise ::ArgumentError, "a block must be provided" unless block_given?
+
+      value_before = @state.call
+      yield
+      value_after = @state.call
+
+      !value_before.eql?(value_after)
+    end
+
+    # Returns a human-readable description of the matcher.
+    #
+    # @api public
+    #
+    # @return [String] A string describing what this matcher verifies
     #
     # @example
-    #   require "matchi/change"
+    #   Change.new("test", :upcase).to_s # => 'eq "test"'
+    def to_s
+      "change #{@state.inspect}"
+    end
+
+    # Specifies a minimum delta of the expected change.
     #
-    #   object = []
+    # @api public
     #
-    #   change_wrapper = Matchi::Change.new(object, :length)
-    #   change_wrapper.by_at_least(1)
+    # @param minimum_delta [#object_id] The minimum expected change amount
     #
-    # @param minimum_delta [#object_id] The minimum delta of the expected change.
+    # @return [#match?] A matcher that verifies the minimum change
     #
-    # @return [#match?] A *change by at least* matcher.
+    # @example
+    #   counter = 0
+    #   matcher = Change.new(counter, :to_i).by_at_least(5)
+    #   matcher.match? { counter += 6 }  # => true
     def by_at_least(minimum_delta)
       ByAtLeast.new(minimum_delta, &@state)
     end
 
     # Specifies a maximum delta of the expected change.
     #
-    # @example
-    #   require "matchi/change"
-    #
-    #   object = []
+    # @api public
     #
-    #   change_wrapper = Matchi::Change.new(object, :length)
-    #   change_wrapper.by_at_most(1)
+    # @param maximum_delta [#object_id] The maximum allowed change amount
     #
-    # @param maximum_delta [#object_id] The maximum delta of the expected change.
+    # @return [#match?] A matcher that verifies the maximum change
     #
-    # @return [#match?] A *change by at most* matcher.
+    # @example
+    #   counter = 0
+    #   matcher = Change.new(counter, :to_i).by_at_most(5)
+    #   matcher.match? { counter += 3 }  # => true
     def by_at_most(maximum_delta)
       ByAtMost.new(maximum_delta, &@state)
     end
 
-    # Specifies the delta of the expected change.
-    #
-    # @example
-    #   require "matchi/change"
+    # Specifies the exact delta of the expected change.
     #
-    #   object = []
+    # @api public
     #
-    #   change_wrapper = Matchi::Change.new(object, :length)
-    #   change_wrapper.by(1)
+    # @param delta [#object_id] The exact expected change amount
     #
-    # @param delta [#object_id] The delta of the expected change.
+    # @return [#match?] A matcher that verifies the exact change
     #
-    # @return [#match?] A *change by* matcher.
+    # @example
+    #   counter = 0
+    #   matcher = Change.new(counter, :to_i).by(5)
+    #   matcher.match? { counter += 5 }  # => true
     def by(delta)
       By.new(delta, &@state)
     end
 
-    # Specifies the original value.
+    # Specifies the original value in a value transition check.
     #
-    # @example
-    #   require "matchi/change"
+    # @api public
     #
-    #   change_wrapper = Matchi::Change.new("foo", :to_s)
-    #   change_wrapper.from("foo")
+    # @param old_value [#object_id] The expected initial value
     #
-    # @param old_value [#object_id] The original value.
+    # @return [#to] A wrapper for creating a from/to matcher
     #
-    # @return [#match?] A *change from* wrapper.
+    # @example
+    #   string = "foo"
+    #   Change.new(string, :to_s).from("foo").to("FOO")
     def from(old_value)
       From.new(old_value, &@state)
     end
 
-    # Specifies the new value to expect.
+    # Specifies the final value to expect.
     #
-    # @example
-    #   require "matchi/change"
+    # @api public
     #
-    #   change_wrapper = Matchi::Change.new("foo", :to_s)
-    #   change_wrapper.to("FOO")
+    # @param new_value [#object_id] The expected final value
     #
-    # @param new_value [#object_id] The new value to expect.
+    # @return [#match?] A matcher that verifies the final state
     #
-    # @return [#match?] A *change to* matcher.
+    # @example
+    #   string = "foo"
+    #   matcher = Change.new(string, :to_s).to("FOO")
+    #   matcher.match? { string.upcase! }  # => true
     def to(new_value)
       To.new(new_value, &@state)
     end

data/lib/matchi/eq.rb

@@ -1,41 +1,83 @@
 # frozen_string_literal: true
 
 module Matchi
-  # *Equivalence* matcher.
+  # Value equivalence matcher that checks if two objects have identical values.
+  #
+  # 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.
+  #
+  # @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
   class Eq
-    # Initialize the matcher with an object.
+    # Initialize the matcher with a reference value.
     #
-    # @example
-    #   require "matchi/eq"
+    # @api public
+    #
+    # @param expected [#eql?] The expected equivalent value
     #
-    #   Matchi::Eq.new("foo")
+    # @return [Eq] a new instance of the matcher
     #
-    # @param expected [#eql?] An expected equivalent object.
+    # @example
+    #   Eq.new("test")              # Match strings with same value
+    #   Eq.new([1, 2, 3])           # Match arrays with same elements
     def initialize(expected)
       @expected = expected
     end
 
-    # Boolean comparison between the actual value and the expected value.
+    # Checks if the yielded object has a value equivalent to the expected object.
     #
-    # @example
-    #   require "matchi/eq"
+    # 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
     #
-    #   matcher = Matchi::Eq.new("foo")
-    #   matcher.match? { "foo" } # => true
+    # @yield [] Block that returns the object to check
+    # @yieldreturn [Object] The object to verify equivalence with
     #
-    # @yieldreturn [#object_id] The actual value to compare to the expected
-    #   one.
+    # @return [Boolean] true if both objects have equivalent values
     #
-    # @return [Boolean] Comparison between actual and expected 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
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
       @expected.eql?(yield)
     end
 
-    # Returns a string representing the matcher.
+    # Returns a human-readable description of the matcher.
+    #
+    # @api public
     #
-    # @return [String] a human-readable description of the matcher
+    # @return [String] A string describing what this matcher verifies
+    #
+    # @example
+    #   Eq.new("test").to_s # => 'eq "test"'
     def to_s
       "eq #{@expected.inspect}"
     end

data/lib/matchi/match.rb

@@ -1,43 +1,83 @@
 # frozen_string_literal: true
 
 module Matchi
-  # *Regular expressions* matcher.
+  # Pattern matching matcher that checks if a value matches a regular expression.
+  #
+  # 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?.
+  #
+  # @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
   class Match
-    # Initialize the matcher with an instance of Regexp.
+    # Initialize the matcher with a pattern.
     #
-    # @example
-    #   require "matchi/match"
+    # @api public
+    #
+    # @param expected [#match?] A pattern that responds to match?
+    #
+    # @raise [ArgumentError] if the pattern doesn't respond to match?
     #
-    #   Matchi::Match.new(/^foo$/)
+    # @return [Match] a new instance of the matcher
     #
-    # @param expected [#match] A regular expression.
+    # @example
+    #   Match.new(/\d+/)           # Match digits
+    #   Match.new(/^test$/i)       # Case-insensitive match
+    #   Match.new(/\A\w+\Z/)       # Full string word characters
     def initialize(expected)
       raise ::ArgumentError, "expected must respond to match?" unless expected.respond_to?(:match?)
 
       @expected = expected
     end
 
-    # Boolean comparison between the actual value and the expected value.
+    # Checks if the yielded value matches the expected pattern.
     #
-    # @example
-    #   require "matchi/match"
+    # 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
     #
-    #   matcher = Matchi::Match.new(/^foo$/)
-    #   matcher.match? { "foo" } # => true
+    # @yield [] Block that returns the value to check
+    # @yieldreturn [#to_s] The value to match against the pattern
     #
-    # @yieldreturn [#object_id] The actual value to compare to the expected
-    #   one.
+    # @return [Boolean] true if the value matches the pattern
     #
-    # @return [Boolean] Comparison between actual and expected values.
+    # @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
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
       @expected.match?(yield)
     end
 
-    # Returns a string representing the matcher.
+    # Returns a human-readable description of the matcher.
+    #
+    # @api public
     #
-    # @return [String] a human-readable description of the matcher
+    # @return [String] A string describing what this matcher verifies
+    #
+    # @example
+    #   Match.new(/^test/).to_s # => "match /^test/"
     def to_s
       "match #{@expected.inspect}"
     end

data/lib/matchi/predicate.rb

@@ -1,45 +1,109 @@
 # frozen_string_literal: true
 
 module Matchi
-  # *Predicate* matcher.
+  # 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
+  #
+  #   matcher = Matchi::Predicate.new(:be_complete, status: :validated)
+  #   matcher.match? { Record.new }  # => true
+  #
+  # @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
   class Predicate
-    # Initialize the matcher with a name and arguments.
+    # Mapping of predicate prefixes to their method name transformations.
+    # Each entry defines how a prefix should be converted to its method form.
     #
-    # @example
-    #   require "matchi/predicate"
+    # @api private
+    PREFIXES = {
+      "be_"   => ->(name) { "#{name.gsub(/\A(?:be_)/, "")}?" },
+      "have_" => ->(name) { "#{name.gsub(/\A(?:have_)/, "has_")}?" }
+    }.freeze
+
+    # 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
     #
-    #   Matchi::Predicate.new(:be_empty)
+    # @example With simple predicate
+    #   Predicate.new(:be_empty)                # Empty check
     #
-    # @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.
+    # @example With arguments
+    #   Predicate.new(:have_key, :id)           # Key presence check
+    #
+    # @example With keyword arguments
+    #   Predicate.new(:be_valid, status: true)  # Conditional validation
     def initialize(name, *args, **kwargs, &block)
       @name = String(name)
       raise ::ArgumentError, "invalid predicate name format" unless valid_name?
 
-      @args   = args
+      @args = args
       @kwargs = kwargs
-      @block  = block
+      @block = block
     end
 
-    # Boolean comparison between the actual value and the expected value.
+    # Checks if the yielded object responds to and returns true for the predicate.
     #
-    # @example
-    #   require "matchi/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.
     #
-    #   matcher = Matchi::Predicate.new(:be_empty)
-    #   matcher.match? { [] } # => true
+    # @api public
     #
-    # @example
-    #   require "matchi/predicate"
+    # @yield [] Block that returns the object to check
+    # @yieldreturn [Object] The object to call the predicate method on
     #
-    #   matcher = Matchi::Predicate.new(:have_key, :foo)
-    #   matcher.match? { { foo: 42 } } # => true
+    # @return [Boolean] true if the predicate method returns true
     #
-    # @yieldreturn [#object_id] The actual value to receive the method request.
+    # @raise [ArgumentError] if no block is provided
+    # @raise [TypeError] if predicate method returns non-boolean value
     #
-    # @return [Boolean] A boolean returned by the actual value being tested.
+    # @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
     def match?
       raise ::ArgumentError, "a block must be provided" unless block_given?
 
@@ -49,9 +113,20 @@ module Matchi
       raise ::TypeError, "Boolean expected, but #{value.class} instance returned."
     end
 
-    # Returns a string representing the matcher.
+    # Returns a human-readable description of the matcher.
+    #
+    # @api public
     #
-    # @return [String] a human-readable description of the matcher
+    # @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"
     def to_s
       (
         "#{@name.tr("_", " ")} " + [
@@ -64,20 +139,34 @@ module Matchi
 
     private
 
-    # The name of the method to send to the object.
+    # 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
-      if @name.start_with?("be_")
-        :"#{@name.gsub("be_", "")}?"
-      else
-        :"#{@name.gsub("have_", "has_")}?"
-      end
+      _, transform = PREFIXES.find { |prefix, _| @name.start_with?(prefix) }
+      return transform.call(@name) if transform
+
+      raise ::ArgumentError, "unknown prefix in predicate name: #{@name}"
     end
 
-    # Verify the matcher name structure.
+    # 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.end_with?("?", "!")
+      return false if @name.match?(/[?!]\z/)
 
-      @name.start_with?("be_", "have_")
+      PREFIXES.keys.any? { |prefix| @name.start_with?(prefix) }
     end
   end
 end