matchi 3.1.1 → 3.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 294443e7f304a5c154aa48af9c20145bba9ff2caaf090bb7336c9bb7538be19d
-  data.tar.gz: c89f84d45eaf0923a7a023bd11b9cf54830054a178ce93e1074aea63cb7a9658
+  metadata.gz: 1b329fa6d8f4acd083fa33dc5a875ab30d521ad598a9a98d87e2e9fa0f3a4ea9
+  data.tar.gz: 122df6c5b532ae6ce316108ac76b32b5528dde249318c45272793df55a6bf240
 SHA512:
-  metadata.gz: 9fe569142636d1acbba97f47dc7efbe38da3c02e9b19e77ab7ad723b6c03a52c03c3d8cd730a9948b4c45b21cdb6e807c29c181fd5d27f77aeee11c92c9738f4
-  data.tar.gz: 2bd24bb8f545496e7bbb115f9bd1577f60d03e67198a0452cd2393f977f063ac0e168f699930c6819a0c478a9c208627db75f7c49a63e5f5905256ba0ef3c8ca
+  metadata.gz: 61dc6797282ee0c2643e57a259b45d0f3b857cc0c725bd55adc1de4fddce61d7822bb25a6dc5bfac30b160c1130a7f76d6b0912a960d8ca930c7485fbfcb84bc
+  data.tar.gz: 40d1d11e0b104d82bd30198de0eb1dba07f0a4fcc725f6936f8ccbec47276e2cbf91e67f4f57065f79e43dcb46b623ea4c5a085c37ac0d70b7516baad3e0d5f7

data/LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2021 Cyril Kato
+Copyright (c) 2015-2022 Cyril Kato
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -8,12 +8,13 @@
 
 > Collection of expectation matchers for Rubyists 🤹
 
-![A Rubyist juggling between Matchi letters](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.png)
 
 ## 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
 
@@ -53,11 +54,7 @@ All examples here assume that this has been done.
 
 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, it is recommended to expose the expected value via the `expected` method.
-
-That's all it is.
-
-Let's see some examples.
+To facilitate the integration of the matchers in other tools, __Matchi__ matchers may expose expected values via the `expected` method.
 
 ### Built-in matchers
 
@@ -81,6 +78,15 @@ matcher.expected          # => :foo
 matcher.matches? { :foo } # => true
 ```
 
+**Comparisons** matcher:
+
+```ruby
+matcher = Matchi::BeWithin.new(8).of(37)
+
+matcher.expected        # => 37
+matcher.matches? { 42 } # => true
+```
+
 **Regular expressions** matcher:
 
 ```ruby
@@ -108,6 +114,20 @@ matcher.expected           # => "String"
 matcher.matches? { "foo" } # => true
 ```
 
+**Predicate** matcher:
+
+```ruby
+matcher = Matchi::Predicate.new(:be_empty)
+
+matcher.expected        # => [:empty?, [], {}, nil]
+matcher.matches? { [] } # => true
+
+matcher = Matchi::Predicate.new(:have_key, :foo)
+
+matcher.expected                 # => [:has_key?, [:foo], {}, nil]
+matcher.matches? { { foo: 42 } } # => true
+```
+
 **Change** matcher:
 
 ```ruby
@@ -183,8 +203,6 @@ require "prime"
 
 module Matchi
   class BePrime
-    attr_reader :expected
-
     def matches?
       Prime.prime?(yield)
     end
@@ -193,7 +211,6 @@ end
 
 matcher = Matchi::BePrime.new
 
