matchers 0.1.0.pre.test

data/lib/matcher/matchers/parse_iso8601_matcher.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Matcher
+  class ParseIso8601Matcher < Base
+    extend OnceBefore
+
+    def initialize(matcher, negated: false)
+      super()
+
+      @matcher = negated ? ~matcher : matcher
+      @original_matcher = matcher
+      @negated = negated
+    end
+
+    once_before :initialize do
+      require 'time'
+    end
+
+    def negate
+      ParseIso8601Matcher.new(@original_matcher, negated: !@negated)
+    end
+
+    def validate(state, &)
+      actual = state.actual
+
+      unless actual.is_a?(String)
+        state.errors << state.expected.kind_of(String) unless @negated
+        return
+      end
+
+      value = Time.iso8601(actual)
+
+      if @matcher.is_a?(NeverMatcher)
+        state.errors << state.expected.not.valid_format(:iso8601)
+        return
+      end
+
+      result = yield(@matcher, value)
+
+      return if result.valid?
+
+      time_of = Call.new(Constant.new(Time), :iso8601, [Variable.actual])
+      state.errors[time_of] << result
+    rescue ArgumentError
+      state.errors << state.expected.valid_format(:iso8601) unless @negated
+    end
+
+    def to_s
+      prefix = @negated ? '~' : ''
+
+      return "#{prefix}iso8601_format" if @original_matcher.is_a?(AlwaysMatcher)
+
+      "#{prefix}parse_iso8601(#{@original_matcher})"
+    end
+  end
+
+  module MatcherBuilding
+    ##
+    # Parses ISO 8601 time and matches with given matcher
+    # @example
+    #   # matches "1999-12-31T23:59:00+01:00"
+    #   parse_iso8601(_ < expr { Time.now })
+    #   # alternatively:
+    #   parse_iso8601 ^ (_ < expr { Time.now })
+    #   # without matcher matches any valid ISO 8601 string
+    #   parse_iso8601
+    # @overload parse_iso8601(matcher)
+    #   @param matcher [Base]
+    #   @return [ParseIso8601Matcher]
+    # @overload parse_iso8601
+    #   @return [OptionalChain<ParseIso8601Matcher>]
+    # @see #iso8601_format
+    def parse_iso8601(matcher = UNDEFINED)
+      return Chain.new { parse_iso8601(_1) }.optional if
+        Matcher.undefined?(matcher)
+
+      matcher = matcher_of(matcher)
+
+      ParseIso8601Matcher.new(matcher)
+    end
+
+    ##
+    # Matches valid ISO 8601 strings
+    # @example
+    #   # matches { timestamp: "2025-11-16T21:13:33+01:00" }
+    #   { timestamp: iso8601_format }
+    # @return [ParseIso8601Matcher]
+    def iso8601_format
+      @iso8601_format ||= ParseIso8601Matcher.new(AlwaysMatcher.instance)
+    end
+  end
+end

