matchi 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8454c54085d68ded31ba34e1ff0ab03cdc3dab452316ef82a15967f3de3ee4c
-  data.tar.gz: ac11c5ab16b7e93f16189b1fa62f0d0502e0d94e67627f81dfab40cd7db48d61
+  metadata.gz: 730c0baf16a64842af123077150d70aee64e664ef6d5626dadf4730c1ee3425d
+  data.tar.gz: a934654b282119e28d4fb5c4079298770f86a834d58621240737f2473f067500
 SHA512:
-  metadata.gz: b984f3a46f4eb2f0743b4407518261ca0539efd780b28ab0b0f476a687925bedeec2d88249160d7c148617809080593d9472957dc8571bf92295007dfaf941b7
-  data.tar.gz: 96f609b1bc8af4ddf6a5b7b839ed0b981018d7aac53f1d26b5ea05c1629318f3cdbef64e9776dd2224c3fdd48b56e148e8e3a94df4de5d07e93164941da0fa25
+  metadata.gz: 75884ba2533b155d3f1e4490f9b8f6071a95aad0fca637dcdb0eee2bf60e1a3dc6bd7cab35ab93a3a7c18b680b9d789ee71bfbd7d524e6ca5ea8573520a3deec
+  data.tar.gz: d421e42619fc45d1f1aab95ccde2a24d6a1226f4163a4afbde02fc8e693343997fa5a9a0081d72734955b2b6a25b3f9f735766702860d2184c44f403e169f442

data/README.md

@@ -63,6 +63,67 @@ A **Matchi** matcher is a simple Ruby object that follows these requirements:
 2. Optionally, it may implement:
    - `to_s`: Returns a human-readable description of the match criteria
 
+### Using Matchers
+
+There are two main ways to use Matchi matchers:
+
+#### 1. Direct Class Instantiation
+
+You can create matchers directly from their classes:
+
+```ruby
+matcher = Matchi::Eq.new("foo")
+matcher.match? { "foo" } # => true
+
+matcher = Matchi::BeWithin.new(0.5).of(3.0)
+matcher.match? { 3.2 } # => true
+```
+
+#### 2. Helper Methods via Module Inclusion
+
+For a more expressive and readable syntax, you can include or extend the `Matchi` module to get access to helper methods:
+
+```ruby
+# Including in a class for instance methods
+class MyTestFramework
+  include Matchi
+
+  def test_equality
+    # Helper methods available as instance methods
+    matcher = eq("foo")
+    assert(matcher.match? { "foo" })
+
+    # Method chaining works too
+    assert(change(@array, :length).by(1).match? { @array << 1 })
+  end
+end
+
+# Extending a class for class methods
+class MyAssertions
+  extend Matchi
+
+  def self.assert_equals(expected, actual)
+    eq(expected).match? { actual }
+  end
+
+  def self.assert_within_range(expected, delta, actual)
+    be_within(delta).of(expected).match? { actual }
+  end
+end
+```
+
+Available helper methods correspond to the built-in matchers:
+- `eq` / `eql` - For equivalence matching
+- `be` / `equal` - For identity matching
+- `be_within` - For delta comparisons
+- `match` - For regular expression matching
+- `change` - For state changes
+- `be_true`, `be_false`, `be_nil` - For state verification
+- `be_an_instance_of` - For exact type matching
+- `be_a_kind_of` - For type hierarchy matching
+- `satisfy` - For custom block-based matching
+- Dynamic predicate matchers (`be_*` and `have_*`)
+
 ### Built-in matchers
 
 Here is the collection of generic matchers.
@@ -72,15 +133,15 @@ Here is the collection of generic matchers.
 ##### `Be`
 Checks for object identity using Ruby's `equal?` method.
 ```ruby
-Matchi::Be.new(:foo).match? { :foo }  # => true (same object)
-Matchi::Be.new("test").match? { "test" }  # => false (different objects)
+Matchi::Be.new(:foo).match? { :foo } # => true (same object)
+Matchi::Be.new("test").match? { "test" } # => false (different objects)
 ```
 
 ##### `Eq`
 Verifies object equivalence using Ruby's `eql?` method.
 ```ruby
-Matchi::Eq.new("foo").match? { "foo" }  # => true (equivalent content)
-Matchi::Eq.new([1, 2]).match? { [1, 2] }  # => true (equivalent arrays)
+Matchi::Eq.new("foo").match? { "foo" } # => true (equivalent content)
+Matchi::Eq.new([1, 2]).match? { [1, 2] } # => true (equivalent arrays)
 ```
 
 #### Type and Class Matchers
