matchers 0.1.0.pre.1

data/lib/matcher/expressions/call.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+module Matcher
+  class Call < Expression
+    attr_reader :receiver, :method, :args, :kwargs, :block
+
+    UNARY_OPERATORS =
+      %i[! ~ +@ -@].freeze
+    BINARY_OPERATORS =
+      %i[+ - * ** / % < > <= >= <=> == === != =~ !~ & | ^ << >> && ||].freeze
+
+    def self.last_assign
+      Matcher.build_session&.dig(Call, :last_assign)
+    end
+
+    def self.reset_last_assign
+      Matcher.build_session&.[](Call)&.delete(:last_assign)
+    end
+
+    def initialize(receiver, method, args = [], kwargs = {}, block = nil)
+      super()
+
+      @receiver = receiver
+      @method = method
+      @args = args
+      @kwargs = kwargs
+      @block = block
+
+      if binary? && Matcher.settings[:logical_operators]
+        case method
+        when :&
+          @method = :"&&"
+        when :|
+          @method = :"||"
+        end
+      end
+
+      set_last_assign if method.end_with?("=")
+    end
+
+    def unary?
+      knary?(0)
+    end
+
+    def binary?
+      knary?(1)
+    end
+
+    def knary?(arity)
+      @args.length == arity && @kwargs.empty? && !@block
+    end
+
+    def assignment?
+      @method.end_with?("=") && !%i[<= >= == === !=].include?(@method)
+    end
+
+    def precedence
+      @precedence ||= begin
+        has_precedence = (unary? && UNARY_OPERATORS.include?(@method)) ||
+          (binary? && BINARY_OPERATORS.include?(@method))
+
+        # if method is not an operator then precedence is highest (-1)
+        has_precedence ? OPERATOR_PRECEDENCE[@method] : -1
+      end
+    end
+
+    def evaluate(values)
+      receiver = @receiver.evaluate(values)
+
+      return receiver if lazy?(receiver)
+
+      args = @args.map { _1.evaluate(values) }
+      kwargs = @kwargs.transform_values { _1.evaluate(values) }
+
+      return args[0] if logical_operator?
+
+      invoke(values, receiver, args, kwargs)
+    end
+
+    def evaluate_tree(values)
+      receiver_t = @receiver.evaluate_tree(values)
+      receiver = receiver_t.last
+
+      return [receiver_t, nil, nil, receiver] if lazy?(receiver)
+
+      args, args_t = evaluate_args_tree(values)
+      kwargs, kwargs_t = evaluate_kwargs_tree(values)
+
+      return [receiver_t, args_t, kwargs_t, args[0]] if logical_operator?
+
+      value = invoke(values, receiver, args, kwargs)
+
+      [receiver_t, args_t, kwargs_t, value]
+    end
+
+    def variables
+      @variables ||= begin
+        variables = @receiver.variables +
+          @args.flat_map(&:variables) +
+          @kwargs.each_value.flat_map(&:variables)
+
+        variables.concat(@block.variables) if @block
+
+        variables.uniq
+      end
+    end
+
+    def ==(other)
+      return true if equal?(other)
+
+      other.instance_of?(Call) &&
+        other.receiver == @receiver &&
+        other.method == @method &&
+        other.args.eql?(@args) &&
+        other.kwargs.eql?(@kwargs) &&
+        other.block == @block
+    end
+    alias eql? ==
+
+    def hash
+      @hash ||= [self.class, @receiver, @args, @method, @kwargs, @block].hash
+    end
+
+    def visit(&)
+      return to_enum(:visit) unless block_given?
+
+      @receiver.visit(&)
+      @args.each { _1.visit(&) }
+      @kwargs.each_value { _1.visit(&) }
+
+      yield self
+    end
+
+    def substitute(replacements)
+      replacement_names = replacements.keys
+
+      return self unless replacement_names.intersect?(variables)
+
+      receiver = @receiver.substitute(replacements)
+
+      no_change = nil
+      substitute = lambda do |expression|
+        result = expression.substitute(replacements)
+        no_change = false unless result.equal?(expression)
+
+        result
+      end
+
+      no_change = true
+      args = @args.map(&substitute)
+      args = @args if no_change
+
+      no_change = true
+      kwargs = @kwargs.transform_values(&substitute)
+      kwargs = @kwargs if no_change
+
+      block = @block.is_a?(Block) ? @block.substitute(replacements) : @block
+
+      Call.new(receiver, @method, args, kwargs, block)
+    end
+
+    def to_s
+      receiver = parenthesized_receiver
+
+      case @method
+      when :!, :~, :+@, :-@
+        # !foo
+        return "#{@method[0]}#{receiver}" if unary?
+      when :+, :-, :*, :/, :%, :**, :<, :>, :<=, :>=, :<=>, :==, :===, :!=, :=~,
+        :!~, :&, :|, :^, :<<, :>>, :"&&", :"||"
+
+        if binary?
+          # foo**2
+          return "#{receiver}**#{parenthesized_operand}" if @method == :**
+
+          # foo + bar
+          return "#{receiver} #{@method} #{parenthesized_operand}"
+        end
+      when :[]
+        # foo[a, b, ...]
+        return "#{receiver}[#{args_and_kwargs_string}]#{block_string}"
+      when :[]=
+        # foo[a, b, ...] = 1
+        if @args.length >= 2 && @kwargs.empty? && !@block
+          first_args = @args[0..-2].join(", ")
+          last_arg = @args[-1].to_s
+
+          return "#{receiver}[#{first_args}] = #{last_arg}"
+        end
+      end
+
+      if @method.end_with?("=") && @method != :[]= && binary?
+        # foo.bar = 42
+
+        "#{receiver}.#{@method[0..-2]} = #{@args[0]}"
+      else
+        # foo.bar OR foo.bar(arg1, arg2, ...)
+
+        is_kernel = @receiver.is_a?(Constant) && @receiver.value == Kernel
+        args_and_kwargs = args_and_kwargs_string
+        string = is_kernel ? @method.to_s : "#{receiver}.#{@method}"
+        string += "(#{args_and_kwargs})" unless args_and_kwargs.empty?
+        string += block_string
+
+        string
+      end
+    end
+
+    private
+
+    def lazy?(receiver)
+      @method == :"&&" && !receiver || @method == :"||" && receiver
+    end
+
+    def logical_operator?
+      %i[&& ||].include?(@method)
+    end
+
+    def invoke(values, receiver, args, kwargs)
+      block = @block.is_a?(Block) ? @block&.to_proc(values:) : @block
+
+      begin
+        result = receiver.send(@method, *args, **kwargs, &block)
+        assignment? ? args.last : result
+      rescue StandardError => e
+        message = "#{self} raised #{e.class}: #{e.message}"
+        given = given_for(values)
+
+        raise CallError.new(message, self, given)
+      end
+    end
+
+    def set_last_assign
+      build_session = Matcher.build_session
+
+      return unless build_session
+
+      call_session = (build_session[Call] ||= {})
+      call_session[:last_assign] = self
+    end
+
+    def evaluate_args_tree(values)
+      n = @args.length
+      args = Array.new(n)
+      args_t = Array.new(n)
+
+      @args.each_with_index do |arg, i|
+        arg_t = arg.evaluate_tree(values)
+        args[i] = arg_t.last
+        args_t[i] = arg_t
+      end
+
+      [args, args_t]
+    end
+
+    def evaluate_kwargs_tree(values)
+      kwargs = {}
+      kwargs_t = {}
+
+      @kwargs.each do |key, kwarg|
+        kwarg_t = kwarg.evaluate_tree(values)
+        kwargs[key] = kwarg_t.last
+        kwargs_t[key] = kwarg_t
+      end
+
+      [kwargs, kwargs_t]
+    end
+
+    def args_and_kwargs_string
+      args = @args.map(&:to_s)
+      kwargs = @kwargs.map do |k, v|
+        v_to_s = v.to_s
+
+        if k.is_a?(Symbol)
+          "#{k}: #{v_to_s}"
+        else
+          "#{k.inspect} => #{v_to_s}"
+        end
+      end
+
+      list = args + kwargs
+      list << "&#{@block.symbol.inspect}" if @block.is_a?(SymbolProc)
+
+      list.join(", ")
+    end
+
+    def block_string
+      if @block.is_a?(Block)
+        " #{@block.to_s(as_block: true)}"
+      elsif @block && !@block.is_a?(SymbolProc)
+        " { ... }"
+      else
+        ""
+      end
+    end
+
+    def parenthesized_receiver
+      non_associative = %i[<=> == === != =~ !~].include?(@method)
+
+      @receiver.parenthesize(precedence, non_associative)
+    end
+
+    def parenthesized_operand
+      @args[0].parenthesize(precedence, true)
+    end
+  end
+end

