matchers 0.1.0.pre.test

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dd26d76a69e586fdc17822b522ad0a1761f2ad87526ecbf818018f7505b52620
+  data.tar.gz: 4c621e0c1f678c9846b9dfdffddc089db092b797eddc9db8b919ad496a2d8598
+SHA512:
+  metadata.gz: fe00a5777c09a4d01a904c0337131474c3c77cee05b4b0a31a5c3ff5a8a915c74164d78102880226062cbe2ad6c00d8b5b3430f9521bdd44f38aa23225091509
+  data.tar.gz: 5492feb0ec66aab747ef9d32f9d5c3c5f66eb9c357533c979e1ed57909358337cebdd7a0ef3aec6cb5f54fd13ee1fdd30ba2547111dd5412d0cf052f72de2ff4

data/lib/matcher/assertions.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Matcher
+  module Assertions
+    def assert_structure(actual, &)
+      errors = Matcher.build(&).match(actual)
+
+      # rubocop:disable Minitest/AssertWithExpectedArgument
+      assert(false, <<~TEXT.chomp) unless errors.valid?
+        For object:
+
+        #{actual.inspect}
+
+        The following conditions were not satisfied:
+
+        #{Reporter.report(errors)}
+      TEXT
+      # rubocop:enable Minitest/AssertWithExpectedArgument
+    end
+  end
+end

data/lib/matcher/base.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Matcher
+  class Base
+    include NoExpression
+    include NoKey
+
+    ##
+    # Negates this matcher
+    def ~
+      matcher_cache = MatcherCache.current
+
+      return negate unless matcher_cache
+
+      cache = (matcher_cache.negated_matchers ||= {}.compare_by_identity)
+      negated = cache[self]
+
+      unless negated
+        negated = negate
+        cache[self] = negated
+        cache[negated] = self
+      end
+
+      negated
+    end
+
+    def negate
+      NegatedMatcher.new(self)
+    end
+    protected :negate
+
+    ##
+    # Combines with matcher to AnyMatcher
+    # @param matcher
+    # @return [AnyMatcher]
+    # @see MatcherBuilding#any
+    def +(matcher)
+      matcher = Matcher.cache(matcher)
+
+      matchers = if matcher.is_a?(AnyMatcher)
+        [self].concat(matcher.matchers)
+      else
+        [self, matcher]
+      end
+
+      AnyMatcher.new(matchers)
+    end
+
+    ##
+    # Combines with matcher to AllMatcher
+    # @param matcher
+    # @return [AllMatcher]
+    # @see MatcherBuilding#all
+    def *(matcher)
+      matcher = Matcher.cache(matcher)
+
+      matchers = if matcher.is_a?(AllMatcher)
+        [self].concat(matcher.matchers)
+      else
+        [self, matcher]
+      end
+
+      AllMatcher.new(matchers)
+    end
+
+    ##
+    # Combines with matcher to LazyAnyMatcher
+    # @param matcher
+    # @return [LazyAnyMatcher]
+    # @see MatcherBuilding#lazy_any
+    def |(matcher)
+      matcher = Matcher.cache(matcher)
+
+      matchers = if matcher.is_a?(LazyAnyMatcher)
+        [self].concat(matcher.matchers)
+      else
+        [self, matcher]
+      end
+
+      LazyAnyMatcher.new(matchers)
+    end
+
+    ##
+    # Combines with matcher to LazyAllMatcher
+    # @param matcher
+    # @return [LazyAllMatcher]
+    # @see MatcherBuilding#lazy_all
+    def &(matcher)
+      matcher = Matcher.cache(matcher)
+
+      matchers = if matcher.is_a?(LazyAllMatcher)
+        [self].concat(matcher.matchers)
+      else
+        [self, matcher]
+      end
+
+      LazyAllMatcher.new(matchers)
+    end
+
+    ##
+    # Implies another matcher
+    # @param matcher
+    # @return [ImplyMatcher]
+    # @see MatcherBuilding#imply
+    def >>(matcher)
+      ImplyMatcher.new(self, Matcher.cache(matcher))
+    end
+
+    StackData = Struct.new(:actual, :vals, :errors)
+
+    ##
+    # Returns +true+ if actual matches, +false+ otherwise
+    # @example
+    #   Matcher.build { Integer }.match?(42) # => true
+    # @param actual the value to match against
+    # @param ** values
+    # @return [Boolean]
+    def match?(actual, **)
+      match_helper(true, actual:, **).valid?
+    end
+    alias === match?
+
+    ##
+    # Returns an error tree describing all mismatches
+    # @example
+    #   errors = Matcher.build { Integer }.match("foo")
+    #   puts Matcher::Reporter.report(errors)
+    #   # > root: expected a kind of Integer but got "foo"
+    # @param actual the value to match against
+    # @param ** values
+    # @return [Error]
+    def match(actual, **)
+      match_helper(false, actual:, **)
+    end
+
+    def match_helper(boolean, **)
+      hash_stack = HashStack.new
+
+      invoke = lambda do |matcher, act = UNDEFINED, **kwargs|
+        state = State.new(hash_stack, boolean:)
+        kwargs[:actual] = act unless Matcher.undefined?(act)
+
+        hash_stack.push(kwargs)
+
+        catch(:mismatch) do
+          matcher.validate(state, &invoke)
+        end
+
+        hash_stack.pop(kwargs)
+
+        state.result
+      end
+
+      Matcher.with_session do
+        invoke.call(self, **)
+      end
+    end
+    private :match_helper
+
+    def validate(state)
+      raise NotImplementedError
+    end
+    protected :validate
+
+    def inspect
+      to_s
+    end
+
+    protected
+
+    ##
+    # Stores information for this matcher instance during match time.
+    def session(key = object_id)
+      Matcher.session[key] ||= {}
+    end
+
+    ##
+    # Stores information for this matcher class during match time.
+    def self.session
+      Matcher.session[self] ||= {}
+    end
+
+    ##
+    # Stores information for this matcher's class during match time.
+    def class_session
+      self.class.session
+    end
+  end
+end