@@ -113,8 +174,8 @@ Matchi::Match.new(/^foo/).match? { "barfoo" }  # => false
 ##### `Satisfy`
 Provides custom matching through a block.
 ```ruby
-Matchi::Satisfy.new { |x| x > 0 && x < 10 }.match? { 5 }  # => true
-Matchi::Satisfy.new { |x| x.start_with?("test") }.match? { "test_file" }  # => true
+Matchi::Satisfy.new { |x| x.positive? && x < 10 }.match? { 5 } # => true
+Matchi::Satisfy.new { |x| x.start_with?("test") }.match? { "test_file" } # => true
 ```
 
 #### State Change Matchers
@@ -125,31 +186,31 @@ Verifies state changes in objects with multiple variation methods:
 ###### Basic Change
 ```ruby
 array = []
-Matchi::Change.new(array, :length).by(2).match? { array.push(1, 2) }  # => true
+Matchi::Change.new(array, :length).by(2).match? { array.push(1, 2) } # => true
 ```
 
 ###### Minimum Change
 ```ruby
 counter = 0
-Matchi::Change.new(counter, :to_i).by_at_least(2).match? { counter += 3 }  # => true
+Matchi::Change.new(counter, :to_i).by_at_least(2).match? { counter += 3 } # => true
 ```
 
 ###### Maximum Change
 ```ruby
 value = 10
-Matchi::Change.new(value, :to_i).by_at_most(5).match? { value += 3 }  # => true
+Matchi::Change.new(value, :to_i).by_at_most(5).match? { value += 3 } # => true
 ```
 
 ###### From-To Change
 ```ruby
 string = "hello"
-Matchi::Change.new(string, :upcase).from("hello").to("HELLO").match? { string.upcase! }  # => true
+Matchi::Change.new(string, :upcase).from("hello").to("HELLO").match? { string.upcase! } # => true
 ```
 
 ###### To-Only Change
 ```ruby
 number = 1
-Matchi::Change.new(number, :to_i).to(5).match? { number = 5 }  # => true
+Matchi::Change.new(number, :to_i).to(5).match? { number = 5 } # => true
 ```
 
 #### Numeric Matchers
@@ -166,8 +227,8 @@ Matchi::BeWithin.new(5).of(100).match? { 98 }     # => true
 ##### `RaiseException`
 Verifies that code raises specific exceptions.
 ```ruby
-Matchi::RaiseException.new(ArgumentError).match? { raise ArgumentError }  # => true
-Matchi::RaiseException.new(NameError).match? { undefined_variable }      # => true
+Matchi::RaiseException.new(ArgumentError).match? { raise ArgumentError } # => true
+Matchi::RaiseException.new(NameError).match? { undefined_variable } # => true
 ```
 
 ##### `Predicate`
@@ -181,7 +242,7 @@ Matchi::Predicate.new(:be_nil).match? { nil }   # => true (calls nil?)
 
 ###### Using `have_` prefix
 ```ruby
-Matchi::Predicate.new(:have_key, :foo).match? { { foo: 42 } }  # => true (calls has_key?)
+Matchi::Predicate.new(:have_key, :foo).match? { { foo: 42 } } # => true (calls has_key?)
 ```
 
 ### Custom matchers
@@ -288,7 +349,7 @@ This is why Matchi's built-in matchers are implemented with this security consid
 ```ruby
 # Implementation in Matchi::Eq
 def match?
-  @expected.eql?(yield)  # Expected value controls the comparison
+  @expected.eql?(yield) # Expected value controls the comparison
 end
 ```
 

data/lib/matchi.rb

@@ -2,8 +2,308 @@
 
 # A collection of damn simple expectation matchers.
 #