data/lib/matcher/matchers/parse_json_matcher.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Matcher
+  class ParseJsonMatcher < Base
+    extend OnceBefore
+
+    def initialize(matcher, json_options: nil, negated: false)
+      super()
+
+      @matcher = negated ? ~matcher : matcher
+      @original_matcher = matcher
+      @json_options = json_options
+      @negated = negated
+    end
+
+    once_before :initialize do
+      require 'json'
+    end
+
+    def negate
+      ParseJsonMatcher.new(@original_matcher, json_options: @json_options, negated: !@negated)
+    end
+
+    def validate(state)
+      actual = state.actual
+
+      unless actual.is_a?(String)
+        state.errors << state.expected.kind_of(String) unless @negated
+        return
+      end
+
+      value = JSON.parse(actual, **@json_options)
+
+      if @matcher.is_a?(NeverMatcher)
+        state.errors << state.expected.not.valid_format(:json)
+        return
+      end
+
+      result = yield(@matcher, value)
+
+      return if result.valid?
+
+      parse_json = Call.new(Constant.new(JSON), :parse, [Variable.actual])
+      state.errors[parse_json] << result
+    rescue JSON::ParserError
+      state.errors << state.expected.valid_format(:json) unless @negated
+    end
+
+    def to_s
+      prefix = @negated ? '~' : ''
+
+      return "#{prefix}json_format" if @original_matcher.is_a?(AlwaysMatcher)
+
+      "#{prefix}parse_json(#{@original_matcher})"
+    end
+  end
+
+  module MatcherBuilding
+    ##
+    # Parses JSON and matches with given matcher
+    # @example
+    #   # matches '{"foo":42}'
+    #   parse_json({ "foo" => Integer })
+    #   # alternatively:
+    #   parse_json ^ { "foo" => Integer }
+    #   # without matcher matches any valid JSON string
+    #   parse_json
+    # @overload parse_json(matcher, **json_options)
+    #   @param matcher [Base]
+    #   @return [ParseJsonMatcher]
+    # @overload parse_json(**json_options)
+    #   @return [OptionalChain<ParseJsonMatcher>]
+    # @see #json_format
+    def parse_json(matcher = UNDEFINED, **)
+      return Chain.new { parse_json(_1, **) }.optional if
+        Matcher.undefined?(matcher)
+
+      matcher = matcher_of(matcher)
+      json_options = {}.merge(**)
+      json_options = nil if json_options.empty?
+
+      ParseJsonMatcher.new(matcher, json_options:)
+    end
+
+    ##
+    # Matches valid JSON strings
+    # @example
+    #   # matches { payload: '{"foo":42}' }
+    #   { payload: json_format }
+    # @return [ParseJsonMatcher]
+    def json_format
+      @json_format ||= ParseJsonMatcher.new(AlwaysMatcher.instance)
+    end
+  end
+end

data/lib/matcher/matchers/project_matcher.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Matcher
+  class ProjectMatcher < Base
+    def initialize(expression, matcher)
+      super()
+
+      @expression = expression
+      @matcher = matcher
+    end
+
+    def negate
+      NegatedProjectMatcher.new(@expression, @matcher)
+    end
+
+    def validate(state)
+      begin
+        result = @expression.evaluate(state.values)
+      rescue CallError => e
+        # rescuing here instead of method so we won't catch from yield
+        state.errors << e.message_for_errors(state.actual)
+        return
+      end
+
+      state.errors[@expression] << yield(@matcher, result)
+    end
+
+    def to_s
+      "project(#{@expression} => #{@matcher})"
+    end
+  end
+
+  module MatcherBuilding
+    ##
+    # Matches the value of an expression
+    # @example
+    #   # matches "5"
+    #   project(_.to_i => _ < 10)
+    #   # alternatively:
+    #   project(_.to_i) ^ (_ < 10)
+    #   # project multiple expressions
+    #   project(
+    #     _.foo => 1,
+    #     _.bar => 2,
+    #   )
+    # @overload project(expression => matcher)
+    #   @return [ProjectMatcher]
+    # @overload project(expression)
+    #   @return [Chain<ProjectMatcher>]
+    # @overload project(**projections)
+    #   @return [AllMatcher<ProjectMatcher>]
+    def project(expression = UNDEFINED, **projections)
+      raise 'cannot mix project(expression) ^ matcher and project(expression => matcher)' if
+        !Matcher.undefined?(expression) && !projections.empty?
+
+      return Chain.new { project(expression => _1) } unless Matcher.undefined?(expression)
+
+      project_matchers = projections.map do |e, m|
+        e = expression_of(e)
+        m = matcher_of(m)
+
+        ProjectMatcher.new(e, m)
+      end
+
+      all(*project_matchers)
+    end
+  end
+end

