matchi 2.4.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99d5b67cbb65b32a588adc888741aa1b43d86dd26835404388de5444bee6c54c
-  data.tar.gz: 6188812229591bbb66a7fe458eaaaf4cd5707d00cefcc8502dfc3e4ed41195a2
+  metadata.gz: aabf9e773ac6210d1170b3a0f3aa19f38845ea0215bb07280d97c35ef66add16
+  data.tar.gz: 2900c9b936d50bfbe50ba31c6418dcb1402c1fbef5cfbb9f7a1ce289ff6450c0
 SHA512:
-  metadata.gz: 3f00907f22ba9615eeab7541ddba62e6507f6c3609268699b4c20fda2435c338e9307fec63a942a9c49ad105131c6d29f47354fdf8d7e5d8b28fc418f060e9f0
-  data.tar.gz: 4aeea7b5f52278b733c58180753e95d6ab88a47fbc162242ecf63bcfc3bc44ce018976fa544ef48887724d247e6fcb37ccc6372c89fedb0661d008dcc46061b5
+  metadata.gz: e2cfb5b1c32a01b84c1e2eec84cfc3ad34df2a7a17c91ecb1e6012ef84d5b4ef5b11f24817de7dcea77e08006e72c578d0d88947470436f231efef8fed18f061
+  data.tar.gz: 235a73246185fec310960caf6b8c868cbc2daf7598f29c863def9b560ec66ba7a0f43ab303cd164b04c81b5ebbcbddae3224c5550002f9ab924f8202f58a289f

data/README.md

