matchi 2.4.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99d5b67cbb65b32a588adc888741aa1b43d86dd26835404388de5444bee6c54c
-  data.tar.gz: 6188812229591bbb66a7fe458eaaaf4cd5707d00cefcc8502dfc3e4ed41195a2
+  metadata.gz: 16b38ee69034c01d5f2961a5d4e14b6c150cad89a9368f7c0cf84071761e2999
+  data.tar.gz: f76f7a3286443d49f6e449af9ffefdb2f38b9d974aada733e1a611d75c627199
 SHA512:
-  metadata.gz: 3f00907f22ba9615eeab7541ddba62e6507f6c3609268699b4c20fda2435c338e9307fec63a942a9c49ad105131c6d29f47354fdf8d7e5d8b28fc418f060e9f0
-  data.tar.gz: 4aeea7b5f52278b733c58180753e95d6ab88a47fbc162242ecf63bcfc3bc44ce018976fa544ef48887724d247e6fcb37ccc6372c89fedb0661d008dcc46061b5
+  metadata.gz: ed8abd4dd002520dc4740fc80b91573098e3242319e74b807e6621482beb131d4a40e299584fc507bacbb806867a00691a3f4bdcebf611dd2c45eb1b90e9e76e
+  data.tar.gz: 3fd0b621816f91d0569fdebeb4a8c80c55890f83250ed87b0df2cd1b7683e02f390df159f372f6e87f62aab853b7d8042d438f1efc31f83fd3b169a12eab2b8e

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
+
+* Provide a collection of useful generic matchers.
+* Adding matchers should be as simple as possible.
+* Being framework agnostic and easy to integrate.
 
 ## Installation
 
@@ -44,115 +50,97 @@ require "matchi"
 
 All examples here assume that this has been done.
 
+### Anatomy of a matcher
+
+A __Matchi__ matcher is just an object that responds to the `matches?` method with a block as argument, and returns a boolean. That's all it is.
+
+But let's see some examples.
+
 ### Built-in matchers
 
 **Equivalence** matcher:
 
 ```ruby
-eql = Matchi::Matcher::Eql.new("foo")
-eql.matches? { "foo" } # => true
+matcher = Matchi::Eq.new("foo")
+matcher.matches? { "foo" } # => true
 ```
 
 **Identity** matcher:
 
 ```ruby
-equal = Matchi::Matcher::Equal.new(:foo)
-equal.matches? { :foo } # => true
+matcher = Matchi::Be.new(:foo)
+matcher.matches? { :foo } # => true
 ```
 
 **Regular expressions** matcher:
 
 ```ruby
-match = Matchi::Matcher::Match.new(/^foo$/)
-match.matches? { "foo" } # => true
+matcher = Matchi::Match.new(/^foo$/)
+matcher.matches? { "foo" } # => true
 ```
 
 **Expecting errors** matcher:
 
 ```ruby
-raise_exception = Matchi::Matcher::RaiseException.new(NameError)
-raise_exception.matches? { Boom } # => true
-```
-
-**Truth** matcher:
-
-```ruby
-be_true = Matchi::Matcher::BeTrue.new
-be_true.matches? { true } # => true
-```
-
-**Untruth** matcher:
-
-```ruby
-be_false = Matchi::Matcher::BeFalse.new
-be_false.matches? { false } # => true
-```
-
-**Nil** matcher:
-
-```ruby
-be_nil = Matchi::Matcher::BeNil.new
-be_nil.matches? { nil } # => true
+matcher = Matchi::RaiseException.new(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.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.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.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.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.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.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.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 matches?
+      42.equal?(yield)
     end
   end
 end
 
-be_the_answer = Matchi::Matcher::BeTheAnswer.new
-be_the_answer.matches? { 42 } # => true
+matcher = Matchi::BeTheAnswer.new
+matcher.matches? { 42 } # => true
 ```
 
 A **Be prime** matcher:
@@ -161,60 +149,36 @@ 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
-
-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:
+  class StartWith
+    attr_reader :expected
 
