matchers 0.1.0.pre.1

data/lib/matcher/matchers/hash_matcher.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+module Matcher
+  ##
+  # == Basic hash matching
+  #
+  #   m = Matcher.build do
+  #     { foo: 1 }
+  #   end
+  #
+  #   m.match?({ foo: 1 })
+  #   # => true
+  #   m.match({ foo: 0 })
+  #   # > root[:foo]: expected 1 but got 0
+  #   m.match({ foo: 1, bar: 1 })
+  #   # > root[:bar]: did not expect to include key :bar
+  #   #   but got {:foo=>1, :bar=>2}
+  #
+  #   # Use matchers for values
+  #   m = Matcher.build { { foo: Integer } }
+  #   m.match?({ foo: 2 }) # => true
+  #
+  # == Variables passed to value matchers
+  #
+  # HashMatcher passes +key+, +value+ and +parent+ to its value matchers.
+  #
+  #   # key
+  #   m = Matcher.build { { foo: _ == k.to_s } }
+  #   m.match?({ foo: "foo" })
+  #   # => true
+  #   m.match({ foo: "bar" })
+  #   # > root[:foo]: expected actual == key.to_s but got "bar" == "foo",
+  #   #   where k = :foo
+  #
+  #   # parent
+  #   m = Matcher.build do
+  #     {
+  #       items: Array,
+  #       length: equal(parent[:items].length),
+  #     }
+  #   end
+  #
+  #   m.match({ items: [1], length: 10 })
+  #   # > root[:length]: expected 1 but got 10
+  #
+  # == Match hash partially
+  #
+  # Use +partial+ and +partial_r+ to match a hash only partially.
+  #
+  # == Optional keys
+  #
+  # Match value only if key included:
+  #
+  #   m = Matcher.build do
+  #     { optional(:foo) => 1 }
+  #   end
+  #
+  #   m.match?({})           # => true
+  #   m.match?({ foo: 1 })   # => true
+  #   m.match?({ foo: 2 })   # => false
+  #   m.match?({ foo: nil }) # => false
+  #
+  # == Match remaining entries
+  #
+  #   m = Matcher.build do
+  #     {
+  #       id: Integer,
+  #       others => each_value(String),
+  #     }
+  #   end
+  #
+  #   m.match?({ id: 1, foo: "bar" })
+  #   # => true
+  #   m.match({ id: 1, foo: nil })
+  #   # > root[:foo]: expected a kind of String but got nil
+  #
+  # == Expression keys
+  #
+  #   m = Matcher.build do
+  #     { vars[:my_key] => 1 }
+  #   end
+  #
+  #   m.match?({ foo: 1 }, my_key: :foo) # => true
+  #
+  # @see MatcherDsl#partial
+  # @see MatcherDsl#partial_r
+  # @see MatcherDsl#each_pair
+  # @see MatcherDsl#each_key
+  # @see MatcherDsl#each_value
+  class HashMatcher < Base
+    def initialize(hash, partial: false, negated: false)
+      super()
+
+      @hash = negated ? hash.transform_values(&:~) : hash
+      @original_hash = hash
+      @partial = partial
+      @negated = negated
+      @includes_others = hash.include?(Others.instance)
+      @includes_optionals = hash.each_key.any?(Optional)
+      @includes_expressions = hash.each_key.any?(Expression)
+
+      raise "cannot use partial(others => ...)" if @partial && @includes_others
+    end
+
+    def negate
+      HashMatcher.new(@original_hash, partial: @partial, negated: !@negated)
+    end
+
+    def validate(state, &)
+      return validate_negated(state, &) if @negated
+
+      actual = state.actual
+
+      unless actual.is_a?(Hash)
+        state.errors << state.expected.kind_of(Hash)
+        return
+      end
+
+      if @includes_expressions
+        expression_values = {}
+
+        @hash.each_key.with_index do |key, i|
+          key = key.value if key.is_a?(Optional)
+
+          if key.is_a?(Expression)
+            expression_values[i] = key.evaluate(state.values)
+          end
+        end
+      end
+
+      expected_keys = if @includes_optionals || @includes_expressions
+        @hash.keys.map.with_index do |k, i|
+          k = k.value if k.is_a?(Optional)
+          k = expression_values[i] if k.is_a?(Expression)
+          k
+        end
+      else
+        @hash.keys
+      end
+
+      extra_keys = actual.keys - expected_keys
+
+      if !@partial && !@includes_others
+        extra_keys.each do |key|
+          state.errors[key] << state.expected.not.having_key(key)
+        end
+      end
+
+      @hash.each_with_index do |(key, value), i|
+        if key.is_a?(Others)
+          state.errors << yield(value, actual.slice(*extra_keys))
+
+          next
+        end
+
+        is_optional = key.is_a?(Optional)
+        key = key.value if is_optional
+        error_key = key
+        key = expression_values[i] if key.is_a?(Expression)
+        actual_value = actual[key]
+
+        if actual_value.nil? && !actual.key?(key)
+          state.errors << state.expected.having_key(key) unless is_optional
+        else
+          error = yield(value, actual_value, key:, parent: actual)
+
+          next if error.valid?
+
+          error_key = key_call_for(error_key) if error_key.is_a?(Expression)
+
+          state.errors[error_key] << error
+        end
+      end
+    end
+
+    def to_s
+      if @negated
+        @partial ? "~partial(#{@original_hash})" : "neg(#{@original_hash})"
+      else
+        @partial ? "partial(#{@hash})" : @hash.to_s
+      end
+    end
+
+    private
+
+    def validate_negated(state)
+      actual = state.actual
+
+      return unless actual.is_a?(Hash)
+
+      if @hash.empty?
+        if @partial
+          state.errors << state.report.kind_of(Hash)
+        elsif actual.empty?
+          state.errors << state.report.predicate(:empty?)
+        end
+
+        return
+      end
+
+      if @includes_expressions
+        expression_values = {}
+
+        @hash.each_key.with_index do |key, i|
+          key = key.value if key.is_a?(Optional)
+
+          if key.is_a?(Expression)
+            expression_values[i] = key.evaluate(state.values)
+          end
+        end
+      end
+
+      expected_keys = if @includes_optionals || @includes_expressions
+        @hash.keys.map.with_index do |k, i|
+          k = k.value if k.is_a?(Optional)
+          k = expression_values[i] if k.is_a?(Expression)
+          k
+        end
+      else
+        @hash.keys
+      end
+
+      extra_keys = actual.keys - expected_keys
+
+      return if !@partial && !@includes_others && !extra_keys.empty?
+
+      collector = state.new_collector.or!
+
+      @hash.each_with_index do |(key, value), i|
+        if key.is_a?(Others)
+          result = yield(value, actual.slice(*extra_keys))
+
+          return nil if result.valid?
+
+          collector << result
+
+          next
+        end
+
+        is_optional = key.is_a?(Optional)
+        key = key.value if is_optional
+        error_key = key
+        key = expression_values[i] if key.is_a?(Expression)
+        actual_value = actual[key]
+
+        if actual_value.nil? && !actual.key?(key)
+          next if is_optional
+
+          return nil
+        end
+
+        result = yield(value, actual_value, key:, parent: actual)
+
+        return nil if result.valid?
+
+        error_key = key_call_for(error_key) if error_key.is_a?(Expression)
+
+        collector[error_key] << result
+      end
+
+      state.errors << if collector.empty?
+        state.report.predicate(:empty?)
+      else
+        collector.error
+      end
+    end
+
+    def key_call_for(key)
+      Call.new(Variable.actual, :[], [key])
+    end
+  end
+
+  module MatcherDsl
+    ##
+    # Matches hash partially
+    # @example
+    #   # matches { foo: 1, bar: 2 } but not { foo: 0, bar: 2 }
+    #   partial(foo: 1)
+    # @param hash [Hash]
+    # @return [HashMatcher]
+    def partial(hash)
+      hash = hash.to_h do |k, v|
+        [expression_or_value(k), matcher_of(v)]
+      end
+
+      HashMatcher.new(hash, partial: true)
+    end
+
+    ##
+    # Matches nested hashes partially
+    # @example
+    #   # matches { foo: { bar: 1, baz: 2 }, qux: 3 }
+    #   partial_r(foo: { bar: 1 })
+    #   # equivalent to:
+    #   partial(foo: partial(bar: 1))
+    # @param hash [Hash]
+    # @return [HashMatcher]
+    def partial_r(hash)
+      hash = hash.to_h do |k, v|
+        [expression_or_value(k), partial_r_helper(v)]
+      end
+
+      HashMatcher.new(hash, partial: true)
+    end
+
+    def partial_r_helper(value)
+      if Recorder.recorder?(value) || !value.is_a?(Hash)
+        matcher_of(value)
+      else
+        partial_r(value)
+      end
+    end
+    private :partial_r_helper
+  end
+end

