matchi 2.1.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c15a21ea2bcdc3ea9c43344bb1ff12216a384bc3d19a996c39a1138c28d18150
-  data.tar.gz: d023d2472ced57399fd14aea2a35cd36b75f7a9ac3705efd48985ccc03a6b9df
+  metadata.gz: 96a52462a574281d4d485558a112fec5cef2e00f1fb90c13987407c18302887c
+  data.tar.gz: 00511b2878ebc9bbe2deb07f888944c9b2e2f2cebf9d8a78d1fe40e1a2b923c7
 SHA512:
-  metadata.gz: be27946a8a1aa3d24b978603be5efc2ce29eea9a18455dba435276329388fd1448c8e0f770b649ca34ad0cfce711a4b34939d665254741406f4bfa7602342475
-  data.tar.gz: dcdf2ece3a08c3dd266a9f01ebcb76013f3ab6e699b2bb8205656f7e3cd3ba76f786921c68516efc940404e72862a0bd5df9a021bb8c0c0b80720048e2738cc8
+  metadata.gz: d368cf94df8ebbfe50b7d5ffd521653853096cd7c36c1c23093916899d0f2524ccf3f3526495cc37e043af571b0df68652c406e7effb033c8d2e92c661dd2b4a
+  data.tar.gz: 5646d8c021cc964041af44412aefab04cc27ebbaa51ddf381b81b43577f233be8f4621735000f1ef7b63e759d80cf51e67c8c802ace3634e2174f72ee8b4ab9f

data/README.md

@@ -1,12 +1,15 @@
 # Matchi
 
