matchi 4.2.0 → 5.0.0

data/lib/matchi.rb

@@ -1,65 +1,27 @@
 # frozen_string_literal: true
 
-# Main namespace for the Matchi gem, providing a collection of expectation matchers.
-#
-# Matchi is a framework-agnostic Ruby library that offers a comprehensive set of
-# matchers for testing and verification purposes. Each matcher follows a consistent
-# interface pattern, making them easy to use and extend.
-#
-# @example Basic usage with equality matcher
-#   Matchi::Eq.new("hello").match? { "hello" }     # => true
-#   Matchi::Eq.new("hello").match? { "world" }     # => false
-#
-# @example Type checking with inheritance awareness
-#   Matchi::BeAKindOf.new(Numeric).match? { 42 }   # => true
-#   Matchi::BeAKindOf.new(String).match? { 42 }    # => false
-#
-# @example Verifying state changes
-#   array = []
-#   Matchi::Change.new(array, :length).by(2).match? { array.push(1, 2) }  # => true
-#
-# @example Pattern matching with regular expressions
-#   Matchi::Match.new(/^test/).match? { "test_string" }  # => true
-#
-# Each matcher in the Matchi ecosystem implements a consistent interface:
-# - An initializer that sets up the expected values or conditions
-# - A #match? method that takes a block and returns a boolean
-# - An optional #to_s method that provides a human-readable description
-#
-# @example Creating a custom matcher
-#   module Matchi
-#     class BePositive
-#       def match?
-#         raise ArgumentError, "a block must be provided" unless block_given?
-#         yield.positive?
-#       end
-#
-#       def to_s
-#         "be positive"
-#       end
-#     end
-#   end
-#
-# @see Matchi::Be
-# @see Matchi::BeAKindOf
-# @see Matchi::BeAnInstanceOf
-# @see Matchi::BeWithin
-# @see Matchi::Change
-# @see Matchi::Eq
-# @see Matchi::Match
-# @see Matchi::Predicate
-# @see Matchi::RaiseException
-# @see Matchi::Satisfy
+# Framework-agnostic matchers for Ruby.
+#
+# A matcher is any object that responds to `match?` with a block and to
+# `to_s`. The block is evaluated once and yields the actual value, or, for
+# `Change` and `RaiseException`, produces the effect to observe; the matcher
+# returns `true` or `false`. The expected value controls the comparison
+# wherever a comparison takes place, so a hostile actual value cannot forge
+# a match; `Predicate` and the `Change` refinements by delta, which use
+# values produced by the object under test, depend on its honesty.
+#
+# @example
+#   Matchi::Eq.new(42).match? { 42 } # => true
 module Matchi
 end
 
-require "matchi/be"
-require "matchi/be_a_kind_of"
-require "matchi/be_an_instance_of"
-require "matchi/be_within"
-require "matchi/change"
-require "matchi/eq"
-require "matchi/match"
-require "matchi/predicate"
-require "matchi/raise_exception"
-require "matchi/satisfy"
+require_relative "matchi/be"
+require_relative "matchi/be_a_kind_of"
+require_relative "matchi/be_an_instance_of"
+require_relative "matchi/be_within"
+require_relative "matchi/change"
+require_relative "matchi/eq"
+require_relative "matchi/match"
+require_relative "matchi/predicate"
+require_relative "matchi/raise_exception"
+require_relative "matchi/satisfy"

metadata

@@ -1,22 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: matchi
 version: !ruby/object:Gem::Version
-  version: 4.2.0
+  version: 5.0.0
 platform: ruby
 authors:
 - Cyril Kato
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-05 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies: []
-description: 'Matchi is a framework-agnostic Ruby library that provides a comprehensive
-  set of expectation matchers for elegant and secure testing. Its design focuses on
-  simplicity, security, and extensibility, making it easy to integrate with any testing
-  framework. The library offers a rich collection of built-in matchers for common
-  testing scenarios while maintaining a clear, consistent API that follows Ruby best
-  practices. With minimal setup required and support for custom matchers, Matchi enables
-  developers to write more reliable and maintainable tests.
+description: 'Matchi provides small, explicit expectation matchers for any Ruby testing
+  framework. The expected value always controls the comparison, so the object under
+  test cannot forge a match.
 
   '
 email: contact@cyril.email
@@ -31,23 +27,27 @@ files:
 - lib/matchi/be_a_kind_of.rb
 - lib/matchi/be_an_instance_of.rb
 - lib/matchi/be_within.rb