data/lib/matcher/matchers/imply_matcher.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Matcher
+  class ImplyMatcher < Base
+    attr_reader :condition, :matcher
+
+    def initialize(condition, matcher, negated: false)
+      super()
+
+      @condition = condition
+      @matcher = negated ? ~matcher : matcher
+      @original_matcher = matcher
+      @negated = negated
+    end
+
+    def negate
+      ImplyMatcher.new(@condition, @original_matcher, negated: !@negated)
+    end
+
+    def validate(state, &)
+      return validate_negated(state, &) if @negated
+
+      if @condition.is_a?(ExpressionMatcher)
+        begin
+          # evaluate expression directly
+          return unless @condition.expression.evaluate(state.values)
+        rescue CallError
+          return
+        end
+      else
+        return unless yield(@condition).valid?
+      end
+
+      state.errors << yield(@matcher)
+    end
+
+    def to_s
+      "#{'~' if @negated}imply(#{@condition}, #{@original_matcher})"
+    end
+
+    private
+
+    def validate_negated(state)
+      condition_errors = yield @condition
+
+      state.errors << if condition_errors.valid?
+        yield(@matcher)
+      else
+        condition_errors
+      end
+    end
+  end
+
+  module MatcherDsl
+    ##
+    # Matches if condition mismatches or given matcher matches.
+    # In other words, ignore +matcher+ unless +condition+ is met.
+    # @example
+    #   # matches "hello" and 42 but not "hi"
+    #   imply(String, _.length <= 4)
+    #   # alternatively:
+    #   imply(String) ^ (_.length <= 4) # or
+    #   of(String) >> (_.length <= 4)
+    # @overload imply(condition, matcher)
+    #   @param condition [Expression]
+    #   @param matcher [Base]
+    #   @return [ImplyMatcher]
+    # @overload imply(condition)
+    #   @param condition [Expression]
+    #   @return [Chain<ImplyMatcher>]
+    # @see Base#>>
+    # @see #imply_one
+    # @see #imply_any
+    def imply(condition, matcher = UNDEFINED)
+      return Chain.new { imply(condition, _1) } if Matcher.undefined?(matcher)
+
+      condition = matcher_of(condition)
+      matcher = matcher_of(matcher)
+
+      ImplyMatcher.new(condition, matcher)
+    end
+  end
+end