data/lib/matcher/expressions/call_error.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Matcher
+  class CallError < StandardError
+    attr_reader :call, :given
+
+    def initialize(message, call, given)
+      super(message)
+
+      @call = call
+      @given = given
+    end
+
+    def message_for_errors(actual)
+      case cause
+      when NoMethodError
+        not_responding_message(actual)
+      else
+        raising_message(actual)
+      end
+    end
+
+    private
+
+    def raising_message(actual)
+      Message.new(%i[expression raising], false, actual, @call, cause, @given)
+    end
+
+    def not_responding_message(actual)
+      if @call.receiver == Variable.actual
+        Message.new(:responding_to, true, cause.receiver, @call.method)
+      else
+        Message.new(
+          %i[expression responding_to],
+          true,
+          actual,
+          @call.receiver,
+          cause.receiver,
+          @call.method,
+          @given,
+        )
+      end
+    end
+  end
+end

data/lib/matcher/expressions/constant.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Matcher
+  class Constant < Expression
+    def self.cache(value, expression_cache = ExpressionCache.current)
+      if expression_cache
+        expression_cache.constant_for(value)
+      else
+        Constant.new(value)
+      end
+    end
+
+    attr_reader :value
+
+    def initialize(value)
+      super()
+
+      @value = value
+    end
+
+    def negated
+      Constant.new(!@value)
+    end
+
+    def variables
+      []
+    end
+
+    def evaluate(_values)
+      @value
+    end
+
+    def ==(other)
+      return true if equal?(other)
+
+      other.instance_of?(Constant) &&
+        @value.eql?(other.value)
+    end
+    alias eql? ==
+
+    def hash
+      @hash ||= [self.class, @value].hash
+    end
+
+    def substitute(_replacements)
+      self
+    end
+
+    def to_s
+      @value.inspect
+    end
+  end
+end

