matchers 0.1.0.pre.1 → 0.1.0.pre.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92ba01bc8b3f334276b254cb4b78efcd86165a7410cad65fc21e0b319d532df0
-  data.tar.gz: 3626679374928bd5adf361c3d9d1fa357033e003ae702d225f4c3a9b4e028b82
+  metadata.gz: da3b2bf6ae8a3e758ddbb13a3a86955c222eca68d4b3da7fab7545b409153116
+  data.tar.gz: 9c1652a64d328979699349c83b82af1c3ff3fbc769ec22147dc8086f6b42c2c6
 SHA512:
-  metadata.gz: 32fb3f33b2d210d46f81ebaa0f3c4aec455a4543806b3b38e7eefd42f81718f98a2690a600140b12702d3c9ee3232f63c9d4a55b8f58840597779cff40b95276
-  data.tar.gz: 556079ba3a6e26bdc35217e651740d4f1298bc7886165dca2e4715ee0c270955baabb28fd66c6df4031acc6e42af774e5d19ae6bf70b76a10935ffcdeeea3758
+  metadata.gz: c4ea65ab07d7bf8ca6e317d91c0248f603972034b8af39125e7286d2461e78a75d85be8fe2f2d367171208c95e6e11e41e0bc0276b5ec0a59043ad701de52033
+  data.tar.gz: fa0d1a999b7782edd7a02386f38f249657453e1ae8d2e9ce6a4c1fa5a1c5f35fc030d5d6cad34abf2be04e6b6def3b960eeab365ffa8b2918c41a4ba44f89a07

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Rico Jasper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,233 @@
+# Matcher
+
+[![CI](https://github.com/rjasper/ruby-matchers/actions/workflows/ci.yml/badge.svg)](https://github.com/rjasper/ruby-matchers/actions/workflows/ci.yml)
+
+A Ruby gem for validating nested data structures. Make simple matchers easy
+and complex matchers possible.
+
+Whether you're checking API responses, configuration files, AI output, or
+asserting complex structures in tests — writing validation for nested data by
+hand gets tedious fast. When something doesn't match, a full diff on a large
+hash leaves you searching for the actual problem. This gem points you right
+to it: `root[:users][1][:age]: expected a value >= 18 but got 12`.
+
+You describe the expected structure using a DSL that mirrors the shape of the
+data. Ruby literals like classes, ranges, and regexps become matchers
+automatically.
+
+## Docs
+
+- [Quick Reference](doc/quick-reference.md)
+- [Guide](doc/guide-1-basics.md) — start with the basics, 12 chapters total
+- [Comparison with other libraries](doc/comparison.md)
+
+<details>
+<summary>All guide chapters</summary>
+
+1. [Basics](doc/guide-1-basics.md)
+2. [Arrays](doc/guide-2-arrays.md)
+3. [Hashes](doc/guide-3-hashes.md)
+4. [Enumerables](doc/guide-4-enumerables.md)
+5. [Combining](doc/guide-5-combine-matchers.md)
+6. [Calls](doc/guide-6-calls.md)
+7. [Strings](doc/guide-7-strings.md)
+8. [Expressions](doc/guide-8-expressions.md)
+9. [ExpressionMatchers](doc/guide-9-expression-matchers.md)
+10. [Miscellaneous](doc/guide-10-misc.md)
+11. [Recursive Matchers](doc/guide-11-refs.md)
+12. [Custom Matchers](doc/guide-12-custom-matchers.md)
+</details>
+
+## Examples
+
+Validate a file manifest — check paths, verify checksums against content, and
+parse timestamps:
+
+```ruby
+require "digest"
+
+matcher = Matcher.build do
+  {
+    files: each({
+      path: of(String) & _.start_with?("/"),
+      size: _.positive?,
+      content: String,
+      checksum: lazy_all(
+        /\A[a-f0-9]{8}\z/, # 8-char hex string
+        _ == expr(Digest::MD5).hexdigest(parent[:content])[0, 8] # matches content
+      ),
+      uploaded_at: parse_iso8601 ^ (_ >= Time.new(2025, 1, 1)),
+    }),
+  }
+end
+
+errors = matcher.match({
+  files: [
+    {
+      path: "relative/path",
+      size: 0,
+      content: "hello",
+      checksum: "not-a-checksum",
+      uploaded_at: "not-a-date",
+    },
+    {
+      path: "/valid/path",
+      size: 100,
+      content: "data",
+      checksum: Digest::MD5.hexdigest("wrong content")[0, 8],
+      uploaded_at: "2024-06-01T00:00:00Z",
+    },
+  ],
+})
+puts errors.report
+# > root[:files][0][:path]: expected actual.start_with?("/") to be truthy but got false, where actual = "relative/path"
+# > root[:files][0][:size]: expected value to be positive but got 0
+# > root[:files][0][:checksum]: expected value to match /\A[a-f0-9]{8}\z/ but got "not-a-checksum"
+# > root[:files][0][:uploaded_at]: expected a valid iso8601 string but got "not-a-date"
+# > root[:files][1][:checksum]: expected actual == Digest::MD5.hexdigest(parent[:content])[0, 8] but got "5cabbd5b" == "8d777f38", where parent = { ... }
+# > Time.iso8601(root[:files][1][:uploaded_at]): expected a value >= 2025-01-01 00:00:00 +0100 but got 2024-06-01 00:00:00 UTC
+```
+
+### Start simple
+
+Ruby literals are matchers automatically — classes, ranges, regexps, arrays,
+and hashes all work out of the box:
+
+```ruby
+matcher = Matcher.build do
+  {
+    name: String,
+    age: 0..150,
+    active: boolean,
+    tags: each(String),
+  }
+end
+
+matcher.match?({ name: "Alice", age: 30, active: true, tags: ["ruby"] })
+# => true
+
+errors = matcher.match({ name: nil, age: -1, active: nil, tags: [42] })
+puts errors.report
+# > root[:name]: expected a kind of String but got nil
+# > root[:age]: expected value to be between 0 and 150 but got -1
+# > root[:active]: expected object to be included in [false, true] but got nil
+# > root[:tags][0]: expected a kind of String but got 42
+```
+
+### Combine matchers
+
+Matchers combine with `&` (and), `|` (or), and `~` (negate).
+
+```ruby
+matcher = Matcher.build do
+  {
+    id: any(String, Integer),
+    score: of(Integer) & _.positive?,
+    status: ~equal("deleted"),
+  }
+end
+
+errors = matcher.match({ id: nil, score: -5, status: "deleted" })
+puts errors.report
+# > expected at least one error to be absent:
+# > - root[:id]: expected a kind of String but got nil
+# > - root[:id]: expected a kind of Integer but got nil
+# > root[:score]: expected value to be positive but got -5
+# > root[:status]: did not expect "deleted"
+```
+
+See also `one`, `>>` (imply) and more:
+
+```ruby
+of(String) >> (_.length <= 255) # if it's a String, it must be short
+```
+
+See [combining matchers](doc/guide-5-combine-matchers.md).
+
+### Error tracing through transformations
+
+After `map`, `filter`, or `dig`, errors still point to the position in the
+original data.
+
+```ruby
+matcher = Matcher.build do
+  filter(_.odd?) ^ each(_ < 10)
+end
+
+errors = matcher.match([2, 3, 4, 15, 6])
+puts errors.report
+# > root[3]: expected a value < 10 but got 15
+```
+
+The error reports index 3 in the original array, not index 1 in the filtered
+result. See also `map`, `dig`, `index_by`, and `project`:
+
+```ruby
+project(_.to_i => 1..100, _.length => 1..3) # match projected values
+```
+
+See [enumerables](doc/guide-4-enumerables.md) and [calls](doc/guide-6-calls.md).
+
+### Recursive matchers
+
+`refs` lets matchers reference themselves for trees and graphs.
+
+```ruby
+matcher = Matcher.build do
+  refs[:node] = {
+    value: Integer,
+    children: each(refs[:node]),
+  }
+end
+
+errors = matcher.match({
+  value: 1,
+  children: [
+    { value: 2, children: [] },
+    { value: "three", children: [] },
+  ]
+})
+puts errors.report
+# > root[:children][1][:value]: expected a kind of Integer but got "three"
+```
+
+See [Recursive Matchers](doc/guide-11-refs.md)
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add matchers
+
+If bundler is not being used to manage dependencies, install the gem by
+executing:
+
+    $ gem install matchers --pre
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake test` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and the created tag, and push the `.gem` file
+to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/rjasper/ruby-matchers. See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Code of Conduct
+
+Everyone interacting in the Matcher project's codebases, issue trackers, chat
+rooms and mailing lists is expected to follow
+the [code of conduct](https://github.com/rjasper/ruby-matchers/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of
+the [MIT License](https://opensource.org/licenses/MIT).

data/lib/matcher/autoload.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Matcher
-  autoload :Reporter, "matcher/reporter"
+  autoload :Reporter, "matcher/errors/reporter"
 end

data/lib/matcher/dsl/expression_builder.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Matcher
+  class ExpressionBuilder
+    include ExpressionDsl
+
+    def initialize(build_session: Matcher.build_session)
+      ExpressionDsl.init(self, build_session)
+    end
+  end
+end

data/lib/matcher/dsl/optional.rb

@@ -39,6 +39,26 @@ module Matcher
       ~Matcher.cache(self)
     end
 
+    def +(other)
+      Matcher.cache(self) + other
+    end
+
+    def *(other)
+      Matcher.cache(self) * other
+    end
+
+    def |(other)
+      Matcher.cache(self) | other
+    end
+
+    def &(other)
+      Matcher.cache(self) & other
+    end
+
+    def >>(other)
+      Matcher.cache(self) >> other
+    end
+
     def ==(other)
       return true if equal?(other)
 

data/lib/matcher/dsl/optional_chain.rb

@@ -17,6 +17,26 @@ module Matcher
       OptionalChain.new(~@chain, @fallback)
     end
 
+    def +(other)
+      Matcher.cache(fallback) + other
+    end
+
+    def *(other)
+      Matcher.cache(fallback) * other
+    end
+
+    def |(other)
+      Matcher.cache(fallback) | other
+    end
+
+    def &(other)
+      Matcher.cache(fallback) & other
+    end
+
+    def >>(other)
+      Matcher.cache(fallback) >> other
+    end
+
     def fallback
       @chain ^ @fallback
     end

data/lib/matcher/expressions/expression.rb

@@ -24,125 +24,7 @@ module Matcher
   #
   # @see Recorder
   class Expression
-    class ExpressionBuilder
-      include ExpressionDsl
-
-      def initialize(build_session: Matcher.build_session)
-        ExpressionDsl.init(self, build_session)
-      end
-    end
-
-    ##
-    # Builds an expression conveniently using {Recorder} and helpers from
-    # {ExpressionDsl}.
-    #
-    # @example
-    #   Matcher::Expression.build do
-    #     _.sum(&:to_i)
-    #   end
-    #
-    #   Matcher::Expression.build do
-    #     range(vars[:from], vars[:to]).include?(_)
-    #   end
-    #
-    # @see ExpressionDsl
-    def self.build(&)
-      Matcher.with_build_session do |build_session|
-        builder = ExpressionBuilder.new(build_session:)
-        result = builder.instance_exec(&)
-        builder.expression_of(result)
-      end
-    end
-
-    def self.expression_or_value(obj, expression_cache: nil)
-      case obj
-      when -> { Recorder.recorder?(_1) }
-        return Recorder.to_expression(obj)
-      when Base
-        raise ArgumentError, "Cannot use matcher as expression"
-      when NoExpression
-        raise ArgumentError, "Cannot use #{obj.class} as expression"
-      when Proc
-        raise ArgumentError, "Cannot use Proc as expression. " \
-          "Use `expr { ... }' instead"
-      when Array
-        items = obj.map { expression_or_value(_1, expression_cache:) }
-
-        if items.any?(Expression)
-          items.each_with_index do |item, i|
-            unless item.is_a?(Expression)
-              items[i] = Constant.cache(item, expression_cache)
-            end
-          end
-
-          return ArrayExpression.new(items)
-        end
-      when Hash
-        pairs = obj.map do |key, value|
-          key = expression_or_value(key, expression_cache:)
-          value = expression_or_value(value, expression_cache:)
-
-          [key, value]
-        end
-
-        if pairs.any? { |k, v| k.is_a?(Expression) || v.is_a?(Expression) }
-          pairs.each do |pair|
-            k, v = pair
-
-            unless k.is_a?(Expression)
-              pair[0] = Constant.cache(k, expression_cache)
-            end
-            unless v.is_a?(Expression)
-              pair[1] = Constant.cache(v, expression_cache)
-            end
-          end
-
-          return HashExpression.new(pairs)
-        end
-      when Range
-        from = expression_or_value(obj.begin, expression_cache:)
-        to = expression_or_value(obj.end, expression_cache:)
-
-        if from.is_a?(Expression) || to.is_a?(Expression)
-          unless from.is_a?(Expression)
-            from = Constant.cache(from, expression_cache)
-          end
-          to = Constant.cache(to, expression_cache) unless to.is_a?(Expression)
-
-          return RangeExpression.new(from, to, exclude_end: obj.exclude_end?)
-        end
-      when Set
-        items = obj.map { expression_or_value(_1, expression_cache:) }
-
-        if items.any?(Expression)
-          items.each_with_index do |item, i|
-            unless item.is_a?(Expression)
-              items[i] = Constant.cache(item, expression_cache)
-            end
-          end
-
-          return SetExpression.new(items)
-        end
-      end
-
-      obj
-    end
-
-    def self.of(obj, expression_cache: nil)
-      obj = expression_or_value(obj, expression_cache:)
-
-      if obj.is_a?(Expression)
-        obj
-      else
-        Constant.cache(obj, expression_cache)
-      end
-    end
-
-    def self.try_recorder(obj)
-      return obj unless Recorder.recorder?(obj)
-
-      Recorder.to_expression(obj)
-    end
+    extend ExpressionBuilding
 
     def initialize
       raise "abstract class" if instance_of?(Expression)

data/lib/matcher/expressions/expression_building.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Matcher
+  module ExpressionBuilding
+    ##
+    # Builds an expression conveniently using {Recorder} and helpers from
+    # {ExpressionDsl}.
+    #
+    # @example
+    #   Matcher::Expression.build do
+    #     _.sum(&:to_i)
+    #   end
+    #
+    #   Matcher::Expression.build do
+    #     range(vars[:from], vars[:to]).include?(_)
+    #   end
+    #
+    # @see ExpressionDsl
+    def build(&)
+      Matcher.with_build_session do |build_session|
+        builder = ExpressionBuilder.new(build_session:)
+        result = builder.instance_exec(&)
+        builder.expression_of(result)
+      end
+    end
+
+    def expression_or_value(obj, expression_cache: nil)
+      case obj
+      when -> { Recorder.recorder?(_1) }
+        return Recorder.to_expression(obj)
+      when Base
+        raise ArgumentError, "Cannot use matcher as expression"
+      when NoExpression
+        raise ArgumentError, "Cannot use #{obj.class} as expression"
+      when Proc
+        raise ArgumentError, "Cannot use Proc as expression. " \
+          "Use `expr { ... }' instead"
+      when Array
+        items = obj.map { expression_or_value(_1, expression_cache:) }
+
+        if items.any?(Expression)
+          items.each_with_index do |item, i|
+            unless item.is_a?(Expression)
+              items[i] = Constant.cache(item, expression_cache)
+            end
+          end
+
+          return ArrayExpression.new(items)
+        end
+      when Hash
+        pairs = obj.map do |key, value|
+          key = expression_or_value(key, expression_cache:)
+          value = expression_or_value(value, expression_cache:)
+
+          [key, value]
+        end
+
+        if pairs.any? { |k, v| k.is_a?(Expression) || v.is_a?(Expression) }
+          pairs.each do |pair|
+            k, v = pair
+
+            unless k.is_a?(Expression)
+              pair[0] = Constant.cache(k, expression_cache)
+            end
+            unless v.is_a?(Expression)
+              pair[1] = Constant.cache(v, expression_cache)
+            end
+          end
+
+          return HashExpression.new(pairs)
+        end
+      when Range
+        from = expression_or_value(obj.begin, expression_cache:)
+        to = expression_or_value(obj.end, expression_cache:)
+
+        if from.is_a?(Expression) || to.is_a?(Expression)
+          unless from.is_a?(Expression)
+            from = Constant.cache(from, expression_cache)
+          end
+          to = Constant.cache(to, expression_cache) unless to.is_a?(Expression)
+
+          return RangeExpression.new(from, to, exclude_end: obj.exclude_end?)
+        end
+      when Set
+        items = obj.map { expression_or_value(_1, expression_cache:) }
+
+        if items.any?(Expression)
+          items.each_with_index do |item, i|
+            unless item.is_a?(Expression)
+              items[i] = Constant.cache(item, expression_cache)
+            end
+          end
+
+          return SetExpression.new(items)
+        end
+      end
+
+      obj
+    end
+
+    def of(obj, expression_cache: nil)
+      obj = expression_or_value(obj, expression_cache:)
+
+      if obj.is_a?(Expression)
+        obj
+      else
+        Constant.cache(obj, expression_cache)
+      end
+    end
+
+    def try_recorder(obj)
+      return obj unless Recorder.recorder?(obj)
+
+      Recorder.to_expression(obj)
+    end
+  end
+end

data/lib/matcher/matchers/array_matcher.rb

@@ -37,17 +37,21 @@ module Matcher
   #   # > root[2]: expected actual >= parent[index - 1] but got 0 >= 2, where
   #   #   parent = [1, 2, 0], index = 2
   class ArrayMatcher < Base
-    def initialize(array)
+    def initialize(array, negated: false)
       super()
 
-      @array = array
+      @array = negated ? array.map(&:~) : array
+      @original_array = array
+      @negated = negated
     end
 
     def negate
-      NegatedArrayMatcher.new(@array)
+      ArrayMatcher.new(@original_array, negated: !@negated)
     end
 
-    def validate(state)
+    def validate(state, &)
+      return validate_negated(state, &) if @negated
+
       actual = state.actual
       errors = state.errors
 
@@ -66,7 +70,27 @@ module Matcher
     end
 
     def to_s
-      @array.to_s
+      @negated ? "neg(#{@original_array})" : @original_array.to_s
+    end
+
+    private
+
+    def validate_negated(state)
+      actual = state.actual
+
+      return if !actual.is_a?(Array) || @array.length != actual.length
+
+      collector = state.new_collector.or!
+
+      @array.length.times do |i|
+        result = yield @array[i], actual[i], index: i, parent: actual
+
+        return nil if result.valid?
+
+        collector[i] << result
+      end
+
+      state.errors << collector.error
     end
   end
 end

data/lib/matcher/matchers/each_matcher.rb

@@ -20,17 +20,21 @@ module Matcher
   #   m.match?([1, 0, 2]) # => true
   #   m.match?([1, 2, 3]) # => false
   class EachMatcher < Base
-    def initialize(matcher)
+    def initialize(matcher, negated: false)
       super()
 
-      @matcher = matcher
+      @matcher = negated ? ~matcher : matcher
+      @original_matcher = matcher
+      @negated = negated
     end
 
     def negate
-      NegatedEachMatcher.new(@matcher)
+      EachMatcher.new(@original_matcher, negated: !@negated)
     end
 
-    def validate(state)
+    def validate(state, &)
+      return validate_negated(state, &) if @negated
+
       unless state.actual.respond_to?(:each)
         state.errors << state.expected.responding_to(:each)
         return
@@ -44,7 +48,25 @@ module Matcher
     end
 
     def to_s
-      "each(#{@matcher})"
+      "#{"~" if @negated}each(#{@original_matcher})"
+    end
+
+    private
+
+    def validate_negated(state)
+      return unless state.actual.respond_to?(:each)
+
+      collector = state.new_collector.or!
+
+      state.actual.each.with_index do |item, i|
+        result = yield @matcher, item, index: i, parent: state.actual
+
+        return nil if result.valid?
+
+        collector[i] << result
+      end
+
+      state.errors << collector.error
     end
   end