data/lib/matcher/matchers/imply_some_matcher.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Matcher
+  class ImplySomeMatcher < Base
+    def self.check(matchers, else_matcher, count)
+      raise "count must be a positive integer or :any. Got #{count.inspect}" if
+        count != :any && (!count.is_a?(Integer) || count <= 0)
+
+      raise "else cannot be combined with count > 1" if
+        else_matcher && count != :any && count != 1
+
+      invalid_matcher = matchers.find { !_1.is_a?(ImplyMatcher) }
+
+      raise "Not an ImplyMatcher: #{invalid_matcher.inspect}" if invalid_matcher
+    end
+
+    def initialize(matchers, else_matcher, count)
+      ImplySomeMatcher.check(matchers, else_matcher, count)
+
+      super()
+
+      @matchers = matchers
+      @else_matcher = else_matcher
+      @count = count
+    end
+
+    def negate
+      NegatedImplySomeMatcher.new(@matchers, @else_matcher, @count)
+    end
+
+    def validate(state)
+      errors = state.errors
+      matchers = @matchers.filter { yield(_1.condition).valid? }
+
+      if matchers.empty?
+        errors << if @else_matcher
+          yield @else_matcher
+        else
+          state.report.namespace(:imply_some)
+            .no_condition_satisfied(@matchers.map(&:condition), @count)
+        end
+
+        return
+      elsif @count != :any && matchers.length != @count
+        errors << state.report.namespace(:imply_some)
+          .x_conditions_satisfied(matchers.map(&:condition), @count)
+      end
+
+      matchers.each { errors << yield(_1.matcher) }
+    end
+
+    def to_s
+      args = @matchers.map(&:to_s)
+
+      case @count
+      when :any
+        method = "imply_any"
+      when 1
+        method = "imply_one"
+      else
+        method = "imply_some"
+        args << "count: #{@count}"
+      end
+
+      args << "else: #{@else_matcher}" if @else_matcher
+
+      "#{method}(#{args.join(', ')})"
+    end
+  end
+
+  module MatcherDsl
+    ##
+    # Matches exactly one implied matcher
+    # @example
+    #   # Strings should be lower case and integers positive. But it should
+    #   # either be a string or an integer.
+    #   # matches "foo" and 1 but not "BAR", -1, or nil
+    #   imply_one(
+    #     imply(String, _ == _.downcase),
+    #     imply(Integer, _.positive?),
+    #   )
+    # @param matchers [ImplyMatcher]
+    # @param else [Base] if no condition passed match against +else+ matcher.
+    # @return [ImplySomeMatcher]
+    # @see #imply
+    def imply_one(*matchers, else: UNDEFINED)
+      els = { else: }[:else]
+      else_matcher = Matcher.undefined?(els) ? nil : matcher_of(els)
+
+      ImplySomeMatcher.new(matchers, else_matcher, 1)
+    end
+
+    ##
+    # Matches at least one implied matcher
+    # @example
+    #   # matches 9, 12, 40 but not 8, 21, 15.5
+    #   imply_any(
+    #     imply(_.even?, _ > 10),
+    #     imply(_ % 3 == 0, _ < 20),
+    #   )
+    # @param matchers [ImplyMatcher]
+    # @param else [Base] if no condition passed match against +else+ matcher.
+    # @return [ImplySomeMatcher]
+    # @see #imply
+    def imply_any(*matchers, else: UNDEFINED)
+      els = { else: }[:else]
+      else_matcher = Matcher.undefined?(els) ? nil : matcher_of(els)
+
+      ImplySomeMatcher.new(matchers, else_matcher, :any)
+    end
+
+    def imply_some(*matchers, count:)
+      ImplySomeMatcher.new(matchers, nil, count)
+    end
+  end
+end