data/lib/matcher/expressions/expression.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+module Matcher
+  ##
+  # Expressions are a central feature of this library. They are used for:
+  #
+  # - building ad-hoc matchers (e.g. <tt>_ > 10</tt> , +_.even?+ )
+  # - tracking where match errors happen
+  #   (e.g. <tt>root[:name]: expected ...</tt>)
+  # - as parameters for other matchers like +map+ where they take the role of
+  #   anonymous functions (e.g. <tt>map(_.to_s, "some_string")</tt> )
+  #
+  # Helpers (like +map+) use expressions instead of procs because the AST of an
+  # Expression can be inspected and transformed. This is useful when building
+  # the path and message of errors.
+  #
+  #   my_expression = Matcher::Expression.build { _ * 21 }
+  #   my_expression.evaluate(actual: 2) # => 42
+  #   # proc equivalent:
+  #   ->(x) { x * 21 }
+  #
+  # Have a look at {Recorder} where we explain how reorders are used to build
+  # expressions.
+  #
+  # @see Recorder
+  class Expression
+    class ExpressionBuilder
+      include ExpressionDsl
+
+      def initialize(build_session: Matcher.build_session)
+        ExpressionDsl.init(self, build_session)
+      end
+    end
+
+    ##
+    # Builds an expression conveniently using {Recorder} and helpers from
+    # {ExpressionDsl}.
+    #
+    # @example
+    #   Matcher::Expression.build do
+    #     _.sum(&:to_i)
+    #   end
+    #
+    #   Matcher::Expression.build do
+    #     range(vars[:from], vars[:to]).include?(_)
+    #   end
+    #
+    # @see ExpressionDsl
+    def self.build(&)
+      Matcher.with_build_session do |build_session|
+        builder = ExpressionBuilder.new(build_session:)
+        result = builder.instance_exec(&)
+        builder.expression_of(result)
+      end
+    end
+
+    def self.expression_or_value(obj, expression_cache: nil)
+      case obj
+      when -> { Recorder.recorder?(_1) }
+        return Recorder.to_expression(obj)
+      when Base
+        raise ArgumentError, "Cannot use matcher as expression"
+      when NoExpression
+        raise ArgumentError, "Cannot use #{obj.class} as expression"
+      when Proc
+        raise ArgumentError, "Cannot use Proc as expression. " \
+          "Use `expr { ... }' instead"
+      when Array
+        items = obj.map { expression_or_value(_1, expression_cache:) }
+
+        if items.any?(Expression)
+          items.each_with_index do |item, i|
+            unless item.is_a?(Expression)
+              items[i] = Constant.cache(item, expression_cache)
+            end
+          end
+
+          return ArrayExpression.new(items)
+        end
+      when Hash
+        pairs = obj.map do |key, value|
+          key = expression_or_value(key, expression_cache:)
+          value = expression_or_value(value, expression_cache:)
+
+          [key, value]
+        end
+
+        if pairs.any? { |k, v| k.is_a?(Expression) || v.is_a?(Expression) }
+          pairs.each do |pair|
+            k, v = pair
+
+            unless k.is_a?(Expression)
+              pair[0] = Constant.cache(k, expression_cache)
+            end
+            unless v.is_a?(Expression)
+              pair[1] = Constant.cache(v, expression_cache)
+            end
+          end
+
+          return HashExpression.new(pairs)
+        end
+      when Range
+        from = expression_or_value(obj.begin, expression_cache:)
+        to = expression_or_value(obj.end, expression_cache:)
+
+        if from.is_a?(Expression) || to.is_a?(Expression)
+          unless from.is_a?(Expression)
+            from = Constant.cache(from, expression_cache)
+          end
+          to = Constant.cache(to, expression_cache) unless to.is_a?(Expression)
+
+          return RangeExpression.new(from, to, exclude_end: obj.exclude_end?)
+        end
+      when Set
+        items = obj.map { expression_or_value(_1, expression_cache:) }
+
+        if items.any?(Expression)
+          items.each_with_index do |item, i|
+            unless item.is_a?(Expression)
+              items[i] = Constant.cache(item, expression_cache)
+            end
+          end
+
+          return SetExpression.new(items)
+        end
+      end
+
+      obj
+    end
+
+    def self.of(obj, expression_cache: nil)
+      obj = expression_or_value(obj, expression_cache:)
+
+      if obj.is_a?(Expression)
+        obj
+      else
+        Constant.cache(obj, expression_cache)
+      end
+    end
+
+    def self.try_recorder(obj)
+      return obj unless Recorder.recorder?(obj)
+
+      Recorder.to_expression(obj)
+    end
+
+    def initialize
+      raise "abstract class" if instance_of?(Expression)
+    end
+
+    def evaluate_tree(values)
+      [evaluate(values)]
+    end
+
+    def given_for(values)
+      variables.to_h { [_1, values[_1]] }
+    end
+
+    def visit
+      return to_enum(:visit) unless block_given?
+
+      yield self
+    end
+
+    def free_symbol(symbol)
+      parameters = ExpressionWalker.each_block(self).flat_map do |block|
+        block.parameters.map { |_type, name| name }
+      end
+
+      identifiers = (variables + parameters).to_set
+
+      return symbol unless identifiers.include?(symbol)
+
+      i = 2
+      loop do
+        symbol_i = :"#{symbol}#{i}"
+
+        return symbol_i unless identifiers.include?(symbol_i)
+
+        i += 1
+      end
+    end
+
+    OPERATOR_PRECEDENCE = begin
+      precedence = {}
+
+      # see https://docs.ruby-lang.org/en/master/syntax/precedence_rdoc.html
+      [
+        %i[! ~ +@],
+        %i[**],
+        %i[-@],
+        %i[* / %],
+        %i[+ -],
+        %i[<< >>],
+        %i[&],
+        %i[| ^],
+        %i[> >= < <=],
+        %i[<=> == === != =~ !~],
+        %i[&&],
+        %i[||],
+        %i[..],
+        %i[modifier_rescue],
+      ].each_with_index do |operators, index|
+        operators.each { precedence[_1] = index }
+      end
+
+      precedence.freeze
+    end
+
+    def precedence
+      # highest precedence, won't need parentheses
+      -1
+    end
+
+    def parenthesize(precedence, when_equal)
+      # Parenthesize if own precedence is lower than the other. In some
+      # situations (as right hand side or for non-associative operators) we also
+      # parenthesize when precedence is equal.
+
+      need_parentheses = if when_equal
+        self.precedence >= precedence
+      else
+        self.precedence > precedence
+      end
+
+      need_parentheses ? "(#{self})" : to_s
+    end
+
+    def inspect
+      to_s
+    end
+
+    def to_recorder
+      Recorder.new(self)
+    end
+  end
+end

