matchers 0.1.0.pre.1

data/lib/matcher/matchers/project_matcher.rb

@@ -0,0 +1,72 @@
+# 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 MatcherDsl
+    ##
+    # 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)
+      if !Matcher.undefined?(expression) && !projections.empty?
+        raise "cannot mix project(expression) ^ matcher and " \
+          "project(expression => matcher)"
+      end
+
+      unless Matcher.undefined?(expression)
+        return Chain.new { project(expression => _1) }
+      end
+
+      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,131 @@
+# 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(error)
+      case error
+      when CallError
+        error.cause
+      else
+        error
+      end
+    end
+  end
+
+  module MatcherDsl
+    ##
+    # 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.fetch(:foo) }
+    #   # rescue non-standard exceptions
+    #   raises(_.call, rescue: Exception)
+    # @overload raises(expression, matcher, message: UNDEFINED, rescue: StandardError)
+    #   Matches error raised from expression.
+    #   @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, &)
+    #   Matches error raised from block.
+    #   @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,50 @@
+# 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?
+        unless @negated
+          state.errors << state.expected.comparable_to(@range.begin)
+        end
+
+        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,213 @@
+# frozen_string_literal: true
+
+module Matcher
+  ##
+  # Build recursive matchers.
+  #   m = Matcher.build do
+  #     refs[:list] = {
+  #       head: Integer,
+  #       tail: optional(refs[:list]),
+  #     }
+  #   end
+  #
+  #   m.match?({ head: 1, tail: { head: 2, tail: nil } })
+  #   # => true
+  #   m.match({ head: 1, tail: { head: "two", tail: nil } })
+  #   # > root[:tail][:head]: expected a kind of Integer but got "two"
+  #
+  # == Allow cyclic references
+  #
+  # By default, reference matchers won't allow visiting the same object twice.
+  # However, for structures like graphs we can enable cyclic mode. When the
+  # reference matcher revisits an object it will assume a new match would be
+  # the same as the first match result and skip traversal.
+  #
+  # Also note, that when caching is enabled values won't be passed to the target
+  # matcher to ensure results are reproducible for the same object.
+  #
+  #   m = Matcher.build do
+  #     refs[:vertex] = {
+  #       name: String,
+  #       edges: each(refs[:edge, cyclic: true]),
+  #     }
+  #
+  #     refs[:edge] = {
+  #       weight: Integer,
+  #       destination: refs[:vertex, cyclic: true],
+  #     }
+  #
+  #     { vertices: each(refs[:vertex]) }
+  #   end
+  #
+  #   a = { name: 'a', edges: [] }
+  #   b = { name: 'b', edges: [] }
+  #   c = { name: 'c', edges: [] }
+  #
+  #   a[:edges] << { weight: 1, destination: b }
+  #   b[:edges] << { weight: 2, destination: c }
+  #   c[:edges] << { weight: "3", destination: a }
+  #
+  #   graph = { vertices: [a, b, c] }
+  #
+  #   m.match(graph)
+  #   # > root[:vertices][0][:edges][0][:destination][:edges][0][:destination]~
+  #   #   [:edges][0][:weight]: expected a kind of Integer but got "3"
+  #   # > root[:vertices][1]: actual has already failed before
+  #   # > root[:vertices][2]: actual has already failed before
+  #
+  # == Disable cache
+  #
+  # By default, results are cached for each object during a match session.
+  # However, if a result depends not only on the actual value but also on other
+  # passed values then the cache may return an incorrect result. See the example
+  # below:
+  #
+  #   m = Matcher.build do
+  #     refs[:foo] = _ == vars[:a]
+  #
+  #     [
+  #       let(a: 1) ^ refs[:foo],
+  #       let(a: 2) ^ refs[:foo],
+  #     ]
+  #   end
+  #
+  #   # should only match [1, 2] but refs[:foo] caches result for 1 as valid:
+  #
+  #   m.match?([1, 1])
+  #   # => true, but shouldn't
+  #
+  #   # disable cache when matching result depends on other values than actual:
+  #
+  #   m = Matcher.build do
+  #     refs[:foo, { cache: false }] = _ == vars[:a]
+  #
+  #     [
+  #       let(a: 1) ^ refs[:foo],
+  #       let(a: 2) ^ refs[:foo],
+  #     ]
+  #   end
+  #
+  #   m.match([1, 1])
+  #   # > root[1]: expected actual == a but got 1 == 2
+  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)
+        if @negated == @cyclic
+          state.errors << state.report.namespace(:reference).cyclic
+        end
+
+        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 MatcherDsl
+    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(DEFAULT_OPTIONS) { |_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,86 @@
+# 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 MatcherDsl
+    ##
+    # 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)
+    #   # without matcher passes if regular expression matches
+    #   regexp(/x=\d+/)
+    # @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