matchers 0.1.0.pre.test

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.test"
+end

data/lib/matcher.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+require_relative "matcher/version"
+
+require 'singleton'
+require 'forwardable'
+
+module Matcher
+  module NoMatcher end
+  module NoExpression end
+  module NoKey end
+end
+
+require_relative 'matcher/once_before'
+require_relative 'matcher/expressions/expression_building'
+require_relative 'matcher/matchers/matcher_building'
+require_relative 'matcher/patterns/pattern_building'
+require_relative 'matcher/utils/mapping_utils'
+
+require_relative 'matcher/assertions'
+require_relative 'matcher/base'
+require_relative 'matcher/builder'
+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/optional_chain'
+require_relative 'matcher/chain'
+require_relative 'matcher/reporter'
+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/markers/optional'
+require_relative 'matcher/markers/others'
+
+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_matcher'
+require_relative 'matcher/matchers/parse_json_matcher'
+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.
+    UNDEFINED == object
+  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
+  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 a value into a matcher
+  #
+  # The conversion depends on the type of the value:
+  # - +Module+/+Class+ -> KindOfMatcher
+  # - +Range+ -> RangeMatcher
+  # - +Regexp+ -> RegexpMatcher
+  # - +Hash+ -> HashMatcher
+  # - +Array+ -> ArrayMatcher
+  # - +Expression+ -> ExpressionMatcher
+  # - +Proc+ -> BlockMatcher
+  # - +Optional+ -> OptionalMatcher
+  # - other -> EqualMatcher
+  # @example
+  #   Matcher.of(String).class  # => Matcher::KindOfMatcher
+  #   Matcher.of(1..10).class   # => Matcher::RangeMatcher
+  #   Matcher.of(/foo/).class   # => Matcher::RegexpMatcher
+  # @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,167 @@
+--- !ruby/object:Gem::Specification
+name: matchers
+version: !ruby/object:Gem::Version
+  version: 0.1.0.pre.test
+platform: ruby
+authors:
+- Rico Jasper
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-03-14 00:00:00.000000000 Z
+dependencies: []
+description: 
+email:
+- jasper.rico@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/matcher.rb
+- lib/matcher/assertions.rb
+- lib/matcher/base.rb
+- lib/matcher/builder.rb
+- lib/matcher/chain.rb
+- lib/matcher/debug.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_building.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/optional.rb
+- lib/matcher/markers/others.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/matcher_building.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_matcher.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/once_before.rb
+- lib/matcher/optional_chain.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-matcher
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rjasper/ruby-matcher
+  source_code_uri: https://github.com/rjasper/ruby-matcher
+  changelog_uri: https://github.com/rjasper/ruby-matcher/blob/master/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key: 
+specification_version: 4
+summary: A matcher library.
+test_files: []