data/lib/matcher/matchers/raises_matcher.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Matcher
+  class RaisesMatcher < Base
+    def initialize(
+      expression,
+      matcher,
+      negated: false,
+      rescue_exception: StandardError
+    )
+      super()
+
+      @expression = expression
+      @matcher = negated ? ~matcher : matcher
+      @original_matcher = matcher
+      @negated = negated
+      @rescue_exception = rescue_exception
+    end
+
+    def negate
+      RaisesMatcher.new(
+        @expression,
+        @original_matcher,
+        negated: !@negated,
+        rescue_exception: @rescue_exception,
+      )
+    end
+
+    def validate(state)
+      @expression.evaluate(state.values)
+
+      return if @negated
+
+      given = @expression.given_for(state.values)
+      state.errors << state.expected.namespace(:expression).raising(@expression, @rescue_exception, given)
+    rescue @rescue_exception => e
+      state.errors[rescue_last_error] << yield(@matcher, unwrap_exception(e))
+    end
+
+    def to_s
+      "#{'~' if @negated}raises(#{@expression}, #{@original_matcher})"
+    end
+
+    private
+
+    def rescue_last_error
+      @rescue_last_error ||= RescueLastErrorExpression.new(@expression)
+    end
+
+    def unwrap_exception(e)
+      case e
+      when CallError
+        e.cause
+      else
+        e
+      end
+    end
+  end
+
+  module MatcherBuilding
+    ##
+    # Matches raised error
+    # @example
+    #   # matches {} (because fetch raises KeyError)
+    #   raises(_.fetch(:foo), KeyError)
+    #   # alternatively:
+    #   raises(_.fetch(:foo)) ^ KeyError
+    #   # match error message
+    #   raises(_.call, message: /something went wrong/)
+    #   # pass block instead of expression
+    #   raises(NoMethodError) { |x| x.foo }
+    #   # rescue non-standard exceptions
+    #   raises(_.call, rescue: Exception)
+    # @overload raises(expression, matcher, message: UNDEFINED, rescue: StandardError)
+    #   @param expression [Expression]
+    #   @param matcher [Base] matcher for error
+    #   @param message [Base] matcher for message
+    #   @param rescue [Class] exception class to rescue
+    #   @return [RaisesMatcher]
+    # @overload raises(matcher, message: UNDEFINED, rescue: StandardError)
+    #   @param matcher [Base] matcher for error
+    #   @param message [Base] matcher for message
+    #   @param rescue [Class] exception class to rescue
+    #   @yield actual
+    #   @return [OptionalChain<RaisesMatcher>]
+    def raises(
+      expression_or_matcher = UNDEFINED,
+      matcher = UNDEFINED,
+      message: UNDEFINED,
+      rescue: StandardError,
+      &block
+    )
+      no_arg1 = Matcher.undefined?(expression_or_matcher)
+      no_arg2 = Matcher.undefined?(matcher)
+
+      if no_arg1 == no_arg2 && no_arg1 ^ block_given?
+        raise ArgumentError, 'both expression and block given' unless no_arg1
+
+        raise ArgumentError, 'neither expression nor block given'
+      end
+
+      if block_given?
+        expression = ProcExpression.new(block)
+        matcher = expression_or_matcher
+      else
+        expression = expression_of(expression_or_matcher)
+      end
+
+      return Chain.new { raises(expression, _1, message:, rescue:) }.optional if
+        Matcher.undefined?(matcher)
+
+      matcher = matcher_of(matcher)
+
+      unless Matcher.undefined?(message)
+        @raises_message_call ||= expression_of(Call.new(Variable.actual, :message))
+        message_matcher = matcher_of(message)
+
+        matcher &= ProjectMatcher.new(@raises_message_call, message_matcher)
+      end
+
+      RaisesMatcher.new(expression, matcher, rescue_exception: { rescue: }[:rescue])
+    end
+  end
+end

