matchers 0.1.0.pre.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 92ba01bc8b3f334276b254cb4b78efcd86165a7410cad65fc21e0b319d532df0
+  data.tar.gz: 3626679374928bd5adf361c3d9d1fa357033e003ae702d225f4c3a9b4e028b82
+SHA512:
+  metadata.gz: 32fb3f33b2d210d46f81ebaa0f3c4aec455a4543806b3b38e7eefd42f81718f98a2690a600140b12702d3c9ee3232f63c9d4a55b8f58840597779cff40b95276
+  data.tar.gz: 556079ba3a6e26bdc35217e651740d4f1298bc7886165dca2e4715ee0c270955baabb28fd66c6df4031acc6e42af774e5d19ae6bf70b76a10935ffcdeeea3758

data/lib/matcher/assertions.rb

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

data/lib/matcher/autoload.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Matcher
+  autoload :Reporter, "matcher/reporter"
+end

data/lib/matcher/base.rb

@@ -0,0 +1,183 @@
+# 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 other to AnyMatcher
+    # @param other
+    # @return [AnyMatcher]
+    # @see MatcherDsl#any
+    def +(other)
+      other = Matcher.cache(other)
+
+      matchers = if other.is_a?(AnyMatcher)
+        [self].concat(other.matchers)
+      else
+        [self, other]
+      end
+
+      AnyMatcher.new(matchers)
+    end
+
+    ##
+    # Combines with other to AllMatcher
+    # @param other
+    # @return [AllMatcher]
+    # @see MatcherDsl#all
+    def *(other)
+      other = Matcher.cache(other)
+
+      matchers = if other.is_a?(AllMatcher)
+        [self].concat(other.matchers)
+      else
+        [self, other]
+      end
+
+      AllMatcher.new(matchers)
+    end
+
+    ##
+    # Combines with other to LazyAnyMatcher
+    # @param other
+    # @return [LazyAnyMatcher]
+    # @see MatcherDsl#lazy_any
+    def |(other)
+      other = Matcher.cache(other)
+
+      matchers = if other.is_a?(LazyAnyMatcher)
+        [self].concat(other.matchers)
+      else
+        [self, other]
+      end
+
+      LazyAnyMatcher.new(matchers)
+    end
+
+    ##
+    # Combines with other to LazyAllMatcher
+    # @param other
+    # @return [LazyAllMatcher]
+    # @see MatcherDsl#lazy_all
+    def &(other)
+      other = Matcher.cache(other)
+
+      matchers = if other.is_a?(LazyAllMatcher)
+        [self].concat(other.matchers)
+      else
+        [self, other]
+      end
+
+      LazyAllMatcher.new(matchers)
+    end
+
+    ##
+    # Implies another matcher
+    # @param other
+    # @return [ImplyMatcher]
+    # @see MatcherDsl#imply
+    def >>(other)
+      ImplyMatcher.new(self, Matcher.cache(other))
+    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's class during match time.
+    def class_session
+      Matcher.session[self.class] ||= {}
+    end
+  end
+end

data/lib/matcher/compatibility.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Matcher
+  module Compatibility
+    extend self
+
+    # rubocop:disable Style/ClassVars
+
+    @@method_quote_delimiter = caller[0].include?("`") ? "`" : "'"
+
+    # rubocop:enable Style/ClassVars
+
+    def quote_method(method)
+      "#{@@method_quote_delimiter}#{method}'"
+    end
+
+    def nil_kwargs?
+      test_nil_kwargs(**nil)
+    rescue TypeError
+      false
+    end
+
+    # rubocop:disable Naming/PredicateMethod
+
+    def test_nil_kwargs(**)
+      true
+    end
+    private :test_nil_kwargs
+
+    # rubocop:enable Naming/PredicateMethod
+
+    NULL_KWARGS = nil_kwargs? ? nil : {}.freeze
+  end
+end