-matcher.expected        # => nil
 matcher.matches? { 42 } # => false
 ```
 

data/lib/matchi/be_within/of.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Matchi
+  class BeWithin
+    # *BeWithin of* matcher.
+    class Of
+      # @return [Numeric] An expected value.
+      attr_reader :expected
+
+      # Initialize the matcher with a delta and an expected value.
+      #
+      # @example
+      #   require "matchi/be_within/of"
+      #
+      #   Matchi::BeWithin::Of.new(1, 41)
+      #
+      # @param delta    [Numeric] The accepted variation of the actual value.
+      # @param expected [Numeric] The expected value.
+      def initialize(delta, expected)
+        @delta    = delta
+        @expected = expected
+      end
+
+      # Boolean comparison on the expected be_within by comparing the actual
+      # value and the expected value.
+      #
+      # @example
+      #   require "matchi/be_within/of"
+      #
+      #   matcher = Matchi::BeWithin::Of.new(1, 41)
+      #
+      #   matcher.expected        # => 41
+      #   matcher.matches? { 42 } # => true
+      #
+      # @yieldreturn [Numeric] The block of code to execute.
+      #
+      # @return [Boolean] Comparison between the actual and the expected values.
+      def matches?
+        (expected - yield).abs <= @delta
+      end
+
+      # A string containing a human-readable representation of the matcher.
+      def inspect
+        "#{self.class}(#{@delta}, #{expected})"
+      end
+
+      # Returns a string representing the matcher.
+      def to_s
+        "be within #{@delta} of #{expected}"
+      end
+    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

data/lib/matchi/predicate.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Matchi
+  # *Predicate* matcher.
+  class Predicate
+    # Initialize the matcher with a name and arguments.
+    #
+    # @example
+    #   require "matchi/predicate"
+    #
+    #   Matchi::Predicate.new(:be_empty)
+    #
+    # @param name   [#to_s] A matcher name.
+    # @param args   [Array] A list of parameters.
+    # @param kwargs [Hash]  A list of keyword parameters.
+    # @param block  [Proc]  A block of code.
+    def initialize(name, *args, **kwargs, &block)
+      @name = String(name)
+
+      raise ::ArgumentError unless valid_name?
+
+      @args   = args
+      @kwargs = kwargs
+      @block  = block
+    end
+
+    # @return [Array] The method name with any arguments to send to the subject.
+    def expected
+      [method_name, @args, @kwargs, @block]
+    end
+
+    # Boolean comparison between the actual value and the expected value.
+    #
+    # @example
+    #   require "matchi/predicate"
+    #
+    #   matcher = Matchi::Predicate.new(:be_empty)
+    #
+    #   matcher.expected        # => [:empty?, [], {}, nil]
+    #   matcher.matches? { [] } # => true
+    #
+    # @example
+    #   require "matchi/predicate"
+    #
+    #   matcher = Matchi::Predicate.new(:have_key, :foo)
+    #
+    #   matcher.expected                 # => [:has_key?, [:foo], {}, nil]
+    #   matcher.matches? { { foo: 42 } } # => true
+    #
+    # @yieldreturn [#object_id] The actual value to receive the method request.
+    #
+    # @return [Boolean] A boolean returned by the actual value being tested.
+    def matches?
+      value = yield.send(method_name, *@args, **@kwargs, &@block)
+      return value if [false, true].include?(value)
+
+      raise ::TypeError, "Boolean expected, but #{value.class} instance returned."
+    end
+
+    # A string containing a human-readable representation of the matcher.
+    def inspect
+      "#{self.class}(#{@name}, *#{@args.inspect}, **#{@kwargs.inspect}, &#{@block.inspect})"
+    end
+
+    # Returns a string representing the matcher.
+    def to_s
+      (
+        "#{@name.tr("_", " ")} " + [
+          @args.map(&:inspect).join(", "),
+          @kwargs.map { |k, v| "#{k}: #{v.inspect}" }.join(", "),
+          (@block.nil? ? "" : "&block")
+        ].reject { |i| i.eql?("") }.join(", ")
+      ).strip
+    end
+
+    private
+
+    # The name of the method to send to the object.
+    def method_name
+      if @name.start_with?("be_")
+        :"#{@name.gsub("be_", "")}?"
+      else
+        :"#{@name.gsub("have_", "has_")}?"
+      end
+    end
+
+    # Verify the matcher name structure.
+    def valid_name?
+      return false if @name.end_with?("?", "!")
+
+      @name.start_with?("be_", "have_")
+    end
+  end
+end

data/lib/matchi.rb

@@ -6,6 +6,6 @@
 module Matchi
 end
 
-Dir[File.join(File.dirname(__FILE__), "matchi", "*.rb")].each do |fname|
+Dir[File.join(File.dirname(__FILE__), "matchi", "*.rb")].sort.each do |fname|
   require_relative fname
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: matchi
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 3.3.1
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-07-23 00:00:00.000000000 Z
+date: 2022-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -133,6 +133,8 @@ files:
 - lib/matchi.rb
 - lib/matchi/be.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
@@ -142,12 +144,14 @@ files:
 - lib/matchi/change/to.rb
 - lib/matchi/eq.rb
 - lib/matchi/match.rb
+- lib/matchi/predicate.rb
 - lib/matchi/raise_exception.rb
 - lib/matchi/satisfy.rb
 homepage: https://github.com/fixrb/matchi
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -156,7 +160,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 2.7.6
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="