data/lib/matcher/matchers/range_matcher.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Matcher
+  class RangeMatcher < Base
+    def self.cache(range, matcher_cache = MatcherCache.current)
+      return new(range) unless matcher_cache
+
+      (matcher_cache.range_matchers ||= {})[range] ||= new(range)
+    end
+
+    def initialize(range, negated: false)
+      super()
+
+      @range = range
+      @negated = negated
+    end
+
+    def negate
+      RangeMatcher.new(@range, negated: !@negated)
+    end
+
+    def validate(state)
+      limit = @range.begin || @range.end
+
+      if (limit <=> state.actual).nil?
+        state.errors << state.expected.comparable_to(@range.begin) unless @negated
+        return
+      end
+
+      return if @range.include?(state.actual) ^ @negated
+
+      state.errors << state.expected.not_if(@negated).between(
+        @range.begin,
+        @range.end,
+        exclude_end: @range.exclude_end?,
+      )
+    end
+
+    def to_s
+      if @negated
+        "neg(#{@range})"
+      else
+        @range.to_s
+      end
+    end
+  end
+end

data/lib/matcher/matchers/reference_matcher.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Matcher
+  class ReferenceMatcher < Base
+    Settings = Struct.new(:target, :cache)
+
+    def initialize(key, settings, cyclic: nil, negated: false, session_key: object_id)
+      super()
+
+      @key = key
+      @settings = settings
+      @cyclic = cyclic
+      @negated = negated
+      @session_key = session_key
+    end
+
+    def negate
+      ReferenceMatcher.new(@key, @settings, cyclic: @cyclic, negated: !@negated, session_key: @session_key)
+    end
+
+    def validate(state)
+      actual = state.actual
+      sess = class_session
+      depth = sess[:depth]
+      depth = depth ? depth + 1 : 1
+      sess[:depth] = depth
+
+      if depth > Matcher.max_reference_depth
+        state.errors << "match level too deep: #{depth}"
+        return
+      end
+
+      unless visited.add?(actual.object_id)
+        state.errors << state.report.namespace(:reference).cyclic if @negated == @cyclic
+
+        return
+      end
+
+      unless cache?
+        state.errors << yield(target)
+        return
+      end
+
+      cache = (sess[:cache] ||= {})
+      cache_key = [@key, actual.object_id]
+      cached_result = cache[cache_key]
+
+      if cached_result.nil?
+        # If @cyclic then call #match instead of yield. We disallow passing
+        # previous values for cyclic reference matchers. #match will create a
+        # new values stack.
+        target_errors = @cyclic ? target.match(actual) : yield(target)
+        cache[cache_key] = @negated ^ target_errors.valid?
+
+        state.errors << target_errors
+      elsif @negated == cached_result
+        state.errors << state.report.namespace(:reference).failed_from_cache
+      end
+    ensure
+      sess[:depth] = depth - 1
+    end
+
+    def to_s
+      "#{'~' if @negated}refs[#{@key.inspect}]"
+    end
+
+    private
+
+    def cache?
+      return @cache if defined? @cache
+
+      @cache = @settings[@key].cache
+    end
+
+    def visited
+      session(@session_key)[:visited] ||= Set.new
+    end
+
+    def target
+      return @target if defined? @target
+
+      pair = @settings[@key].target
+
+      raise "No target for #{@key.inspect}" unless pair
+
+      @target = if @negated
+        pair[1] ||= ~pair[0]
+      else
+        pair[0]
+      end
+    end
+  end
+
+  module MatcherBuilding
+    def refs?
+      !@refs.nil?
+    end
+
+    ##
+    # Returns the reference matcher collection for recursive matchers
+    # @example
+    #   refs[:list] = {
+    #     head: Integer,
+    #     tail: optional(refs[:list]),
+    #   }
+    # @return [ReferenceMatcherCollection]
+    def refs
+      @refs ||= ReferenceMatcherCollection.new(self)
+    end
+  end
+end