+- lib/matchi/be_within/of.rb
 - lib/matchi/change.rb
-- lib/matchi/change/by.rb
-- lib/matchi/change/by_at_least.rb
-- lib/matchi/change/by_at_most.rb
+- lib/matchi/change/delta.rb
 - lib/matchi/change/from.rb
-- lib/matchi/change/from/to.rb
+- lib/matchi/change/from_to.rb
 - lib/matchi/change/to.rb
+- lib/matchi/constant.rb
 - lib/matchi/eq.rb
 - lib/matchi/match.rb
+- lib/matchi/number.rb
 - lib/matchi/predicate.rb
 - lib/matchi/raise_exception.rb
 - lib/matchi/satisfy.rb
-homepage: https://github.com/fixrb/matchi
+homepage: https://fixrb.dev/gems/matchi/
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/fixrb/matchi/issues
+  documentation_uri: https://rubydoc.info/gems/matchi
   rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/fixrb/matchi
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -56,15 +56,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.27
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: "Framework-agnostic matchers for secure, elegant Ruby testing \U0001F939"
+summary: Framework-agnostic matchers for secure Ruby testing
 test_files: []

data/lib/matchi/change/by.rb

@@ -1,137 +0,0 @@
-# frozen_string_literal: true
-
-module Matchi
-  class Change
-    # Exact delta matcher that verifies precise numeric changes in object state.
-    #
-    # This matcher ensures that a numeric value changes by exactly the specified amount
-    # after executing a block of code. It's particularly useful for testing operations
-    # that should produce precise, predictable changes in numeric attributes, such as
-    # counters, quantities, or calculated values.
-    #
-    # @example Testing collection size changes
-    #   array = []
-    #   matcher = Matchi::Change::By.new(2) { array.size }
-    #   matcher.match? { array.concat([1, 2]) }     # => true
-    #   matcher.match? { array.push(3) }            # => false  # Changed by 1
-    #   matcher.match? { array.push(3, 4, 5) }      # => false  # Changed by 3
-    #
-    # @example Verifying numeric calculations
-    #   counter = 100
-    #   matcher = Matchi::Change::By.new(-10) { counter }
-    #   matcher.match? { counter -= 10 }            # => true
-    #   matcher.match? { counter -= 15 }            # => false  # Changed too much
-    #
-    # @example Working with custom numeric attributes
-    #   class Account
-    #     attr_reader :balance
-    #
-    #     def initialize(initial_balance)
-    #       @balance = initial_balance
-    #     end
-    #
-    #     def deposit(amount)
-    #       @balance += amount
-    #     end
-    #
-    #     def withdraw(amount)
-    #       @balance -= amount
-    #     end
-    #   end
-    #
-    #   account = Account.new(1000)
-    #   matcher = Matchi::Change::By.new(50) { account.balance }
-    #   matcher.match? { account.deposit(50) }      # => true
-    #   matcher.match? { account.deposit(75) }      # => false  # Changed by 75
-    #
-    # @example Handling floating point values
-    #   temperature = 20.0
-    #   matcher = Matchi::Change::By.new(1.5) { temperature }
-    #   matcher.match? { temperature += 1.5 }       # => true
-    #   matcher.match? { temperature += 1.6 }       # => false  # Not exact match
-    #
-    # @note This matcher checks for exact changes, use ByAtLeast or ByAtMost for
-    #   more flexible delta comparisons
-    #
-    # @see Matchi::Change::ByAtLeast For minimum change validation
-    # @see Matchi::Change::ByAtMost For maximum change validation
-    # @see Matchi::Change::From::To For exact value transition validation
-    class By
-      # Initialize the matcher with an expected delta and a state block.
-      #
-      # @api public
-      #
-      # @param expected [Numeric] The exact amount by which the value should change
-      # @param state [Proc] Block that retrieves the current value
-      #
-      # @raise [ArgumentError] if expected is not a Numeric
-      # @raise [ArgumentError] if no state block is provided
-      #
-      # @return [By] a new instance of the matcher
-      #
-      # @example With positive delta
-      #   By.new(5) { counter.value }
-      #
-      # @example With negative delta
-      #   By.new(-3) { stock_level.quantity }
-      #
-      # @example With floating point delta
-      #   By.new(0.5) { temperature.celsius }
-      def initialize(expected, &state)
-        raise ::ArgumentError, "expected must be a Numeric" unless expected.is_a?(::Numeric)
-        raise ::ArgumentError, "a block must be provided" unless block_given?
-
-        @expected = expected
-        @state = state
-      end
-
-      # Verifies that the value changes by exactly the expected amount.
-      #
-      # This method compares the value before and after executing the provided block,
-      # ensuring that the difference matches the expected delta exactly. It's useful
-      # for cases where precision is important and approximate changes are not acceptable.
-      #
-      # @api public
-      #
-      # @yield [] Block that should cause the state change
-      # @yieldreturn [Object] The result of the block (not used)
-      #
-      # @return [Boolean] true if the value changed by exactly the expected amount
-      #
-      # @raise [ArgumentError] if no block is provided
-      #
-      # @example Basic usage
-      #   counter = 0
-      #   matcher = By.new(5) { counter }
-      #   matcher.match? { counter += 5 }  # => true
-      #
-      # @example Failed match
-      #   items = []
-      #   matcher = By.new(2) { items.size }
-      #   matcher.match? { items.push(1) }  # => false  # Changed by 1
-      def match?
-        raise ::ArgumentError, "a block must be provided" unless block_given?
-
-        value_before = @state.call
-        yield
-        value_after = @state.call
-
-        @expected == (value_after - value_before)
-      end
-
-      # Returns a human-readable description of the matcher.
-      #
-      # @api public
-      #
-      # @return [String] A string describing what this matcher verifies
-      #
-      # @example
-      #   By.new(5).to_s    # => "change by 5"
-      #   By.new(-3).to_s   # => "change by -3"
-      #   By.new(2.5).to_s  # => "change by 2.5"
-      def to_s
-        "change by #{@expected.inspect}"
-      end
-    end
-  end
-end