data/lib/matcher/builder.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Matcher
+  class Builder
+    include ExpressionBuilding
+    include MatcherBuilding
+
+    def initialize(outside, build_session: Matcher.build_session)
+      ExpressionBuilding.init(self, build_session)
+
+      @outside = outside
+      @matcher_cache = MatcherCache.current(build_session)
+    end
+
+    ##
+    # Turns a matchable value into a matcher
+    # @example
+    #   of(String).class # => Matcher::KindOfMatcher
+    #   of(String) & !_.empty? # matches non-empty strings
+    # @param value
+    # @return [Base]
+    def matcher_of(value)
+      Matcher.of(
+        value,
+        matcher_cache: @matcher_cache,
+        expression_cache: @expression_cache,
+      )
+    end
+    alias of matcher_of
+
+    ##
+    # Accesses the outside context within a build block
+    # @example
+    #   # access instance variables or methods from the enclosing scope
+    #   Matcher.build do
+    #     [outside { @ivar }, outside.my_method]
+    #   end
+    # @return [Object] the outside context
+    def outside(&)
+      if block_given?
+        @outside.instance_eval(&)
+      else
+        @outside
+      end
+    end
+
+    ##
+    # Negates a matcher
+    # @example
+    #   # matches anything except 1
+    #   neg(1)
+    #   # alternatively:
+    #   ~equal(1)
+    # @param matcher
+    # @return [Base]
+    # @see Base#~
+    def neg(matcher)
+      ~matcher_of(matcher)
+    end
+
+    ##
+    # Matches given matcher but not +nil+
+    # @example
+    #   present(my_value)
+    # @param matcher
+    # @return [AllMatcher]
+    def present(matcher)
+      AllMatcher.new([
+        ~equal(nil),
+        matcher_of(matcher),
+      ])
+    end
+  end
+end

data/lib/matcher/chain.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Matcher
+  class Chain
+    include NoMatcher
+    include NoExpression
+    include NoKey
+
+    def initialize(negated: false, &block)
+      @block = block
+      @negated = negated
+    end
+
+    def ~
+      Chain.new(negated: !@negated, &@block)
+    end
+
+    ##
+    # Chains this with a matcher or another chain
+    #
+    # Many helpers return a Chain that accepts a child matcher via +^+.
+    # Chains can also be composed: +each ^ map(_.to_i) ^ (_ > 0)+.
+    # @example
+    #   each ^ Integer
+    #   map(_.to_i) ^ [1, 2]
+    #   filter(_.odd?) ^ [1, 3, 5]
+    # @param operand matcher or chain
+    # @return [Base]
+    def ^(operand)
+      if !Recorder.recorder?(operand) && operand.is_a?(Chain)
+        Chain.new { @block.call(operand ^ _1) }
+      else
+        matcher = Matcher.cache(operand)
+        result = @block.call(matcher)
+        result = ~result if @negated
+        result
+      end
+    end
+
+    def optional(fallback = AlwaysMatcher.instance)
+      OptionalChain.new(self, fallback)
+    end
+  end
+
+  module MatcherBuilding
+    ##
+    # Reduces multiple chains to one
+    # @example
+    #   chain(let(limit: 10), map(_.compact), filter(_.even?), _ < vars[:limit])
+    #   # instead of
+    #   let(limit: 10) ^ map(_.compact) ^ filter(_.even?) ^ (_ < vars[:limit])
+    #   # which is equivalent to
+    #   let({ limit: 10 }, map(_.compact, filter(_.even?, _ < vars[:limit])))
+    # @param *chains
+    # @return [Chain]
+    def chain(*chains)
+      chains.reduce(:^)
+    end
+  end
+end

