matchers 0.1.0.pre.1

data/lib/matcher/utils/mapping_utils.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Matcher
+  module MappingUtils
+    def unary_call?(expression)
+      expression.unary? && expression.receiver == Variable.actual
+    end
+
+    def index_call?(expression)
+      expression.binary? &&
+        expression.receiver == Variable.actual &&
+        expression.args[0].is_a?(Constant)
+    end
+
+    def operand_of(expression)
+      expression.args[0].value
+    end
+
+    def index_call_to(operand)
+      Call.new(Variable.actual, :[], [Constant.new(operand)])
+    end
+
+    def map_errors(error, &)
+      case error
+      when EmptyError
+        error
+      when AndError, OrError
+        children = error.children.map { map_errors(_1, &) }
+        error.class.new(children)
+      when NestedError
+        yield(error) || error
+      when ElementError
+        NestedError.new(mapped_base, error)
+      else
+        raise "Unexpected error: #{error.inspect}"
+      end
+    end
+
+    def map_base(method, expression)
+      with_index = expression.variables.include?(:index)
+
+      block = if unary_call?(expression)
+        SymbolProc.new(expression.method)
+      else
+        element = expression.free_symbol(:e)
+        parameters = [[:opt, element]]
+        parameters << %i[opt index] if with_index
+        substituted = expression.substitute(actual: element, original: :actual)
+
+        Block.new(parameters, substituted)
+      end
+
+      if with_index
+        enum_for = Call.new(Variable.actual, method)
+        Call.new(enum_for, :with_index, [], {}, block)
+      else
+        Call.new(Variable.actual, method, [], {}, block)
+      end
+    end
+  end
+end

data/lib/matcher/utils.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Matcher
+  module Utils
+    def self.to_string(obj)
+      case obj
+      when Hash
+        return "{}" if obj.empty?
+
+        body = obj.map do |k, v|
+          if k.is_a?(Symbol)
+            "#{k}: #{to_string(v)}"
+          else
+            "#{k.inspect} => #{to_string(v)}"
+          end
+        end
+
+        "{ #{body.join(', ')} }"
+      when Array
+        "[#{obj.map { |v| to_string(v) }.join(', ')}]"
+      else
+        obj.inspect
+      end
+    end
+
+    def self.call_block(block, values, parameters: block.parameters)
+      args = []
+      kwargs = {}
+
+      parameters.each do |type, name|
+        case type
+        when :req, :opt, :rest
+          args << values[:actual] if args.length == 0
+        when :keyreq
+          kwargs[name] = values[name]
+        when :key
+          value = values[name]
+          kwargs[name] = value if !value.nil? || values.key?(name)
+        when :keyrest
+          kwargs.merge!(values.except(*kwargs.keys))
+        end
+      end
+
+      block.call(*args, **kwargs)
+    end
+
+    def self.inspect_block_params(block)
+      arg_names = []
+      kwarg_names = []
+
+      block.parameters.each do |type, name|
+        case type
+        when :req, :opt, :rest
+          arg_names << name
+        when :keyreq, :key, :keyrest
+          kwarg_names << name
+        end
+      end
+
+      arg_parts = arg_names.all? { _1.match?(/^_[1-9]$/) } ? [] : arg_names
+      kwarg_parts = kwarg_names.map { "#{_1}:" }
+
+      (arg_parts + kwarg_parts).join(", ")
+    end
+
+    def self.block_location(block)
+      file, line = block.source_location
+
+      "#{File.basename(file)}:#{line}"
+    end
+  end
+end

data/lib/matcher/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Matcher
+  VERSION = "0.1.0.pre.1"
+end

data/lib/matcher.rb