-[![Build Status](https://api.travis-ci.org/fixrb/matchi.svg?branch=main)][travis]
-[![Code Climate](https://codeclimate.com/github/fixrb/matchi/badges/gpa.svg)][codeclimate]
-[![Gem Version](https://badge.fury.io/rb/matchi.svg)][gem]
-[![Documentation](https://img.shields.io/:yard-docs-38c800.svg)][rubydoc]
+[![Version](https://img.shields.io/github/v/tag/fixrb/matchi?label=Version&logo=github)](https://github.com/fixrb/matchi/releases)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/fixrb/matchi/main)
+[![CI](https://github.com/fixrb/matchi/workflows/CI/badge.svg?branch=main)](https://github.com/fixrb/matchi/actions?query=workflow%3Aci+branch%3Amain)
+[![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 🤹
 
+![A rubyist juggling between colored balls representing expectation matchers](https://github.com/fixrb/matchi/raw/main/img/matchi.jpg)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -27,8 +30,20 @@ Or install it yourself as:
 gem install matchi
 ```
 
+## Overview
+
+__Matchi__ provides a collection of damn simple expectation matchers.
+
 ## Usage
 
+To make __Matchi__ available:
+
+```ruby
+require "matchi"
+```
+
+All examples here assume that this has been done.
+
 ### Built-in matchers
 
 **Equivalence** matcher:
@@ -83,13 +98,21 @@ be_nil.matches? { nil } # => true
 **Type/class** matcher:
 
 ```ruby
-be_an_instance_of = Matchi::Matcher::BeAnInstanceOf.new(String)
+be_an_instance_of = Matchi::Matcher::BeAnInstanceOf.new(:String)
 be_an_instance_of.matches? { "foo" } # => true
 ```
 
+**Satisfy** matcher:
+
+```ruby
+satisfy = Matchi::Matcher::Satisfy.new { |value| value == 42 }
+satisfy.matches? { 42 } # => true
+```
+
 ### Custom matchers
 
-Custom matchers can easily be defined for expressing expectations.  They can be any Ruby class that responds to `matches?`, `to_s` and `to_h` instance methods.
+Custom matchers can easily be defined for expressing expectations.
+They can be any Ruby class that responds to `matches?` instance method with a block.
 
 A **Be the answer** matcher:
 
@@ -149,6 +172,27 @@ 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"
+
+class MatcherCollection
+  include ::Matchi::Helper
+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
+```
+
 ## Contact
 
 * Home page: https://github.com/fixrb/matchi
@@ -170,8 +214,3 @@ The [gem](https://rubygems.org/gems/matchi) is available as open source under th
     src="https://github.com/fixrb/matchi/raw/main/img/sashite.png"
     alt="Sashite" /></a>
 </p>
-
-[gem]: https://rubygems.org/gems/matchi
-[travis]: https://travis-ci.org/fixrb/matchi
-[codeclimate]: https://codeclimate.com/github/fixrb/matchi
-[rubydoc]: https://rubydoc.info/gems/matchi/frames

data/lib/matchi.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 # Namespace for the Matchi library.
+#
+# @api public
 module Matchi
 end
 

data/lib/matchi/helper.rb

@@ -3,23 +3,35 @@
 require_relative "matcher"
 
 module Matchi
-  # Collection of helper methods.
+  # When included, this module defines a helper instance method per matcher.
+  #
+  # @example Define and use the dynamic helper instance method of a custom matcher
+  #   require "matchi/matcher/base"
+  #
+  #   module Matchi
+  #     module Matcher
+  #       class BeTheAnswer < ::Matchi::Matcher::Base
+  #         def matches?
+  #           42.equal?(yield)
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  #   require "matchi/helper"
+  #
+  #   class MatcherBase
+  #     include ::Matchi::Helper
+  #   end
+  #
+  #   matcher_base = MatcherBase.new
+  #   matcher_base.be_the_answer.matches? { 42 } # => true
   module Helper
     ::Matchi::Matcher.constants.each do |matcher_const|
       next if matcher_const.equal?(:Base)
 
       matcher_klass = ::Matchi::Matcher.const_get(matcher_const)
 
-      # Define a method for the given matcher.
-      #
-      # @example Given the `Matchi::Matchers::Equal::Matcher` matcher, its
-      #   method would be:
-      #
-      #   def equal(expected)
-      #     Matchi::Matchers::Equal::Matcher.new(expected)
-      #   end
-      #
-      # @return [#matches?] The matcher.
       define_method(matcher_klass.to_sym) do |*args|
         matcher_klass.new(*args)
       end

data/lib/matchi/matcher/base.rb

@@ -4,9 +4,16 @@ module Matchi
   module Matcher
     # Abstract matcher class.
     class Base
+      # Returns a symbol identifying the matcher.
+      #
+      # @example The readable definition of a FooBar matcher class.
+      #   matcher_class = Matchi::Matcher::FooBar
+      #   matcher_class.to_sym # => "foo_bar"
+      #
       # @return [Symbol] A symbol identifying the matcher.
       def self.to_sym
-        name.delete_prefix("Matchi::Matcher::")
+        name.split("::")
+            .fetch(-1)
             .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
             .gsub(/([a-z\d])([A-Z])/, '\1_\2')
             .downcase
@@ -18,6 +25,10 @@ module Matchi
 
       # A string containing a human-readable representation of the matcher.
       #
+      # @example The human-readable representation of a FooBar matcher instance.
+      #   matcher = Matchi::Matcher::FooBar.new(42)
+      #   matcher.inspect # => "Matchi::Matcher::FooBar(42)"
+      #
       # @return [String] The human-readable representation of the matcher.
       def inspect
         "#{self.class}(#{expected&.inspect})"
@@ -25,18 +36,25 @@ module Matchi
 
       # Abstract matcher class.
       #
-      # @raise [NotImplementedError] Override me inside a matcher.
+      # @example Test the equivalence between two "foo" strings.
+      #   eql = Matchi::Matcher::Eql.new("foo")
+      #   eql.matches? { "foo" } # => true
+      #
+      # @yieldreturn [#object_id] The actual value to compare to the expected
+      #   one.
+      #
+      # @raise [NotImplementedError] Override this method inside a matcher.
       def matches?
         raise ::NotImplementedError, "matcher MUST respond to this method."
       end
 
-      # Returns a string representing the matcher.
+      # Returns a string representing the matcher instance.
       #
-      # @example The readable definition of a FooBar matcher.
+      # @example The readable definition of a FooBar matcher instance.
       #   matcher = Matchi::Matcher::FooBar.new(42)
       #   matcher.to_s # => "foo_bar 42"
       #
-      # @return [String] A string representing the matcher.
+      # @return [String] A string representing the matcher instance.
       def to_s
         [self.class.to_sym, expected&.inspect].compact.join(" ")
       end

data/lib/matchi/matcher/be_an_instance_of.rb

@@ -8,13 +8,18 @@ module Matchi
     class BeAnInstanceOf < ::Matchi::Matcher::Base
       # Initialize the matcher with an object.
       #
-      # @example A string matcher
-      #   Matchi::Matcher::BeAnInstanceOf.new(String)
+      # @example A duck matcher
+      #   Matchi::Matcher::BeAnInstanceOf.new(:Duck)
       #
-      # @param expected [Class] An expected class.
+      # @param expected [#to_s] The name of a module.
       def initialize(expected)
         super()
-        @expected = expected
+        @expected = String(expected).to_sym
+      end
+
+      # (see Base#inspect)
+      def inspect
+        "#{self.class}(#{expected})"
       end
 
       # Boolean comparison between the class of the actual value and the
@@ -24,11 +29,22 @@ module Matchi
       #   be_an_instance_of = Matchi::Matcher::BeInstanceOf.new(String)
       #   be_an_instance_of.matches? { "foo" } # => true
       #
+      #   be_an_instance_of = Matchi::Matcher::BeInstanceOf.new(:String)
+      #   be_an_instance_of.matches? { "foo" } # => true
+      #
+      #   be_an_instance_of = Matchi::Matcher::BeInstanceOf.new("String")
+      #   be_an_instance_of.matches? { "foo" } # => true
+      #
       # @yieldreturn [#class] the actual value to compare to the expected one.
       #
       # @return [Boolean] Comparison between actual and expected values.
       def matches?(*, **)
-        expected.equal?(yield.class)
+        self.class.const_get(expected).equal?(yield.class)
+      end
+
+      # (see Base#to_s)
+      def to_s
+        "#{self.class.to_sym} #{expected}"
       end
     end
   end

data/lib/matchi/matcher/eql.rb

@@ -8,8 +8,8 @@ module Matchi
     class Eql < ::Matchi::Matcher::Base
       # Initialize the matcher with an object.
       #
-      # @example The string 'foo' matcher.
-      #   Matchi::Matcher::Eql.new('foo')
+      # @example The string "foo" matcher.
+      #   Matchi::Matcher::Eql.new("foo")
       #
       # @param expected [#eql?] An expected equivalent object.
       def initialize(expected)
@@ -19,9 +19,9 @@ module Matchi
 
       # Boolean comparison between the actual value and the expected value.
       #
-      # @example Is it equivalent to 'foo'?
-      #   eql = Matchi::Matcher::Eql.new('foo')
-      #   eql.matches? { 'foo' } # => true
+      # @example Is it equivalent to "foo"?
+      #   eql = Matchi::Matcher::Eql.new("foo")
+      #   eql.matches? { "foo" } # => true
       #
       # @yieldreturn [#object_id] The actual value to compare to the expected
       #   one.

data/lib/matchi/matcher/match.rb

@@ -21,7 +21,7 @@ module Matchi
       #
       # @example Is it matching /^foo$/ regex?
       #   match = Matchi::Matcher::Match.new(/^foo$/)
-      #   match.matches? { 'foo' } # => true
+      #   match.matches? { "foo" } # => true
       #
       # @yieldreturn [#object_id] The actual value to compare to the expected
       #   one.

data/lib/matchi/matcher/satisfy.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Matchi
+  module Matcher
+    # *Satisfy* matcher.
+    class Satisfy < ::Matchi::Matcher::Base
+      # Initialize the matcher with a block.
+      #
+      # @example The number 42 matcher.
+      #   Matchi::Matcher::Satisfy.new { |value| value == 42 }
+      #
+      # @param block [Proc] A block of code.
+      def initialize(&block)
+        super()
+        @expected = block
+      end
+
+      # (see Base#inspect)
+      def inspect
+        "#{self.class}(&block)"
+      end
+
+      # Boolean comparison between the actual value and the expected value.
+      #
+      # @example Is it equal to 42
+      #   equal = Matchi::Matcher::Satisfy.new { |value| value == 42 }
+      #   equal.matches? { 42 } # => true
+      #
+      # @yieldreturn [#object_id] The actual value to compare to the expected
+      #   one.
+      #
+      # @return [Boolean] Comparison between actual and expected values.
+      def matches?(*, **)
+        expected.call(yield)
+      end
+
+      # (see Base#to_s)
+      def to_s
+        "#{self.class.to_sym} &block"
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: matchi
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-16 00:00:00.000000000 Z
+date: 2021-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -142,6 +142,7 @@ files:
 - lib/matchi/matcher/equal.rb
 - lib/matchi/matcher/match.rb
 - lib/matchi/matcher/raise_exception.rb
+- lib/matchi/matcher/satisfy.rb
 homepage: https://github.com/fixrb/matchi
 licenses:
 - MIT