data/lib/matcher/debug.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Matcher
+  module Debug
+    class << self
+      DEBUGGERS = %w[/bin/irb: ruby-debug-ide].freeze
+
+      def enable
+        init(force: true)
+      end
+
+      def 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 debugging?(trace)
+        last_trace_item = trace[0]
+
+        %w[puts p].any? { call_from?(last_trace_item, _1) } ||
+          last_trace_item.include?("ruby-debug-ide") ||
+          trace.any? { call_from?(_1, "output_value") }
+      end
+
+      # rubocop:disable Style/ClassVars
+
+      @@method_quote_delimiter = caller[0].include?("`") ? "`" : "#"
+
+      # rubocop:enable Style/ClassVars
+
+      def call_from?(trace_item, method)
+        trace_item.end_with?("#{@@method_quote_delimiter}#{method}'")
+      end
+    end
+  end
+
+  module ExpressionRecorderDebug
+    private
+
+    def method_missing(method, ...)
+      if Debug.debugging?(caller)
+        return @expression.to_s if %i[to_s inspect].include?(method)
+
+        Object.instance_method(method).bind_call(self, ...)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method, _include_private = false)
+      return Object.method_defined?(method) if Debug.debugging?(caller)
+
+      super
+    end
+  end
+end

data/lib/matcher/dsl/builder.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Matcher
+  class Builder
+    include ExpressionDsl
+    include MatcherDsl
+
+    def initialize(outside, build_session: Matcher.build_session)
+      ExpressionDsl.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
+    #   class MyClass
+    #     def initialize
+    #       @ivar = 42
+    #     end
+    #
+    #     def my_method
+    #       "my string"
+    #     end
+    #
+    #     def my_matcher
+    #       Matcher.build do
+    #         # @ivar and self.my_method not accessible from here
+    #         [outside { @ivar }, outside.my_method]
+    #       end
+    #     end
+    #   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+
+    #
+    # This is useful to prevent accidentally matching against +nil+:
+    #   def definitely_not_nil
+    #     nil # shoot
+    #   end
+    #
+    #   my_value = definitely_not_nil
+    #   m = Matcher.build { present(my_value) }
+    #   m.match?(nil) # => false
+    #
+    #   my_value = "fixed"
+    #   m = Matcher.build { present(my_value) }
+    #   m.match?("fixed") # => true
+    # @example
+    #   present(my_value)
+    # @param matcher
+    # @return [AllMatcher]
+    def present(matcher)
+      AllMatcher.new([
+        ~equal(nil),
+        matcher_of(matcher),
+      ])
+    end
+  end
+end

data/lib/matcher/dsl/chain.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Matcher
+  ##
+  # Matcher helpers like +each+ or +map+ can be chained with the +^+ operator or
+  # +chain+ helper. If a helper has the form <tt>my_helper(..., matcher)</tt>
+  # then it usually also supports this form <tt>my_helper(...) ^ matcher</tt>.
+  # This helps to reduce nested parenthesis:
+  #
+  #   # before
+  #   let({ limit: 10 }, map(_.compact, filter(_.even?, _ < vars[:limit])))
+  #
+  #   # with ^
+  #   let(limit: 10) ^
+  #     map(_.compact) ^
+  #     filter(_.even?) ^
+  #     (_ < vars[:limit])
+  #
+  #   # with chain
+  #   chain(
+  #     let(limit: 10),
+  #     map(_.compact),
+  #     filter(_.even?),
+  #     _ < vars[:limit],
+  #   )
+  #
+  # Keep operator precedence in mind when working with expressions.
+  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 other matcher or chain
+    # @return [Base, Chain]
+    def ^(other)
+      if !Recorder.recorder?(other) && other.is_a?(Chain)
+        Chain.new { @block.call(other ^ _1) }
+      else
+        matcher = Matcher.cache(other)
+        result = @block.call(matcher)
+        result = ~result if @negated
+        result
+      end
+    end
+
+    def optional(fallback = AlwaysMatcher.instance)
+      OptionalChain.new(self, fallback)
+    end
+  end
+
+  module MatcherDsl
+    ##
+    # 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 [Base, Chain]
+    def chain(*chains)
+      chains.reduce(:^)
+    end
+  end
+end