data/lib/matchi/change/by_at_least.rb

@@ -1,158 +0,0 @@
-# frozen_string_literal: true
-
-module Matchi
-  class Change
-    # Minimum delta matcher that verifies numeric changes meet or exceed a threshold.
-    #
-    # This matcher ensures that a numeric value changes by at least the specified amount
-    # after executing a block of code. It's particularly useful when testing operations
-    # where you want to ensure a minimum change occurs but larger changes are acceptable,
-    # such as performance improvements, resource allocation, or progressive counters.
-    #
-    # @example Testing collection growth
-    #   items = []
-    #   matcher = Matchi::Change::ByAtLeast.new(2) { items.size }
-    #   matcher.match? { items.push(1, 2) }          # => true   # Changed by exactly 2
-    #   matcher.match? { items.push(1, 2, 3) }       # => true   # Changed by more than 2
-    #   matcher.match? { items.push(1) }             # => false  # Changed by less than 2
-    #
-    # @example Verifying performance improvements
-    #   class Benchmark
-    #     def initialize
-    #       @score = 100
-    #     end
-    #
-    #     def optimize!
-    #       @score += rand(20..30)  # Improvement varies
-    #     end
-    #
-    #     def score
-    #       @score
-    #     end
-    #   end
-    #
-    #   benchmark = Benchmark.new
-    #   matcher = Matchi::Change::ByAtLeast.new(20) { benchmark.score }
-    #   matcher.match? { benchmark.optimize! }   # => true  # Any improvement >= 20 passes
-    #
-    # @example Resource allocation
-    #   class Pool
-    #     def initialize
-    #       @capacity = 1000
-    #     end
-    #
-    #     def allocate(minimum, maximum)
-    #       actual = rand(minimum..maximum)
-    #       @capacity -= actual
-    #       actual
-    #     end
-    #
-    #     def available
-    #       @capacity
-    #     end
-    #   end
-    #
-    #   pool = Pool.new
-    #   matcher = Matchi::Change::ByAtLeast.new(50) { -pool.available }
-    #   matcher.match? { pool.allocate(50, 100) }  # => true  # Allocates at least 50
-    #
-    # @example Price threshold monitoring
-    #   class Stock
-    #     attr_reader :price
-    #
-    #     def initialize(price)
-    #       @price = price
-    #     end
-    #
-    #     def fluctuate!
-    #       @price += rand(-10.0..20.0)
-    #     end
-    #   end
-    #
-    #   stock = Stock.new(100.0)
-    #   matcher = Matchi::Change::ByAtLeast.new(10.0) { stock.price }
-    #   matcher.match? { stock.fluctuate! }  # => true if price rises by 10.0 or more
-    #
-    # @note This matcher verifies minimum changes only. For exact changes, use By,
-    #   and for maximum changes, use ByAtMost.
-    #
-    # @see Matchi::Change::By For exact change validation
-    # @see Matchi::Change::ByAtMost For maximum change validation
-    # @see Matchi::Change::To For final value validation
-    class ByAtLeast
-      # Initialize the matcher with a minimum expected change and a state block.
-      #
-      # @api public
-      #
-      # @param expected [Numeric] The minimum amount by which the value should change
-      # @param state [Proc] Block that retrieves the current value
-      #
-      # @raise [ArgumentError] if expected is not a Numeric
-      # @raise [ArgumentError] if expected is negative
-      # @raise [ArgumentError] if no state block is provided
-      #
-      # @return [ByAtLeast] a new instance of the matcher
-      #
-      # @example With integer minimum
-      #   ByAtLeast.new(5) { counter.value }
-      #
-      # @example With floating point minimum
-      #   ByAtLeast.new(0.5) { temperature.celsius }
-      def initialize(expected, &state)
-        raise ::ArgumentError, "expected must be a Numeric" unless expected.is_a?(::Numeric)
-        raise ::ArgumentError, "a block must be provided" unless block_given?
-        raise ::ArgumentError, "expected must be non-negative" if expected.negative?
-
-        @expected = expected
-        @state    = state
-      end
-
-      # Checks if the value changes by at least the expected amount.
-      #
-      # This method compares the value before and after executing the provided block,
-      # ensuring that the difference is greater than or equal to the expected minimum.
-      # This is useful when you want to verify that a change meets a minimum threshold.
-      #
-      # @api public
-      #
-      # @yield [] Block that should cause the state change
-      # @yieldreturn [Object] The result of the block (not used)
-      #
-      # @return [Boolean] true if the value changed by at least the expected amount
-      #
-      # @raise [ArgumentError] if no block is provided
-      #
-      # @example Basic usage
-      #   counter = 0
-      #   matcher = ByAtLeast.new(5) { counter }
-      #   matcher.match? { counter += 7 }  # => true   # Changed by more than minimum
-      #
-      # @example Edge case - exact minimum
-      #   items = []
-      #   matcher = ByAtLeast.new(2) { items.size }
-      #   matcher.match? { items.push(1, 2) }  # => true  # Changed by exactly minimum
-      def match?
-        raise ::ArgumentError, "a block must be provided" unless block_given?
-
-        value_before = @state.call
-        yield
-        value_after = @state.call
-
-        @expected <= (value_after - value_before)
-      end
-
-      # Returns a human-readable description of the matcher.
-      #
-      # @api public
-      #
-      # @return [String] A string describing what this matcher verifies
-      #
-      # @example
-      #   ByAtLeast.new(5).to_s    # => "change by at least 5"
-      #   ByAtLeast.new(2.5).to_s  # => "change by at least 2.5"
-      def to_s
-        "change by at least #{@expected.inspect}"
-      end
-    end
-  end
-end