data/lib/matcher/matchers/index_by_matcher.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Matcher
+  class IndexByMatcher < Base
+    include MappingUtils
+
+    def initialize(projection, matcher, negated: false)
+      super()
+
+      @projection = projection
+      @matcher = negated ? ~matcher : matcher
+      @original_matcher = matcher
+      @negated = negated
+    end
+
+    def negate
+      IndexByMatcher.new(@projection, @original_matcher, negated: !@negated)
+    end
+
+    def validate(state, &)
+      return validate_negated(state, &) if @negated
+
+      actual = state.actual
+
+      unless actual.respond_to?(:each)
+        state.errors << state.expected.responding_to(:each)
+        return
+      end
+
+      values = state.values
+      failed = false
+      index = {}
+      mapping = {}
+      duplicates = []
+
+      actual.each_with_index do |item, i|
+        key = @projection.evaluate(
+          values.merge(actual: item, index: i, original: actual),
+        )
+
+        mapped_index = mapping[key]
+
+        if mapped_index
+          duplicates << [key, i, mapped_index]
+        else
+          index[key] = item
+          mapping[key] = i
+        end
+
+        key
+      rescue CallError => e
+        state.errors[i] << e.message_for_errors(item)
+        failed = true
+      end
+
+      duplicates.each do |key, i, j|
+        state.errors[i] << state.expected(actual[i])
+          .not.duplicate_by(@projection, key, j)
+      end
+
+      return if failed
+
+      errors = yield(@matcher, index, original: actual)
+      errors = map_errors2(errors, mapping) unless state.boolean?
+
+      state.errors << errors
+    end
+
+    def to_s
+      "#{'~' if @negated}index_by(#{@projection}, #{@original_matcher})"
+    end
+
+    private
+
+    def validate_negated(state)
+      actual = state.actual
+
+      return unless actual.respond_to?(:each)
+
+      values = state.values
+      index = {}
+      mapping = {}
+
+      actual.each_with_index do |item, i|
+        key = @projection.evaluate(
+          values.merge(actual: item, index: i, original: actual),
+        )
+
+        return nil if mapping.key?(key)
+
+        index[key] = item
+        mapping[key] = i
+
+        key
+      rescue CallError
+        return nil
+      end
+
+      errors = yield(@matcher, index, original: actual)
+
+      state.errors << map_errors2(errors, mapping)
+    end
+
+    def map_errors2(error, mapping)
+      map_errors(error) do |nested_error|
+        key = nested_error.key
+
+        next unless index_call?(key)
+
+        index = mapping[operand_of(key)]
+
+        NestedError.new(index_call_to(index), nested_error.child) if index
+      end
+    end
+
+    def mapped_base
+      return @mapped_base if @mapped_base
+
+      expression = @projection
+      with_index = expression.variables.include?(:index)
+      element = expression.free_symbol(:e)
+      parameters = [[:opt, element]]
+      parameters << %i[opt index] if with_index
+      substituted = expression.substitute(actual: element, original: :actual)
+      pair = ArrayExpression.new([substituted, Variable.new(element)])
+      block = Block.new(parameters, pair)
+
+      receiver = if with_index
+        Call.new(Variable.actual, :each_with_index)
+      else
+        Variable.actual
+      end
+
+      @mapped_base = Call.new(receiver, :to_h, [], {}, block)
+    end
+  end
+
+  module MatcherDsl
+    ##
+    # Matches against an indexed version of actual.
+    #
+    # This is really useful when validating an array of items where the order
+    # shouldn't matter.
+    # @example
+    #   # matches:
+    #   # [
+    #   #   { name: "bar", value: 2 },
+    #   #   { name: "foo", value: 1 },
+    #   # ]
+    #   index_by(_[:name], {
+    #     "foo" => { name: "foo", value: 1 },
+    #     "bar" => { name: "bar", value: 2 },
+    #   })
+    #   # alternatively:
+    #   index_by(_[:name]) ^ {
+    #     "foo" => { name: "foo", value: 1 },
+    #     "bar" => { name: "bar", value: 2 },
+    #   }
+    # @overload index_by(expression, matcher)
+    #   @param expression [Expression]
+    #   @param matcher [Base]
+    #   @return [IndexByMatcher]
+    # @overload index_by(expression)
+    #   @param expression [Expression]
+    #   @return [Chain<IndexByMatcher>]
+    def index_by(expression, matcher = UNDEFINED)
+      if Matcher.undefined?(matcher)
+        return Chain.new { index_by(expression, _1) }
+      end
+
+      expression = expression_of(expression)
+      matcher = matcher_of(matcher)
+
+      IndexByMatcher.new(expression, matcher)
+    end
+  end
+end