-```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:
 
-```ruby
-matcher = MatcherCollection.new
-matcher.equal(42).matches? { 44 } # => false
-matcher.be_an_instance_of(:String).matches? { "안녕하세요" } # => true
+matcher = Matchi::StartWith.new("foo")
+matcher.matches? { "foobar" } # => true
 ```
 
 ## Contact
@@ -228,7 +192,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,44 @@
+# frozen_string_literal: true
+
+module Matchi
+  # *Identity* matcher.
+  class Be
+    # 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.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,44 @@
+# frozen_string_literal: true
+
+module Matchi
+  # *Type/class* matcher.
+  class BeAnInstanceOf
+    # Initialize the matcher with (the name of) a class or module.
+    #
+    # @example
+    #   require "matchi/be_an_instance_of"
+    #
+    #   Matchi::BeAnInstanceOf.new(String)
+    #
+    # @param expected [#to_s] A (name of a) class or module.
+    def initialize(expected)
+      @expected = String(expected).to_sym
+    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.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/change.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative File.join("change", "by_at_least")
+require_relative File.join("change", "by_at_most")
+require_relative File.join("change", "by")
+require_relative File.join("change", "from")
+require_relative File.join("change", "to")
+
+module Matchi
+  # Wraps the target of a change matcher.
+  class Change
+    # Initialize a wrapper of the change matcher with an object and the name of
+    # one of its methods.
+    #
+    # @example
+    #   require "matchi/change"
+    #
+    #   Matchi::Change.new("foo", :to_s)
+    #
+    # @param object [#object_id]  An object.
+    # @param method [Symbol]      The name of a method.
+    # @param args   [Array]       A list of arguments.
+    # @param kwargs [Hash]        A list of keyword arguments.
+    def initialize(object, method, *args, **kwargs, &block)
+      @state = -> { object.send(method, *args, **kwargs, &block) }
+    end
+
+    # Specifies a minimum delta of the expected change.
+    #
+    # @example
+    #   require "matchi/change"
+    #
+    #   object = []
+    #
+    #   change = Matchi::Change.new(object, :length)
+    #   change.by_at_least(1)
+    #
+    # @param expected [#object_id] The minimum delta of the expected change.
+    #
+    # @return [#matches?] A *change by at least* matcher.
+    def by_at_least(expected)
+      ByAtLeast.new(expected, &@state)
+    end
+
+    # Specifies a maximum delta of the expected change.
+    #
+    # @example
+    #   require "matchi/change"
+    #
+    #   object = []
+    #
+    #   change = Matchi::Change.new(object, :length)
+    #   change.by_at_most(1)
+    #
+    # @param expected [#object_id] The maximum delta of the expected change.
+    #
+    # @return [#matches?] A *change by at most* matcher.
+    def by_at_most(expected)
+      ByAtMost.new(expected, &@state)
+    end
+
+    # Specifies the delta of the expected change.
+    #
+    # @example
+    #   require "matchi/change"
+    #
+    #   object = []
+    #
+    #   change = Matchi::Change.new(object, :length)
+    #   change.by(1)
+    #
+    # @param expected [#object_id] The delta of the expected change.
+    #
+    # @return [#matches?] A *change by* matcher.
+    def by(expected)
+      By.new(expected, &@state)
+    end
+
+    # Specifies the original value.
+    #
+    # @example
+    #   require "matchi/change"
+    #
+    #   change = Matchi::Change.new("foo", :to_s)
+    #   change.from("foo")
+    #
+    # @param expected [#object_id] The original value.
+    #
+    # @return [#matches?] A *change from* wrapper.
+    def from(expected)
+      From.new(expected, &@state)
+    end
+
+    # Specifies the new value to expect.
+    #
+    # @example
+    #   require "matchi/change"
+    #
+    #   change = Matchi::Change.new("foo", :to_s)
+    #   change.to("FOO")
+    #
+    # @param expected [#object_id] The new value to expect.
+    #
+    # @return [#matches?] A *change to* matcher.
+    def to(expected)
+      To.new(expected, &@state)
+    end
+  end
+end