data/lib/matchi/change/by_at_most.rb

@@ -1,171 +0,0 @@
-# frozen_string_literal: true
-
-module Matchi
-  class Change
-    # Maximum delta matcher that verifies numeric changes don't exceed a limit.
-    #
-    # This matcher ensures that a numeric value changes by no more than the specified amount
-    # after executing a block of code. It's particularly useful when testing operations
-    # where you want to enforce an upper bound on changes, such as rate limiting,
-    # resource consumption, or controlled increments.
-    #
-    # @example Testing controlled collection growth
-    #   items = []
-    #   matcher = Matchi::Change::ByAtMost.new(2) { items.size }
-    #   matcher.match? { items.push(1) }             # => true   # Changed by less than limit
-    #   matcher.match? { items.push(1, 2) }          # => true   # Changed by exactly limit
-    #   matcher.match? { items.push(1, 2, 3) }       # => false  # Changed by more than limit
-    #
-    # @example Rate limiting
-    #   class RateLimiter
-    #     def initialize
-    #       @requests = 0
-    #     end
-    #
-    #     def process_batch(items)
-    #       items.each do |item|
-    #         break if @requests >= 3  # Rate limit
-    #         process_item(item)
-    #       end
-    #     end
-    #
-    #     private
-    #
-    #     def process_item(item)
-    #       @requests += 1
-    #       # Processing logic...
-    #     end
-    #
-    #     def requests
-    #       @requests
-    #     end
-    #   end
-    #
-    #   limiter = RateLimiter.new
-    #   matcher = Matchi::Change::ByAtMost.new(3) { limiter.requests }
-    #   matcher.match? { limiter.process_batch([1, 2, 3, 4, 5]) } # => true
-    #
-    # @example Resource consumption
-    #   class ResourcePool
-    #     attr_reader :used
-    #
-    #     def initialize
-    #       @used = 0
-    #     end
-    #
-    #     def allocate(requested)
-    #       available = 5 - @used  # Maximum pool size is 5
-    #       granted = [requested, available].min
-    #       @used += granted
-    #       granted
-    #     end
-    #   end
-    #
-    #   pool = ResourcePool.new
-    #   matcher = Matchi::Change::ByAtMost.new(2) { pool.used }
-    #   matcher.match? { pool.allocate(2) }  # => true
-    #   matcher.match? { pool.allocate(3) }  # => false
-    #
-    # @example Score adjustments
-    #   class GameScore
-    #     attr_reader :value
-    #
-    #     def initialize
-    #       @value = 100
-    #     end
-    #
-    #     def apply_penalty(amount)
-    #       max_penalty = 10
-    #       actual_penalty = [amount, max_penalty].min
-    #       @value -= actual_penalty
-    #     end
-    #   end
-    #
-    #   score = GameScore.new
-    #   matcher = Matchi::Change::ByAtMost.new(10) { -score.value }
-    #   matcher.match? { score.apply_penalty(5) }   # => true   # Small penalty
-    #   matcher.match? { score.apply_penalty(15) }  # => true   # Limited to max
-    #
-    # @note This matcher verifies maximum changes only. For exact changes, use By,
-    #   and for minimum changes, use ByAtLeast.
-    #
-    # @see Matchi::Change::By For exact change validation
-    # @see Matchi::Change::ByAtLeast For minimum change validation
-    # @see Matchi::Change::To For final value validation
-    class ByAtMost
-      # Initialize the matcher with a maximum allowed change and a state block.
-      #
-      # @api public
-      #
-      # @param expected [Numeric] The maximum amount by which the value should change
-      # @param state [Proc] Block that retrieves the current value
-      #
-      # @raise [ArgumentError] if expected is not a Numeric
-      # @raise [ArgumentError] if expected is negative
-      # @raise [ArgumentError] if no state block is provided
-      #
-      # @return [ByAtMost] a new instance of the matcher
-      #
-      # @example With integer maximum
-      #   ByAtMost.new(5) { counter.value }
-      #
-      # @example With floating point maximum
-      #   ByAtMost.new(0.5) { temperature.celsius }
-      def initialize(expected, &state)
-        raise ::ArgumentError, "expected must be a Numeric" unless expected.is_a?(::Numeric)
-        raise ::ArgumentError, "a block must be provided" unless block_given?
-        raise ::ArgumentError, "expected must be non-negative" if expected.negative?
-
-        @expected = expected
-        @state = state
-      end
-
-      # Checks if the value changes by no more than the expected amount.
-      #
-      # This method compares the value before and after executing the provided block,
-      # ensuring that the absolute difference is less than or equal to the expected maximum.
-      # This is useful for enforcing upper bounds on state changes.
-      #
-      # @api public
-      #
-      # @yield [] Block that should cause the state change
-      # @yieldreturn [Object] The result of the block (not used)
-      #
-      # @return [Boolean] true if the value changed by at most the expected amount
-      #
-      # @raise [ArgumentError] if no block is provided
-      #
-      # @example Basic usage with growth
-      #   users = []
-      #   matcher = ByAtMost.new(2) { users.size }
-      #   matcher.match? { users.push('alice') }  # => true
-      #
-      # @example With negative changes
-      #   stock = 10
-      #   matcher = ByAtMost.new(3) { stock }
-      #   matcher.match? { stock -= 2 }  # => true
-      def match?
-        raise ::ArgumentError, "a block must be provided" unless block_given?
-
-        value_before = @state.call
-        yield
-        value_after = @state.call
-
-        @expected >= (value_after - value_before)
-      end
-
-      # Returns a human-readable description of the matcher.
-      #
-      # @api public
-      #
-      # @return [String] A string describing what this matcher verifies
-      #
-      # @example
-      #   ByAtMost.new(5).to_s    # => "change by at most 5"
-      #   ByAtMost.new(2.5).to_s  # => "change by at most 2.5"
-      def to_s
-        "change by at most #{@expected.inspect}"
-      end
-    end
-  end
-end