+# The Matchi module provides two ways to create and use matchers:
+#
+# 1. Direct instantiation through classes:
+#    ```ruby
+#    matcher = Matchi::Eq.new("foo")
+#    matcher.match? { "foo" } # => true
+#    ```
+#
+# 2. Helper methods by including/extending the Matchi module:
+#    ```ruby
+#    # Via include in a class
+#    class MyTestFramework
+#      include Matchi
+#
+#      def test_something
+#        # Helpers are now available as instance methods
+#        matcher = eq("foo")
+#        matcher.match? { "foo" } # => true
+#
+#        # Multiple helpers can be chained
+#        change(@array, :length).by(1).match? { @array << 1 }
+#      end
+#    end
+#
+#    # Or via extend for direct usage
+#    class MyOtherFramework
+#      extend Matchi
+#
+#      def self.assert_equals(expected, actual)
+#        eq(expected).match? { actual }
+#      end
+#    end
+#    ```
+#
+# The helper method approach provides a more readable and fluent interface,
+# making tests easier to write and understand. It's particularly useful when
+# integrating with testing frameworks or creating custom assertions.
+#
+# Available helpers include:
+#   - eq/eql    : Equivalence matching
+#   - be/equal  : Identity matching
+#   - be_within : Delta comparison
+#   - match     : Regular expression matching
+#   - change    : State change verification
+#   - be_true/be_false/be_nil : State verification
+#   - be_an_instance_of : Exact type matching
+#   - be_a_kind_of     : Type hierarchy matching
+#   - satisfy   : Custom block-based matching
+#   - be_* & have_* : Dynamic predicate matching
+#
 # @api public
 module Matchi