data/lib/matcher/expressions/expression_walker.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Matcher
+  class ExpressionWalker
+    attr_accessor :constant_visitor,
+      :variable_visitor,
+      :call_visitor,
+      :block_visitor,
+      :proc_expression_visitor
+
+    def self.each_variable(expression, &block)
+      return to_enum(:each_variable, expression) unless block_given?
+
+      walker = new(expression)
+      walker.variable_visitor = block
+      walker.walk
+    end
+
+    def self.each_block(expression, &block)
+      return to_enum(:each_block, expression) unless block_given?
+
+      walker = new(expression)
+      walker.block_visitor = block
+      walker.walk
+    end
+
+    def initialize(expression)
+      @expression = expression
+    end
+
+    def walk
+      traverse(@expression)
+    end
+
+    private
+
+    def traverse(expression)
+      case expression
+      when Constant
+        @constant_visitor&.call(expression)
+      when Variable
+        @variable_visitor&.call(expression)
+      when Call
+        @call_visitor&.call(expression)
+
+        traverse(expression.receiver)
+        expression.args.each { traverse(_1) }
+        expression.kwargs.each { traverse(_2) }
+        traverse_block(expression.block) if expression.block
+      when ProcExpression
+        @proc_expression_visitor&.call(expression)
+      when ArrayExpression, SetExpression
+        expression.items.each { traverse(_1) }
+      when HashExpression
+        expression.pairs.each do |k, v|
+          traverse(k)
+          traverse(v)
+        end
+      when RangeExpression
+        traverse(expression.begin)
+        traverse(expression.end)
+      when RescueLastErrorExpression
+        traverse(expression.expression)
+      else
+        raise "unsupported expression type: #{expression.class}"
+      end
+    end
+
+    def traverse_block(block)
+      @block_visitor&.call(block)
+
+      return unless block.is_a?(Block)
+
+      traverse(block.expression)
+    end
+  end
+end