@@ -6,9 +6,15 @@
 [![RuboCop](https://github.com/fixrb/matchi/workflows/RuboCop/badge.svg?branch=main)](https://github.com/fixrb/matchi/actions?query=workflow%3Arubocop+branch%3Amain)
 [![License](https://img.shields.io/github/license/fixrb/matchi?label=License&logo=github)](https://github.com/fixrb/matchi/raw/main/LICENSE.md)
 
-> Collection of expectation matchers for Ruby 🤹
+> Collection of expectation matchers for Rubyists 🤹
 
-![A rubyist juggling between colored balls representing expectation matchers](https://github.com/fixrb/matchi/raw/main/img/matchi.jpg)
+![A Rubyist juggling between Matchi letters](https://github.com/fixrb/matchi/raw/main/img/matchi.jpg)
+
+## Project goals
+
+* Adding matchers should be as simple as possible.
+* Being framework agnostic and easy to integrate.
+* Avoid false positives/negatives due to malicious actual values.
 
 ## Installation
 
@@ -44,115 +50,136 @@ require "matchi"
 
 All examples here assume that this has been done.
 
+### Anatomy of a matcher
+
+A __Matchi__ matcher is an object that must respond to the `matches?` method with a block as argument, and return a boolean.
+
+To facilitate the integration of the matchers in other tools, __Matchi__ matchers may expose expected values via the `expected` method.
+
 ### Built-in matchers
 
+Here is the collection of useful generic matchers.
+
 **Equivalence** matcher:
 
 ```ruby
-eql = Matchi::Matcher::Eql.new("foo")
-eql.matches? { "foo" } # => true
+matcher = Matchi::Eq.new("foo")
+
+matcher.expected           # => "foo"
+matcher.matches? { "foo" } # => true
 ```
 
 **Identity** matcher:
 
 ```ruby
-equal = Matchi::Matcher::Equal.new(:foo)
-equal.matches? { :foo } # => true
-```
+matcher = Matchi::Be.new(:foo)
 
-**Regular expressions** matcher:
-
-```ruby
-match = Matchi::Matcher::Match.new(/^foo$/)
-match.matches? { "foo" } # => true
+matcher.expected          # => :foo
+matcher.matches? { :foo } # => true
 ```
 
-**Expecting errors** matcher:
+**Comparisons** matcher:
 
 ```ruby
-raise_exception = Matchi::Matcher::RaiseException.new(NameError)
-raise_exception.matches? { Boom } # => true
-```
-
-**Truth** matcher:
+matcher = Matchi::BeWithin.new(8).of(37)
 
-```ruby
-be_true = Matchi::Matcher::BeTrue.new
-be_true.matches? { true } # => true
+matcher.expected        # => 37
+matcher.matches? { 42 } # => true
 ```
 
-**Untruth** matcher:
+**Regular expressions** matcher:
 
 ```ruby
-be_false = Matchi::Matcher::BeFalse.new
-be_false.matches? { false } # => true
+matcher = Matchi::Match.new(/^foo$/)
+
+matcher.expected           # => /^foo$/
+matcher.matches? { "foo" } # => true
 ```
 
-**Nil** matcher:
+**Expecting errors** matcher:
 
 ```ruby
-be_nil = Matchi::Matcher::BeNil.new
-be_nil.matches? { nil } # => true
+matcher = Matchi::RaiseException.new(:NameError)
+
+matcher.expected          # => "NameError"
+matcher.matches? { Boom } # => true
 ```
 
 **Type/class** matcher:
 
 ```ruby
-be_an_instance_of = Matchi::Matcher::BeAnInstanceOf.new(:String)
-be_an_instance_of.matches? { "foo" } # => true
+matcher = Matchi::BeAnInstanceOf.new(:String)
+
+matcher.expected           # => "String"
+matcher.matches? { "foo" } # => true
 ```
 
 **Change** matcher:
 
 ```ruby
 object = []
-change = Matchi::Matcher::Change.new(object, :length).by(1)
-change.matches? { object << 1 } # => true
+matcher = Matchi::Change.new(object, :length).by(1)
+
+matcher.expected                 # => 1
+matcher.matches? { object << 1 } # => true
 
 object = []
-change = Matchi::Matcher::Change.new(object, :length).by_at_least(1)
-change.matches? { object << 1 } # => true
+matcher = Matchi::Change.new(object, :length).by_at_least(1)
+
+matcher.expected                 # => 1
+matcher.matches? { object << 1 } # => true
 
 object = []
-change = Matchi::Matcher::Change.new(object, :length).by_at_most(1)
-change.matches? { object << 1 } # => true
+matcher = Matchi::Change.new(object, :length).by_at_most(1)
+
+matcher.expected                 # => 1
+matcher.matches? { object << 1 } # => true
 
 object = "foo"
-change = Matchi::Matcher::Change.new(object, :to_s).from("foo").to("FOO")
-change.matches? { object.upcase! } # => true
+matcher = Matchi::Change.new(object, :to_s).from("foo").to("FOO")
+
+matcher.expected                    # => "FOO"
+matcher.matches? { object.upcase! } # => true
 
 object = "foo"
-change = Matchi::Matcher::Change.new(object, :to_s).to("FOO")
-change.matches? { object.upcase! } # => true
+matcher = Matchi::Change.new(object, :to_s).to("FOO")
+
+matcher.expected                    # => "FOO"
+matcher.matches? { object.upcase! } # => true
 ```
 
 **Satisfy** matcher:
 
 ```ruby
-satisfy = Matchi::Matcher::Satisfy.new { |value| value == 42 }
-satisfy.matches? { 42 } # => true
+matcher = Matchi::Satisfy.new { |value| value == 42 }
+
+matcher.expected        # => #<Proc:0x00007fbaafc65540>
+matcher.matches? { 42 } # => true
 ```
 
 ### Custom matchers
 
-Custom matchers can easily be defined for expressing expectations.
-They can be any Ruby class that responds to `matches?` instance method with a block.
+Custom matchers can easily be added to express more specific expectations.
 
 A **Be the answer** matcher:
 
 ```ruby
 module Matchi
-  module Matcher
-    class BeTheAnswer < ::Matchi::Matcher::Base
-      def matches?
-        42.equal?(yield)
-      end
+  class BeTheAnswer
+    def expected
+      42
+    end
+
+    def matches?
+      expected.equal?(yield)
     end
   end
 end
 
-be_the_answer = Matchi::Matcher::BeTheAnswer.new
-be_the_answer.matches? { 42 } # => true
+matcher = Matchi::BeTheAnswer.new
+
+matcher.expected        # => 42
+matcher.matches? { 42 } # => true
 ```
 
 A **Be prime** matcher:
@@ -161,60 +188,39 @@ A **Be prime** matcher:
 require "prime"
 
 module Matchi
-  module Matcher
-    class BePrime < ::Matchi::Matcher::Base
-      def matches?
-        Prime.prime?(yield)
-      end
+  class BePrime
+    def matches?
+      Prime.prime?(yield)
     end
   end
 end
 
-be_prime = Matchi::Matcher::BePrime.new
-be_prime.matches? { 42 } # => false
+matcher = Matchi::BePrime.new
+
+matcher.matches? { 42 } # => false
 ```
 
 A **Start with** matcher:
 
 ```ruby
 module Matchi
-  module Matcher
-    class StartWith < ::Matchi::Matcher::Base
-      def initialize(expected)
-        super()
-        @expected = expected
-      end
-
-      def matches?
-        Regexp.new(/\A#{expected}/).match?(yield)
-      end
-    end
-  end
-end
+  class StartWith
+    attr_reader :expected
 
-start_with = Matchi::Matcher::StartWith.new("foo")
-start_with.matches? { "foobar" } # => true
-```
-
-### Helper methods
-
-For convenience, it is possible to instantiate a matcher with a method rather than with its class.
-To do so, the `Helper` module can be included like this:
-
-```ruby
-require "matchi/helper"
+    def initialize(expected)
+      @expected = expected
+    end
 
-class MatcherCollection
-  include ::Matchi::Helper
+    def matches?
+      Regexp.new(/\A#{expected}/).match?(yield)
+    end
+  end
 end
-```
 
-The set of loaded matcher then becomes accessible via a dynamically generated instance method, like these:
+matcher = Matchi::StartWith.new("foo")
 
-```ruby
-matcher = MatcherCollection.new
-matcher.equal(42).matches? { 44 } # => false
-matcher.be_an_instance_of(:String).matches? { "안녕하세요" } # => true
+matcher.expected              # => "foo"
+matcher.matches? { "foobar" } # => true
 ```
 
 ## Contact
@@ -228,7 +234,7 @@ __Matchi__ follows [Semantic Versioning 2.0](https://semver.org/).
 
 ## License
 
-The [gem](https://rubygems.org/gems/matchi) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The [gem](https://rubygems.org/gems/matchi) is available as open source under the terms of the [MIT License](https://github.com/fixrb/matchi/raw/main/LICENSE.md).
 
 ***
 

data/lib/matchi.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-# Namespace for the Matchi library.
+# A collection of damn simple expectation matchers.
 #
 # @api public
 module Matchi
 end
 
-require_relative File.join("matchi", "matcher")
+Dir[File.join(File.dirname(__FILE__), "matchi", "*.rb")].each do |fname|
+  require_relative fname
+end

data/lib/matchi/be.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Matchi
+  # *Identity* matcher.
+  class Be
+    # @return [#equal?] The expected identical object.
+    attr_reader :expected
+
+    # Initialize the matcher with an object.
+    #
+    # @example
+    #   require "matchi/be"
+    #
+    #   Matchi::Be.new(:foo)
+    #
+    # @param expected [#equal?] The expected identical object.
+    def initialize(expected)
+      @expected = expected
+    end
+
+    # Boolean comparison between the actual value and the expected value.
+    #
+    # @example
+    #   require "matchi/be"
+    #
+    #   matcher = Matchi::Be.new(:foo)
+    #
+    #   matcher.expected          # => :foo
+    #   matcher.matches? { :foo } # => true
+    #
+    # @yieldreturn [#object_id] The actual value to compare to the expected
+    #   one.
+    #
+    # @return [Boolean] Comparison between actual and expected values.
+    def matches?
+      expected.equal?(yield)
+    end
+
+    # A string containing a human-readable representation of the matcher.
+    def inspect
+      "#{self.class}(#{expected.inspect})"
+    end
+
+    # Returns a string representing the matcher.
+    def to_s
+      "be #{expected.inspect}"
+    end
+  end
+end

data/lib/matchi/be_an_instance_of.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Matchi
+  # *Type/class* matcher.
+  class BeAnInstanceOf
+    # @return [String] The expected class name.
+    attr_reader :expected
+
+    # Initialize the matcher with (the name of) a class or module.
+    #
+    # @example
+    #   require "matchi/be_an_instance_of"
+    #
+    #   Matchi::BeAnInstanceOf.new(String)
+    #
+    # @param expected [Class, #to_s] The expected class name.
+    def initialize(expected)
+      @expected = String(expected)
+    end
+
+    # Boolean comparison between the class of the actual value and the
+    # expected class.
+    #
+    # @example
+    #   require "matchi/be_an_instance_of"
+    #
+    #   matcher = Matchi::BeAnInstanceOf.new(String)
+    #
+    #   matcher.expected           # => "String"
+    #   matcher.matches? { "foo" } # => true
+    #
+    # @yieldreturn [#class] the actual value to compare to the expected one.
+    #
+    # @return [Boolean] Comparison between actual and expected values.
+    def matches?
+      self.class.const_get(expected).equal?(yield.class)
+    end
+
+    # A string containing a human-readable representation of the matcher.
+    def inspect
+      "#{self.class}(#{expected})"
+    end
+
+    # Returns a string representing the matcher.
+    def to_s
+      "be an instance of #{expected}"
+    end
+  end
+end

data/lib/matchi/be_within.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative File.join("be_within", "of")
+
+module Matchi
+  # Wraps the target of a be_within matcher.
+  class BeWithin
+    # Initialize a wrapper of the be_within matcher with a numeric value.
+    #
+    # @example
+    #   require "matchi/be_within"
+    #
+    #   Matchi::BeWithin.new(1)
+    #
+    # @param delta [Numeric] A numeric value.
+    def initialize(delta)
+      @delta = delta
+    end
+
+    # Specifies an expected numeric value.
+    #
+    # @example
+    #   require "matchi/be_within"
+    #
+    #   be_within_wrapper = Matchi::BeWithin.new(1)
+    #   be_within_wrapper.of(41)
+    #
+    # @param expected [Numeric] The expected value.
+    #
+    # @return [#matches?] A *be_within of* matcher.
+    def of(expected)
+      Of.new(@delta, expected)
+    end
+  end
+end