@@ -0,0 +1,346 @@
+# frozen_string_literal: true
+
+require_relative "matcher/version"
+
+require "singleton"
+require "forwardable"
+
+require_relative "matcher/autoload"
+require_relative "matcher/markers"
+
+require_relative "matcher/dsl/expression_dsl"
+require_relative "matcher/dsl/matcher_dsl"
+require_relative "matcher/base"
+
+require_relative "matcher/dsl/builder"
+require_relative "matcher/dsl/optional"
+require_relative "matcher/dsl/optional_chain"
+require_relative "matcher/dsl/others"
+require_relative "matcher/dsl/chain"
+
+require_relative "matcher/patterns/pattern_building"
+require_relative "matcher/utils/mapping_utils"
+
+require_relative "matcher/assertions"
+require_relative "matcher/compatibility"
+require_relative "matcher/debug"
+require_relative "matcher/expression_labeler"
+require_relative "matcher/expression_cache"
+require_relative "matcher/hash_stack"
+require_relative "matcher/list"
+require_relative "matcher/matcher_cache"
+require_relative "matcher/state"
+require_relative "matcher/undefined"
+require_relative "matcher/utils"
+
+require_relative "matcher/errors/error"
+require_relative "matcher/errors/and_error"
+require_relative "matcher/errors/element_error"
+require_relative "matcher/errors/empty_error"
+require_relative "matcher/errors/error_collector"
+require_relative "matcher/errors/nested_error"
+require_relative "matcher/errors/or_error"
+require_relative "matcher/errors/boolean_collector"
+
+require_relative "matcher/expressions/expression"
+require_relative "matcher/expressions/array_expression"
+require_relative "matcher/expressions/block"
+require_relative "matcher/expressions/call"
+require_relative "matcher/expressions/call_error"
+require_relative "matcher/expressions/constant"
+require_relative "matcher/expressions/expression_walker"
+require_relative "matcher/expressions/hash_expression"
+require_relative "matcher/expressions/proc_expression"
+require_relative "matcher/expressions/range_expression"
+require_relative "matcher/expressions/recorder"
+require_relative "matcher/expressions/rescue_last_error_expression"
+require_relative "matcher/expressions/set_expression"
+require_relative "matcher/expressions/string_expression"
+require_relative "matcher/expressions/symbol_proc"
+require_relative "matcher/expressions/variable"
+
+require_relative "matcher/matchers/all_matcher"
+require_relative "matcher/matchers/always_matcher"
+require_relative "matcher/matchers/any_matcher"
+require_relative "matcher/matchers/array_matcher"
+require_relative "matcher/matchers/block_matcher"
+require_relative "matcher/matchers/boolean_matcher"
+require_relative "matcher/matchers/dig_matcher"
+require_relative "matcher/matchers/each_matcher"
+require_relative "matcher/matchers/each_pair_matcher"
+require_relative "matcher/matchers/equal_matcher"
+require_relative "matcher/matchers/equal_set_matcher"
+require_relative "matcher/matchers/expression_matcher"
+require_relative "matcher/matchers/filter_matcher"
+require_relative "matcher/matchers/hash_matcher"
+require_relative "matcher/matchers/index_by_matcher"
+require_relative "matcher/matchers/inline_matcher"
+require_relative "matcher/matchers/imply_matcher"
+require_relative "matcher/matchers/imply_some_matcher"
+require_relative "matcher/matchers/keys_matcher"
+require_relative "matcher/matchers/kind_of_matcher"
+require_relative "matcher/matchers/lazy_all_matcher"
+require_relative "matcher/matchers/lazy_any_matcher"
+require_relative "matcher/matchers/let_matcher"
+require_relative "matcher/matchers/map_matcher"
+require_relative "matcher/matchers/negated_array_matcher"
+require_relative "matcher/matchers/negated_each_matcher"
+require_relative "matcher/matchers/negated_each_pair_matcher"
+require_relative "matcher/matchers/negated_imply_some_matcher"
+require_relative "matcher/matchers/negated_matcher"
+require_relative "matcher/matchers/negated_project_matcher"
+require_relative "matcher/matchers/never_matcher"
+require_relative "matcher/matchers/one_matcher"
+require_relative "matcher/matchers/optional_matcher"
+require_relative "matcher/matchers/parse_float_matcher"
+require_relative "matcher/matchers/parse_integer_matcher"
+require_relative "matcher/matchers/parse_iso8601_helper"
+require_relative "matcher/matchers/parse_json_helper"
+require_relative "matcher/matchers/project_matcher"
+require_relative "matcher/matchers/raises_matcher"
+require_relative "matcher/matchers/range_matcher"
+require_relative "matcher/matchers/reference_matcher"
+require_relative "matcher/matchers/reference_matcher_collection"
+require_relative "matcher/matchers/regexp_matcher"
+
+require_relative "matcher/messages/phrasing"
+require_relative "matcher/messages/message_builder"
+require_relative "matcher/messages/expected_phrasing"
+require_relative "matcher/messages/message"
+require_relative "matcher/messages/namespaced_message_builder"
+require_relative "matcher/messages/standard_message_builder"
+
+require_relative "matcher/patterns/hole"
+require_relative "matcher/patterns/ast_mapping"
+require_relative "matcher/patterns/capture_hole"
+require_relative "matcher/patterns/constant_hole"
+require_relative "matcher/patterns/method_hole"
+require_relative "matcher/patterns/pattern"
+require_relative "matcher/patterns/pattern_capture"
+require_relative "matcher/patterns/pattern_match"
+require_relative "matcher/patterns/variable_hole"
+
+require_relative "matcher/rules/message_factory"
+require_relative "matcher/rules/message_rule"
+require_relative "matcher/rules/message_rule_context"
+require_relative "matcher/rules/rule_builder"
+require_relative "matcher/rules/rule_set"
+require_relative "matcher/rules/transform_builder"
+require_relative "matcher/rules/transform_mapping"
+require_relative "matcher/rules/transform_rule"
+
+require_relative "matcher/testing/error_builder"
+require_relative "matcher/testing/error_checker"
+require_relative "matcher/testing/error_testing"
+require_relative "matcher/testing/pattern_testing"
+require_relative "matcher/testing/pattern_testing_scope"
+
+module Matcher
+  UNDEFINED = Undefined.instance
+
+  def self.undefined?(object)
+    # Note that for an ExpressionRecorder object == UNDEFINED won't work.
+
+    # rubocop:disable Style/YodaCondition
+    UNDEFINED == object
+    # rubocop:enable Style/YodaCondition
+  end
+
+  ##
+  # Builds a matcher from a block
+  #
+  # Inside the block all matcher and expression building helpers are available.
+  # The return value of the block is converted to a matcher via +Matcher.of+.
+  # @example
+  #   m = Matcher.build do
+  #     { name: String, count: 1..10 }
+  #   end
+  #   m.match?({ name: 'test', count: 5 }) # => true
+  # @return [Base]
+  # @see Matcher.of
+  # @see MatcherDsl
+  # @see ExpressionDsl
+  def self.build(&block)
+    with_build_session do |build_session|
+      builder = Builder.new(block.binding.receiver, build_session:)
+      object = builder.instance_exec(&block)
+      builder.refs.finalize
+
+      matcher = if builder.refs? && builder.refs.last_object_id == object.__id__
+        builder.refs.last_matcher
+      else
+        builder.matcher_of(object)
+      end
+
+      if (assigns = builder.assigns)
+        LetMatcher.new(assigns, matcher)
+      else
+        matcher
+      end
+    end
+  end
+
+  def self.max_reference_depth
+    @max_reference_depth ||= 100
+  end
+
+  def self.max_reference_depth=(value)
+    @max_reference_depth = value
+  end
+
+  ##
+  # Converts an object into a matcher
+  #
+  # The conversion depends on the type of the value:
+  #
+  # +Module+ or +Class+: match kind with {KindOfMatcher}
+  #   Matcher.of(String).match?("Hello World!")
+  # +Range+: match between with {RangeMatcher}
+  #   Matcher.of(1..10).match?(5)
+  # +Regexp+: match pattern with {RegexpMatcher}
+  #   Matcher.of(/Hello/).match?("Hello World!")
+  # +Array+: match all elements with {ArrayMatcher}
+  #   Matcher.of([1, String]).match?([1, "Hello"])
+  # +Hash+: match all entries with {HashMatcher}
+  #   Matcher.of({ a: 1, b: 0..10 }).match?({ a: 1, b: 5 })
+  # +Expression+ or +Recorder+: match where evaluated expression is truthy
+  # (see {ExpressionMatcher})
+  #   even = Matcher::Expression.build { _.even? }
+  #   Matcher.of(even).match?(4)
+  # other objects: match equal value with {EqualMatcher}
+  #   Matcher.of(1).match?(1)
+  # @param object the value to convert
+  # @return [Base]
+  def self.of(object, matcher_cache: nil, expression_cache: nil)
+    object = Expression.try_recorder(object)
+
+    case object
+    when NoMatcher
+      raise ArgumentError, "Cannot use #{object.class} as matcher"
+    when Module
+      KindOfMatcher.cache(object, matcher_cache)
+    when OptionalChain
+      object.fallback
+    when Base
+      object
+    when Expression
+      ExpressionMatcher.cache(object, matcher_cache, expression_cache)
+    when Proc
+      BlockMatcher.new(object)
+    when Range
+      RangeMatcher.cache(object, matcher_cache)
+    when Regexp
+      RegexpMatcher.cache(object, matcher_cache)
+    when Hash
+      hash = object.to_h do |k, v|
+        case k
+        when -> { Recorder.recorder?(_1) }
+          k = Recorder.to_expression(k)
+        when Optional
+          k = Optional.cache(k.value, matcher_cache)
+        when Base
+          raise "Cannot use matcher as key for hash matcher"
+        when NoKey
+          raise "Cannot use #{k.class} as key for hash matcher"
+        when Others
+          # keep k
+        else
+          k = Expression.expression_or_value(k)
+        end
+
+        [k, of(v, matcher_cache:, expression_cache:)]
+      end
+
+      HashMatcher.new(hash)
+    when Array
+      ArrayMatcher.new(object.map { of(_1, matcher_cache:, expression_cache:) })
+    when Optional
+      matcher = of(object.value, matcher_cache:, expression_cache:)
+
+      OptionalMatcher.cache(matcher, matcher_cache)
+    else
+      EqualMatcher.cache(object, matcher_cache)
+    end
+  end
+
+  def self.cache(object)
+    build_session = Matcher.build_session
+    matcher_cache = MatcherCache.current(build_session)
+    expression_cache = ExpressionCache.current(build_session)
+
+    of(object, matcher_cache:, expression_cache:)
+  end
+
+  def self.parenthesize(matcher)
+    matcher_to_s = matcher.to_s
+
+    matcher_to_s = "(#{matcher_to_s})" if
+      case matcher
+      when ExpressionMatcher
+        !matcher.negated &&
+          matcher.expression.precedence > Call::OPERATOR_PRECEDENCE[:^]
+      when EqualMatcher, KindOfMatcher, RangeMatcher, RegexpMatcher,
+        ArrayMatcher, HashMatcher
+
+        false
+      else
+        matcher_to_s !~ /\A(~?\w+(\(.*\)|\[.*\])?|-> \{.*})\z/
+      end
+
+    matcher_to_s
+  end
+
+  def self.settings
+    Thread.current[:matcher_settings_stack] || {}
+  end
+
+  def self.with_settings(**settings)
+    stack = (Thread.current[:matcher_settings_stack] ||= HashStack.new)
+    stack.push(settings)
+
+    begin
+      yield
+    ensure
+      stack.pop(settings)
+      Thread.current[:matcher_settings_stack] = nil if stack.empty?
+    end
+  end
+
+  def self.session
+    Thread.current[:matcher_session]
+  end
+
+  def self.with_session(initial = {})
+    return yield if Thread.current[:matcher_session]
+
+    begin
+      Thread.current[:matcher_session] = initial
+
+      yield
+    ensure
+      Thread.current[:matcher_session] = nil
+    end
+  end
+
+  def self.build_session
+    Thread.current[:matcher_build_session]
+  end
+
+  def self.with_build_session(initial = {})
+    build_session = Thread.current[:matcher_build_session]
+
+    return yield build_session if build_session
+
+    begin
+      Thread.current[:matcher_build_session] = initial
+
+      yield initial
+    ensure
+      Thread.current[:matcher_build_session] = nil
+    end
+  end
+
+  Debug.init
+end
+
+require_relative "matcher/messages/message_rules"