data/lib/matcher/matchers/reference_matcher_collection.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Matcher
+  class ReferenceMatcherCollection
+    include NoMatcher
+    include NoExpression
+    include NoKey
+
+    attr_reader :last_object_id, :last_matcher
+
+    def initialize(builder)
+      @settings = {}
+      @last_object_id = nil
+      @last_matcher = nil
+      @used = Set.new
+      @builder = builder
+    end
+
+    def finalize
+      @settings.freeze
+
+      assigned = @settings.each_key.to_set
+      missing = @used - assigned
+      unused = assigned - @used
+
+      raise "undefined ref: #{missing.join(', ')}" unless missing.empty?
+      raise "unused ref: #{unused.join(', ')}" unless unused.empty?
+    end
+
+    def [](key, cyclic: false)
+      @used << key
+
+      ReferenceMatcher.new(key, @settings, cyclic:)
+    end
+
+    DEFAULT_OPTIONS = { cache: true }.freeze
+
+    def []=(key, matcher_or_options, matcher = UNDEFINED)
+      raise "Cannot reassign reference: #{key.inspect}" if @settings.key?(key)
+
+      if Matcher.undefined?(matcher)
+        options = DEFAULT_OPTIONS
+        matcher = matcher_or_options
+      else
+        options = matcher_or_options.merge(cache: true) { |_k, l, r| l }
+      end
+
+      @last_object_id = matcher.__id__
+      matcher = @builder.matcher_of(matcher)
+      @last_matcher = matcher
+
+      settings = (@settings[key] ||= ReferenceMatcher::Settings.new)
+      settings.target = [matcher, nil]
+      settings.cache = options[:cache]
+    end
+  end
+end

data/lib/matcher/matchers/regexp_matcher.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Matcher
+  class RegexpMatcher < Base
+    def self.cache(pattern, matcher_cache = MatcherCache.current)
+      return new(pattern) unless matcher_cache
+
+      (matcher_cache.regexp_matchers ||= {})[pattern] ||= new(pattern)
+    end
+
+    def initialize(pattern, matcher = AlwaysMatcher.instance, negated: false)
+      super()
+
+      @pattern = pattern
+      @matcher = negated ? ~matcher : matcher
+      @original_matcher = matcher
+      @negated = negated
+    end
+
+    def negate
+      RegexpMatcher.new(@pattern, @original_matcher, negated: !@negated)
+    end
+
+    def validate(state)
+      unless state.actual.is_a?(String)
+        state.errors << state.expected.kind_of(String) unless @negated
+        return
+      end
+
+      if @original_matcher == AlwaysMatcher.instance
+        state.errors << state.expected.not_if(@negated).matching(@pattern) if
+          @pattern.match?(state.actual) == @negated
+      else
+        match = @pattern.match(state.actual)
+
+        if match
+          state.errors[match_pattern_call] << yield(@matcher, match)
+        else
+          state.errors << state.expected.matching(@pattern) unless @negated
+        end
+      end
+    end
+
+    def match_pattern_call
+      @match_pattern_call ||=
+        Call.new(Variable.actual, :match, [Constant.new(@pattern)])
+    end
+
+    def to_s
+      if @original_matcher == AlwaysMatcher.instance
+        if @negated
+          "neg(#{@pattern.inspect})"
+        else
+          @pattern.inspect
+        end
+      else
+        "#{'~' if @negated}regexp(#{@pattern.inspect}, #{@original_matcher})"
+      end
+    end
+  end
+
+  module MatcherBuilding
+    ##
+    # Matches regular expression and passes MatchData to matcher
+    # @example
+    #   # matches "x=5" but not "y=5" or "x=20"
+    #   regexp(/x=(\d+)/, project(_[1].to_i => 0..10))
+    #   # alternatively:
+    #   regexp(/x=(\d+)/) ^ project(_[1].to_i => 0..10)
+    # @overload regexp(pattern, matcher)
+    #   @param pattern [Regexp]
+    #   @param matcher [Base]
+    #   @return [RegexpMatcher]
+    # @overload regexp(pattern)
+    #   @param pattern [Regexp]
+    #   @return [OptionalChain<RegexpMatcher>]
+    def regexp(pattern, matcher = UNDEFINED)
+      return Chain.new { regexp(pattern, _1) }.optional if
+        Matcher.undefined?(matcher)
+
+      RegexpMatcher.new(pattern, matcher_of(matcher))
+    end
+  end
+end