data/lib/matcher/debug.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Matcher
+  module Debug
+    def self.enable
+      init(force: true)
+    end
+
+    DEBUGGERS = %w[/bin/irb: ruby-debug-ide].freeze
+
+    def self.init(force: false)
+      return if @initialized
+
+      main_caller = caller[-1]
+
+      return if !force && DEBUGGERS.none? { main_caller.include?(_1) }
+
+      Recorder.prepend(ExpressionRecorderDebug)
+      @initialized = true
+    end
+
+    def self.debugging?(last_caller)
+      %w[puts p].any? { last_caller.end_with?(":in `#{_1}'") } ||
+        last_caller.include?('ruby-debug-ide')
+    end
+  end
+
+  module ExpressionRecorderDebug
+    private
+
+    def method_missing(method, *args, **kwargs, &block)
+      if Debug.debugging?(caller[0])
+        return @expression.to_s if %i[to_s inspect].include?(method)
+
+        return Object.instance_method(method)
+          .bind_call(self, *args, **kwargs, &block)
+      end
+
+      super
+    end
+
+    def respond_to_missing?(method, _include_private = false)
+      return Object.instance_methods.include?(method) if Debug.debugging?(caller[0])
+
+      super
+    end
+  end
+end

data/lib/matcher/errors/and_error.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Matcher
+  class AndError < Error
+    attr_reader :children
+
+    def self.from(children)
+      length = children.length
+
+      return EmptyError.instance if length == 0
+
+      children.reduce do |left, right|
+        if left.is_a?(AndError)
+          left << right
+        else
+          left & right
+        end
+      end
+    end
+
+    def initialize(children)
+      raise 'children fewer than 2' if children.length < 2
+
+      super()
+
+      @children = children
+    end
+
+    def ==(other)
+      return true if equal?(other)
+
+      other.instance_of?(AndError) &&
+        @children == other.children
+    end
+
+    def &(other)
+      return self if other.is_a?(EmptyError)
+
+      clone << other
+    end
+
+    def add(other)
+      case other
+      when AndError
+        right = other.children.dup
+
+        @children.each_with_index do |l, i|
+          next unless l.is_a?(NestedError)
+
+          index = right.find_index { _1.is_a?(NestedError) && _1.key == l.key }
+
+          @children[i] = l & right.delete_at(index) if index
+        end
+
+        @children.concat(right)
+      when NestedError
+        index = @children.find_index { _1.is_a?(NestedError) && _1.key == other.key }
+
+        if index
+          @children[index] &= other
+        else
+          @children << other
+        end
+      else
+        @children << other
+      end
+
+      self
+    end
+    alias << add
+
+    def clone
+      klone = super
+      klone.instance_exec do
+        @children = @children.dup
+      end
+
+      klone
+    end
+    alias dup clone
+
+    def to_s
+      @children.map(&:to_s).join(' & ')
+    end
+  end
+end

data/lib/matcher/errors/boolean_collector.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Matcher
+  class BooleanCollector
+    def initialize
+      @result = true
+      @mode = :and
+    end
+
+    def or!
+      @mode = :or
+      self
+    end
+
+    def or?
+      @mode == :or
+    end
+
+    def and?
+      @mode == :and
+    end
+
+    def empty?
+      @result
+    end
+
+    INVALID_ERROR = ElementError.new('invalid')
+    private_constant :INVALID_ERROR
+
+    def error
+      @result ? EmptyError.instance : INVALID_ERROR
+    end
+
+    def <<(error)
+      if !error.is_a?(Error) || !error.valid?
+        @result = false
+        throw :mismatch if and?
+      end
+
+      self.error
+    end
+
+    def [](_key)
+      self
+    end
+
+    def clear
+      @result = true
+    end
+  end
+end

data/lib/matcher/errors/element_error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Matcher
+  class ElementError < Error
+    attr_reader :message
+
+    def initialize(message)
+      super()
+
+      @message = message
+    end
+
+    def ==(other)
+      return true if equal?(other)
+
+      other.instance_of?(ElementError) &&
+        @message == other.message
+    end
+
+    def to_s
+      @message.inspect
+    end
+  end
+end

data/lib/matcher/errors/empty_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Matcher
+  class EmptyError < Error
+    include Singleton
+
+    def &(other)
+      other
+    end
+
+    def |(other)
+      other
+    end
+
+    def valid?
+      true
+    end
+
+    def to_s
+      '<>'
+    end
+  end
+end

data/lib/matcher/errors/error.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Matcher
+  class Error
+    def &(other)
+      case other
+      when EmptyError
+        self
+      when AndError
+        AndError.new([self].concat(other.children))
+      else
+        AndError.new([self, other])
+      end
+    end
+
+    def |(other)
+      case other
+      when EmptyError
+        self
+      when OrError
+        OrError.new([self].concat(other.children))
+      else
+        OrError.new([self, other])
+      end
+    end
+
+    def valid?
+      false
+    end
+
+    def inspect
+      to_s
+    end
+
+    def report
+      Reporter.report(self)
+    end
+  end
+end