+  # Equivalence matcher
+  #
+  # @example
+  #   matcher = eq("foo")
+  #   matcher.match? { "foo" } # => true
+  #   matcher.match? { "bar" } # => false
+  #
+  # @param expected [#eql?] An expected equivalent object.
+  #
+  # @return [#match?] An equivalence matcher.
+  #
+  # @api public
+  def eq(expected)
+    ::Matchi::Eq.new(expected)
+  end
+
+  alias eql eq
+
+  # Identity matcher
+  #
+  # @example
+  #   object = "foo"
+  #   matcher = be(object)
+  #   matcher.match? { object } # => true
+  #   matcher.match? { "foo" } # => false
+  #
+  # @param expected [#equal?] The expected identical object.
+  #
+  # @return [#match?] An identity matcher.
+  #
+  # @api public
+  def be(expected)
+    ::Matchi::Be.new(expected)
+  end
+
+  alias equal be
+
+  # Comparisons matcher
+  #
+  # @example
+  #   matcher = be_within(1).of(41)
+  #   matcher.match? { 42 } # => true
+  #   matcher.match? { 43 } # => false
+  #
+  # @param delta [Numeric] A numeric value.
+  #
+  # @return [#match?] A comparison matcher.
+  #
+  # @api public
+  def be_within(delta)
+    ::Matchi::BeWithin.new(delta)
+  end
+
+  # Regular expressions matcher
+  #
+  # @example
+  #   matcher = match(/^foo$/)
+  #   matcher.match? { "foo" } # => true
+  #   matcher.match? { "bar" } # => false
+  #
+  # @param expected [#match] A regular expression.
+  #
+  # @return [#match?] A regular expression matcher.
+  #
+  # @api public
+  def match(expected)
+    ::Matchi::Match.new(expected)
+  end
+
+  # Expecting errors matcher
+  #
+  # @example
+  #   matcher = raise_exception(NameError)
+  #   matcher.match? { Boom } # => true
+  #   matcher.match? { true } # => false
+  #
+  # @param expected [Exception, #to_s] The expected exception name.
+  #
+  # @return [#match?] An error matcher.
+  #
+  # @api public
+  def raise_exception(expected)
+    ::Matchi::RaiseException.new(expected)
+  end
+
+  # True matcher
+  #
+  # @example
+  #   matcher = be_true
+  #   matcher.match? { true } # => true
+  #   matcher.match? { false } # => false
+  #   matcher.match? { nil } # => false
+  #   matcher.match? { 4 } # => false
+  #
+  # @return [#match?] A `true` matcher.
+  #
+  # @api public
+  def be_true
+    be(true)
+  end
+
+  # False matcher
+  #
+  # @example
+  #   matcher = be_false
+  #   matcher.match? { false } # => true
+  #   matcher.match? { true } # => false
+  #   matcher.match? { nil } # => false
+  #   matcher.match? { 4 } # => false
+  #
+  # @return [#match?] A `false` matcher.
+  #
+  # @api public
+  def be_false
+    be(false)
+  end
+
+  # Nil matcher
+  #
+  # @example
+  #   matcher = be_nil
+  #   matcher.match? { nil } # => true
+  #   matcher.match? { false } # => false
+  #   matcher.match? { true } # => false
+  #   matcher.match? { 4 } # => false
+  #
+  # @return [#match?] A `nil` matcher.
+  #
+  # @api public
+  def be_nil
+    be(nil)
+  end
+
+  # Type/class matcher
+  #
+  # Verifies exact class matching (no inheritance).
+  #
+  # @example
+  #   matcher = be_an_instance_of(String)
+  #   matcher.match? { "foo" }  # => true
+  #   matcher.match? { 4 }      # => false
+  #
+  # @param expected [Class, #to_s] The expected class name.
+  #
+  # @return [#match?] A type/class matcher.
+  #
+  # @api public
+  def be_an_instance_of(expected)
+    ::Matchi::BeAnInstanceOf.new(expected)
+  end
+
+  # Type/class matcher
+  #
+  # Verifies class inheritance and module inclusion.
+  #
+  # @example
+  #   matcher = be_a_kind_of(Numeric)
+  #   matcher.match? { 42 }   # => true (Integer inherits from Numeric)
+  #   matcher.match? { 42.0 } # => true (Float inherits from Numeric)
+  #
+  # @param expected [Class, #to_s] The expected class name.
+  #
+  # @return [#match?] A type/class matcher.
+  #
+  # @api public
+  def be_a_kind_of(expected)
+    ::Matchi::BeAKindOf.new(expected)
+  end
+
+  # Change matcher
+  #
+  # @example
+  #   object = []
+  #   matcher = change(object, :length).by(1)
+  #   matcher.match? { object << 1 } # => true
+  #
+  #   object = []
+  #   matcher = change(object, :length).by_at_least(1)
+  #   matcher.match? { object << 1 } # => true
+  #
+  #   object = []
+  #   matcher = change(object, :length).by_at_most(1)
+  #   matcher.match? { object << 1 } # => true
+  #
+  #   object = "foo"
+  #   matcher = change(object, :to_s).from("foo").to("FOO")
+  #   matcher.match? { object.upcase! } # => true
+  #
+  #   object = "foo"
+  #   matcher = change(object, :to_s).to("FOO")
+  #   matcher.match? { object.upcase! } # => true
+  #
+  # @param object [#object_id]  An object.
+  # @param method [Symbol]      The name of a method.
+  #
+  # @return [#match?] A change matcher.
+  #
+  # @api public
+  def change(object, method, ...)
+    ::Matchi::Change.new(object, method, ...)
+  end
+
+  # Satisfy matcher
+  #
+  # @example
+  #   matcher = satisfy { |value| value == 42 }
+  #   matcher.match? { 42 } # => true
+  #
+  # @yield [value] A block that defines the satisfaction criteria
+  # @yieldparam value The value to test
+  # @yieldreturn [Boolean] true if the value satisfies the criteria
+  #
+  # @return [#match?] A satisfy matcher.
+  #
+  # @api public
+  def satisfy(&)
+    ::Matchi::Satisfy.new(&)
+  end
+
+  private
+
+  # Predicate matcher, or default method missing behavior.
+  #
+  # @example Empty predicate matcher
+  #   matcher = be_empty
+  #   matcher.match? { [] } # => true
+  #   matcher.match? { [4] } # => false
+  def method_missing(name, ...)
+    return super unless predicate_matcher_name?(name)
+
+    ::Matchi::Predicate.new(name, ...)
+  end
+
+  # :nocov:
+
+  # Hook method to return whether the obj can respond to id method or not.
+  def respond_to_missing?(name, include_private = false)
+    predicate_matcher_name?(name) || super
+  end
+
+  # :nocov:
+
+  # Predicate matcher name detector.
+  #
+  # @param name [Array, Symbol] The name of a potential predicate matcher.
+  #
+  # @return [Boolean] Indicates if it is a predicate matcher name or not.
+  def predicate_matcher_name?(name)
+    name.start_with?("be_", "have_") && !name.end_with?("!", "?")
+  end
 end
 
 Dir[File.join(File.dirname(__FILE__), "matchi", "*.rb")].each do |fname|

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: matchi
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Cyril Kato
 bindir: bin
 cert_chain: []
-date: 2024-12-29 00:00:00.000000000 Z
+date: 2024-12-31 00:00:00.000000000 Z
 dependencies: []
 description: "Collection of expectation matchers for Rubyists \U0001F939"
 email: contact@cyril.email