metadata

@@ -0,0 +1,174 @@
+--- !ruby/object:Gem::Specification
+name: matchers
+version: !ruby/object:Gem::Version
+  version: 0.1.0.pre.1
+platform: ruby
+authors:
+- Rico Jasper
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'A DSL for building matchers that validate nested data structures. Ruby
+  literals like classes, ranges, regexps, arrays, and hashes are automatically converted
+  into matchers. Mismatches produce error trees with paths pointing to each failing
+  element.
+
+  '
+email:
+- jasper.rico@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/matcher.rb
+- lib/matcher/assertions.rb
+- lib/matcher/autoload.rb
+- lib/matcher/base.rb
+- lib/matcher/compatibility.rb
+- lib/matcher/debug.rb
+- lib/matcher/dsl/builder.rb
+- lib/matcher/dsl/chain.rb
+- lib/matcher/dsl/expression_dsl.rb
+- lib/matcher/dsl/matcher_dsl.rb
+- lib/matcher/dsl/optional.rb
+- lib/matcher/dsl/optional_chain.rb
+- lib/matcher/dsl/others.rb
+- lib/matcher/errors/and_error.rb
+- lib/matcher/errors/boolean_collector.rb
+- lib/matcher/errors/element_error.rb
+- lib/matcher/errors/empty_error.rb
+- lib/matcher/errors/error.rb
+- lib/matcher/errors/error_collector.rb
+- lib/matcher/errors/nested_error.rb
+- lib/matcher/errors/or_error.rb
+- lib/matcher/expression_cache.rb
+- lib/matcher/expression_labeler.rb
+- lib/matcher/expressions/array_expression.rb
+- lib/matcher/expressions/block.rb
+- lib/matcher/expressions/call.rb
+- lib/matcher/expressions/call_error.rb
+- lib/matcher/expressions/constant.rb
+- lib/matcher/expressions/expression.rb
+- lib/matcher/expressions/expression_walker.rb
+- lib/matcher/expressions/hash_expression.rb
+- lib/matcher/expressions/proc_expression.rb
+- lib/matcher/expressions/range_expression.rb
+- lib/matcher/expressions/recorder.rb
+- lib/matcher/expressions/rescue_last_error_expression.rb
+- lib/matcher/expressions/set_expression.rb
+- lib/matcher/expressions/string_expression.rb
+- lib/matcher/expressions/symbol_proc.rb
+- lib/matcher/expressions/variable.rb
+- lib/matcher/hash_stack.rb
+- lib/matcher/list.rb
+- lib/matcher/markers.rb
+- lib/matcher/matcher_cache.rb
+- lib/matcher/matchers/all_matcher.rb
+- lib/matcher/matchers/always_matcher.rb
+- lib/matcher/matchers/any_matcher.rb
+- lib/matcher/matchers/array_matcher.rb
+- lib/matcher/matchers/block_matcher.rb
+- lib/matcher/matchers/boolean_matcher.rb
+- lib/matcher/matchers/dig_matcher.rb
+- lib/matcher/matchers/each_matcher.rb
+- lib/matcher/matchers/each_pair_matcher.rb
+- lib/matcher/matchers/equal_matcher.rb
+- lib/matcher/matchers/equal_set_matcher.rb
+- lib/matcher/matchers/expression_matcher.rb
+- lib/matcher/matchers/filter_matcher.rb
+- lib/matcher/matchers/hash_matcher.rb
+- lib/matcher/matchers/imply_matcher.rb
+- lib/matcher/matchers/imply_some_matcher.rb
+- lib/matcher/matchers/index_by_matcher.rb
+- lib/matcher/matchers/inline_matcher.rb
+- lib/matcher/matchers/keys_matcher.rb
+- lib/matcher/matchers/kind_of_matcher.rb
+- lib/matcher/matchers/lazy_all_matcher.rb
+- lib/matcher/matchers/lazy_any_matcher.rb
+- lib/matcher/matchers/let_matcher.rb
+- lib/matcher/matchers/map_matcher.rb
+- lib/matcher/matchers/negated_array_matcher.rb
+- lib/matcher/matchers/negated_each_matcher.rb
+- lib/matcher/matchers/negated_each_pair_matcher.rb
+- lib/matcher/matchers/negated_imply_some_matcher.rb
+- lib/matcher/matchers/negated_matcher.rb
+- lib/matcher/matchers/negated_project_matcher.rb
+- lib/matcher/matchers/never_matcher.rb
+- lib/matcher/matchers/one_matcher.rb
+- lib/matcher/matchers/optional_matcher.rb
+- lib/matcher/matchers/parse_float_matcher.rb
+- lib/matcher/matchers/parse_integer_matcher.rb
+- lib/matcher/matchers/parse_iso8601_helper.rb
+- lib/matcher/matchers/parse_iso8601_matcher.rb
+- lib/matcher/matchers/parse_json_helper.rb
+- lib/matcher/matchers/parse_json_matcher.rb
+- lib/matcher/matchers/project_matcher.rb
+- lib/matcher/matchers/raises_matcher.rb
+- lib/matcher/matchers/range_matcher.rb
+- lib/matcher/matchers/reference_matcher.rb
+- lib/matcher/matchers/reference_matcher_collection.rb
+- lib/matcher/matchers/regexp_matcher.rb
+- lib/matcher/messages/expected_phrasing.rb
+- lib/matcher/messages/message.rb
+- lib/matcher/messages/message_builder.rb
+- lib/matcher/messages/message_rules.rb
+- lib/matcher/messages/namespaced_message_builder.rb
+- lib/matcher/messages/phrasing.rb
+- lib/matcher/messages/standard_message_builder.rb
+- lib/matcher/patterns/ast_mapping.rb
+- lib/matcher/patterns/capture_hole.rb
+- lib/matcher/patterns/constant_hole.rb
+- lib/matcher/patterns/hole.rb
+- lib/matcher/patterns/method_hole.rb
+- lib/matcher/patterns/pattern.rb
+- lib/matcher/patterns/pattern_building.rb
+- lib/matcher/patterns/pattern_capture.rb
+- lib/matcher/patterns/pattern_match.rb
+- lib/matcher/patterns/variable_hole.rb
+- lib/matcher/reporter.rb
+- lib/matcher/rules/message_factory.rb
+- lib/matcher/rules/message_rule.rb
+- lib/matcher/rules/message_rule_context.rb
+- lib/matcher/rules/rule_builder.rb
+- lib/matcher/rules/rule_set.rb
+- lib/matcher/rules/transform_builder.rb
+- lib/matcher/rules/transform_mapping.rb
+- lib/matcher/rules/transform_rule.rb
+- lib/matcher/state.rb
+- lib/matcher/testing.rb
+- lib/matcher/testing/error_builder.rb
+- lib/matcher/testing/error_checker.rb
+- lib/matcher/testing/error_testing.rb
+- lib/matcher/testing/pattern_testing.rb
+- lib/matcher/testing/pattern_testing_scope.rb
+- lib/matcher/undefined.rb
+- lib/matcher/utils.rb
+- lib/matcher/utils/mapping_utils.rb
+- lib/matcher/version.rb
+homepage: https://github.com/rjasper/ruby-matchers
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rjasper/ruby-matchers
+  source_code_uri: https://github.com/rjasper/ruby-matchers/tree/pre
+  changelog_uri: https://github.com/rjasper/ruby-matchers/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Composable data structure matchers with error reporting
+test_files: []