janeway-jsonpath 0.2.0 → 0.3.0

data/lib/janeway/interpreters/array_slice_selector_interpreter.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Janeway
+  module Interpreters
+    # Interprets array slice selector on the given input
+    class ArraySliceSelectorInterpreter < Base
+      alias selector node
+
+      # Filter the input by applying the array slice selector.
+      #
+      # @param selector [ArraySliceSelector]
+      # @param input [Array, Hash] the results of processing so far
+      # @param root [Array, Hash] the entire input
+      # @return [Array]
+      def interpret(input, root)
+        return [] unless input.is_a?(Array)
+        return [] if selector&.step&.zero? # RFC: When step is 0, no elements are selected.
+
+        # Calculate the upper and lower indices of the target range
+        lower = selector.lower_index(input.size)
+        upper = selector.upper_index(input.size)
+
+        # Collect values from target indices. Omit the value from the final index.
+        results =
+          if selector.step.positive?
+            lower.step(to: upper - 1, by: selector.step).map { input[_1] }
+          else
+            upper.step(to: lower + 1, by: selector.step).map { input[_1] }
+          end
+        return results unless @next
+
+        # Apply child selector to each node in the output node list
+        node_list = results
+        results = []
+        node_list.each do |node|
+          results.concat @next.interpret(node, root)
+        end
+        results
+      end
+    end
+  end
+end

data/lib/janeway/interpreters/base.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'tree_constructor'
+
+module Janeway
+  # Interpreters module contains interpreter classes which correspond to each
+  # type of AST::Node.
+  module Interpreters
+    # Base class for interpreters.
+    class Base
+      # The special result NOTHING represents the absence of a JSON value and
+      # is distinct from any JSON value, including null.
+      # It represents:
+      #  * object keys referred to by name that do not exist in the input
+      #  * array values referred to by index that are out of range
+      #  * return value of function calls with an invalid input data type
+      NOTHING = :nothing
+
+      # Subsequent expression interpreter that filters the output of this one
+      # @return [Interpreters::Base, nil]
+      attr_accessor :next
+
+      # @return [AST::Expression]
+      attr_reader :node
+
+      def initialize(node)
+        @node = node
+
+        return unless node.next
+
+        @next = TreeConstructor.ast_node_to_interpreter(node.next)
+      end
+
+      # Interpret the input, return result or forward to next node.
+      #
+      # @param input [Array, Hash] the results of processing so far
+      # @param root [Array, Hash] the entire input
+      def interpret(_input, _root)
+        raise NotImplementedError, 'subclass must implement #interpret'
+      end
+    end
+  end
+end

data/lib/janeway/interpreters/binary_operator_interpreter.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Janeway
+  module Interpreters
+    # Interprets a binary operator within filter selector.
+    class BinaryOperatorInterpreter < Base
+      alias operator node
+
+      # Set up the internal interpreter chain for the BinaryOperator.
+      def initialize(operator)
+        super
+        @left = TreeConstructor.ast_node_to_interpreter(operator.left)
+        @right = TreeConstructor.ast_node_to_interpreter(operator.right)
+      end
+
+      # The binary operators are all comparison operators that test equality.
+      #
+      #  * boolean values specified in the query
+      #  * JSONPath expressions which must be evaluated
+      #
+      # After a JSONPath expression is evaluated, it results in a node list.
+      # This may contain literal values or nodes, whose value must be extracted before comparison.
+      #
+      # @param input [Array, Hash] the results of processing so far
+      # @param root [Array, Hash] the entire input
+      def interpret(input, root)
+        case operator.name
+        when :and, :or
+          # handle node list for existence check
+          lhs = @left.interpret(input, root)
+          rhs = @right.interpret(input, root)
+        when :equal, :not_equal, :less_than, :greater_than, :less_than_or_equal, :greater_than_or_equal
+          # handle node values for comparison check
+          lhs = to_single_value @left.interpret(input, root)
+          rhs = to_single_value @right.interpret(input, root)
+        else
+          raise "Don't know how to handle binary operator #{operator.name.inspect}"
+        end
+        send(:"interpret_#{operator.name}", lhs, rhs)
+      end
+
+      # Interpret a node and extract its value, in preparation for using the node
+      # in a comparison operator.
+      # Basic literals such as AST::Number and AST::StringType evaluate to a number or string,
+      # but selectors and segments evaluate to a node list.  Extract the value (if any)
+      # from the node list, or return basic type.
+
+      # Convert an expression result into a single value suitable for use by a comparison operator.
+      # Expression result may already ba single value (ie. from a literal like AST::String)
+      # or it may be a node list from a singular query.
+      #
+      # Any node list is guaranteed not to contain multiple values because the expression that
+      # produce it was already verified to be a singular query.
+      #
+      # @param node [AST::Expression]
+      # @param input [Object]
+      def to_single_value(result)
+        # Return basic types (ie. from AST::Number, AST::StringType, AST::Null)
+        return result unless result.is_a?(Array)
+
+        # Node lists are returned by Selectors, ChildSegment, DescendantSegment.
+        #
+        # For a comparison operator, an empty node list represents a missing element.
+        # This must not match any literal value (including null/nil) but must match another missing value.
+        return NOTHING if result.empty?
+
+        # The parsing stage has already verified that both the left and right
+        # expressions evaluate to a single value. Both are either a literal or a singular query.
+        # So, this check will never raise an error.
+        raise 'node list contains multiple elements but this is a comparison' unless result.size == 1
+
+        result.first # Return the only node in the node list
+      end
+
+      # @param lhs [String, Numeric, Symbol, nil] string/number/null or NOTHING
+      # @param rhs [String, Numeric, Symbol, nil] string/number/null or NOTHING
+      def interpret_equal(lhs, rhs)
+        lhs == rhs
+      end
+
+      # Interpret != operator
+      def interpret_not_equal(lhs, rhs)
+        !interpret_equal(lhs, rhs)
+      end
+
+      # Interpret && operator
+      # May receive node lists, in which case empty node list == false
+      def interpret_and(lhs, rhs)
+        # non-empty array is already truthy, so that works properly without conversion
+        lhs = false if lhs == []
+        rhs = false if rhs == []
+        lhs && rhs
+      end
+
+      # Interpret || operator
+      # May receive node lists, in which case empty node list == false
+      def interpret_or(lhs, rhs)
+        # non-empty array is already truthy, so that works properly without conversion
+        lhs = false if lhs.is_a?(Array) && lhs.empty?
+        rhs = false if rhs.is_a?(Array) && rhs.empty?
+        lhs || rhs
+      end
+
+      def interpret_less_than(lhs, rhs)
+        lhs < rhs
+      rescue StandardError
+        false
+      end
+
+      def interpret_less_than_or_equal(lhs, rhs)
+        # Must be done in 2 comparisons, because the equality comparison is
+        # valid for many types that do not support the < operator.
+        return true if interpret_equal(lhs, rhs)
+
+        lhs < rhs
+      rescue StandardError
+        # This catches type mismatches like {} <= 1
+        # RFC says that both < and > return false for such comparisons
+        false
+      end
+
+      def interpret_greater_than(lhs, rhs)
+        lhs > rhs
+      rescue StandardError
+        false
+      end
+
+      def interpret_greater_than_or_equal(lhs, rhs)
+        return true if interpret_equal(lhs, rhs)
+
+        lhs > rhs
+      rescue StandardError
+        false
+      end
+
+      # @param boolean [AST::Boolean]
+      # @return [Boolean]
+      def interpret_boolean(boolean, _input)
+        boolean.value
+      end
+
+      # @param number [AST::Number]
+      # @return [Integer, Float]
+      def interpret_number(number, _input)
+        number.value
+      end
+
+      # @param string [AST::StringType]
+      # @return [String]
+      def interpret_string_type(string, _input)
+        string.value
+      end
+
+      # @param _null [AST::Null] ignored
+      # @param _input [Object] ignored
+      def interpret_null(_null, _input)
+        nil
+      end
+    end
+  end
+end

data/lib/janeway/interpreters/child_segment_interpreter.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Janeway
+  module Interpreters
+    # For each node in the input nodelist, the resulting nodelist of a child
+    # segment is the concatenation of the nodelists from each of its
+    # selectors in the order that the selectors appear in the list. Note: Any
+    # node matched by more than one selector is kept as many times in the nodelist.
+    #
+    # A child segment can only contain selectors according to the RFC's ABNF grammar, so it
+    # cannot contain another child segment, or a new expression starting with the root identifier.
+    class ChildSegmentInterpreter < Base
+      # @param child_segment [AST::ChildSegment]
+      def initialize(child_segment)
+        super
+        @nodes =
+          child_segment.map do |expr|
+            TreeConstructor.ast_node_to_interpreter(expr)
+          end
+      end
+
+      # Interpret a set of 2 or more selectors, seperated by the union operator.
+      # All selectors are sent the identical input, the results are combined.
+      #
+      # @param input [Array, Hash] the results of processing so far
+      # @param root [Array, Hash] the entire input
+      # @return [Array]
+      def interpret(input, root)
+        # Apply each expression to the input, collect results
+        results = []
+        @nodes.each do |node|
+          results.concat node.interpret(input, root)
+        end
+
+        # Return results, or forward them to the next selector
+        return results unless @next
+
+        @next.interpret(results, root)
+      end
+    end
+  end
+end

data/lib/janeway/interpreters/current_node_interpreter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Janeway
+  module Interpreters
+    # Interpets current node identifier.
+    # This applies the following selector to the input.
+    class CurrentNodeInterpreter < Base
+      alias current_node node
+
+      # Apply selector to each value in the current node and return result.
+      #
+      # The result is an Array containing all results of evaluating the CurrentNode's selector (if any.)
+      #
+      # If the selector extracted values from nodes such as strings, numbers or nil/null,
+      # these will be included in the array.
+      # If the selector did not match any node, the array may be empty.
+      # If there was no selector, then the current input node is returned in the array.
+      #
+      # @param _input [Array, Hash] the results of processing so far
+      # @param root [Array, Hash] the entire input
+      # @return [Array] Node List containing all results from evaluating this node's selectors.
+      def interpret(input, root)
+        if @next
+          @next.interpret(input, root)
+        else
+          input
+        end
+      end
+    end
+  end
+end

data/lib/janeway/interpreters/descendant_segment_interpreter.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Janeway
+  module Interpreters
+    # Find all descendants of the current input that match the selector in the DescendantSegment
+    class DescendantSegmentInterpreter < Base
+      alias descendant_segment node
+
+      # Find all descendants of the current input that match the selector in the DescendantSegment
+      #
+      # @param input [Array, Hash] the results of processing so far
+      # @param root [Array, Hash] the entire input
+      # @return [Array<AST::Expression>] node list
+      def interpret(input, root)
+        visit(input) do |node|
+          @next.interpret(node, root)
+        end
+      end
+
+      # Visit all descendants of `input`.
+      # Return results of applying `action` on each.
+      def visit(input, &action)
+        results = [yield(input)]
+
+        case input
+        when Array
+          results.concat(input.map { |elt| visit(elt, &action) })
+        when Hash
+          results.concat(input.values.map { |value| visit(value, &action) })
+        else
+          input
+        end
+
+        results.flatten(1).compact
+      end
+    end
+  end
+end

data/lib/janeway/interpreters/filter_selector_interpreter.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Janeway
+  module Interpreters
+    # Interprets a filter selector, returns results or forwards them to next selector
+    class FilterSelectorInterpreter < Base
+      alias selector node
+
+      # Set up the internal interpreter chain for the FilterSelector.
+      # @param selector [AST::FilterSelector]
+      def initialize(selector)
+        super
+        @expr = self.class.setup_interpreter_tree(selector)
+      end
+
+      # FIXME: should this be combined with similar func in Interpreter?
+      # FIXME: move this to a separate module?
+      #
+      # Set up a tree of interpreters which can process input for the filter expression.
+      # For a jsonpath query like '$.a[?@.b == $.x]', this sets up interpreters for '@.b == $.x'.
+      # @return [Interpreters::Base] root of the filter expression
+      def self.setup_interpreter_tree(selector)
+        TreeConstructor.ast_node_to_interpreter(selector.value)
+      end
+
+      # Interpret selector on the input.
+      # @param input [Array, Hash] the results of processing so far
+      # @param root [Array, Hash] the entire input
+      def interpret(input, root)
+        values =
+          case input
+          when Array then input
+          when Hash then input.values
+          else return [] # early exit
+          end
+
+        # Apply filter expressions to the input data
+        node_list = []
+        values.each do |value|
+          # Run filter and interpret result
+          result = @expr.interpret(value, root)
+          case result
+          when TrueClass then node_list << value # comparison test - pass
+          when FalseClass then nil # comparison test - fail
+          when Array then node_list << value unless result.empty? # existence test - node list
+          else
+            node_list << value # existence test. Null values here == success.
+          end
+        end
+        return node_list unless @next
+
+        # Apply child selector to each node in the output node list
+        results = []
+        node_list.each do |node|
+          results.concat @next.interpret(node, root)
+        end
+        results
+      end
+    end
+  end
+end

data/lib/janeway/interpreters/function_interpreter.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Janeway
+  module Interpreters
+    # Interprets a jsonpath function call within a filter selector.
+    class FunctionInterpreter < Base
+      alias function node
+
+      # Specify the parameter types that built-in JsonPath functions require
+      # @return [Hash<Symbol, Array<Symbol>] function name => list of parameter types
+      FUNCTION_PARAMETER_TYPES = {
+        length: [:value_type],
+        count: [:nodes_type],
+        match: %i[value_type value_type],
+        search: %i[value_type value_type],
+        value: [:nodes_type],
+      }.freeze
+
+      # @param [AST::Function]
+      def initialize(function)
+        super
+        @params = function.parameters.map { |param| TreeConstructor.ast_node_to_interpreter(param) }
+      end
+
+      # @param input [Array, Hash] the results of processing so far
+      # @param root [Array, Hash] the entire input
+      def interpret(input, root)
+        params = interpret_function_parameters(@params, input, root)
+        function.body.call(*params)
+      end
+
+      # Evaluate the expressions in the parameter list to make the parameter values
+      # to pass in to a JsonPath function.
+      #
+      # The node lists returned by a singular query must be deconstructed into a single value for
+      # parameters of ValueType, this is done here.
+      # For explanation:
+      # @see https://www.rfc-editor.org/rfc/rfc9535.html#name-well-typedness-of-function-
+      #
+      # @param parameters [Array] parameters before evaluation
+      # @param func [String] function name (eg. "length", "count")
+      # @param input [Object]
+      # @return [Array] parameters after evaluation
+      def interpret_function_parameters(parameters, input, root)
+        param_types = FUNCTION_PARAMETER_TYPES[function.name.to_sym]
+
+        parameters.map.with_index do |parameter, i|
+          type = param_types[i]
+          case parameter.node
+          when AST::CurrentNode, AST::RootNode
+            result = parameter.interpret(input, root)
+            if type == :value_type && parameter.node.singular_query?
+              deconstruct(result)
+            else
+              result
+            end
+          when AST::Function, AST::StringType then parameter.interpret(input, root)
+          when String then parameter.value # from a TreeConstructor::Literal
+          else
+            # invalid parameter type. Function must accept it and return Nothing result
+            parameter
+          end
+        end
+      end
+
+      # Prepare a value to be passed to as a parameter with type ValueType.
+      # Singular queries (see RFC) produce a node list containing one value.
+      # Return the value.
+      #
+      # Implements this part of the RFC:
+      #   > When the declared type of the parameter is ValueType and
+      #     the argument is one of the following:
+      #   > ...
+      #   >
+      #   > A singular query. In this case:
+      #   > * If the query results in a nodelist consisting of a single node,
+      #       the argument is the value of the node.
+      #   > * If the query results in an empty nodelist, the argument is
+      #       the special result Nothing.
+      #
+      # @param input [Object] usually an array - sometimes a basic type like String, Numeric
+      # @return [Object] basic type -- string or number
+      def deconstruct(input)
+        return input unless input.is_a?(Array)
+
+        if input.size == 1
+          # FIXME: what if it was a size 1 array that was intended to be a node not a node list? How to detect this?
+          input.first
+        elsif input.empty?
+          NOTHING
+        else
+          input # input is a single node, which happens to be an Array
+        end
+      end
+    end
+  end
+end

data/lib/janeway/interpreters/index_selector_interpreter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Janeway
+  module Interpreters
+    # Interprets an index selector, returns results or forwards them to next selector
+    #
+    # Filter the input by returning the array element with the given index.
+    # Return empty list if input is not an array, or if array does not contain index.
+    #
+    # Output is an array because all selectors must return node lists, even if
+    # they only select a single element.
+    #
+    # @param selector [IndexSelector]
+    # @param input [Array]
+    # @return [Array]
+    class IndexSelectorInterpreter < Base
+      alias selector node
+
+      # Interpret an index selector on the given input.
+      # NOTHING is selected, and it is not an error, if the index lies outside the range of the array.
+      # NOTHING is selected from a value that is not an array.
+      #
+      # @param input [Array, Hash] the results of processing so far
+      # @param root [Array, Hash] the entire input
+      def interpret(input, root)
+        return [] unless input.is_a?(Array)
+
+        result = input.fetch(selector.value) # raises IndexError if no such index
+        return [result] unless @next
+
+        @next.interpret(result, root)
+      rescue IndexError
+        []
+      end
+    end
+  end
+end

data/lib/janeway/interpreters/name_selector_interpreter.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Janeway
+  module Interpreters
+    # Interprets a name selector, returns results or forwards them to next selector
+    #
+    # Filters the input by returning the key that has the given name.
+    #
+    # Must differentiate between a null value of a key that exists (nil)
+    # and a key that does not exist ([])
+    class NameSelectorInterpreter < Base
+      alias selector node
+
+      # Interpret selector on the given input.
+      # @param input [Array, Hash] the results of processing so far
+      # @param root [Array, Hash] the entire input
+      def interpret(input, root)
+        return [] unless input.is_a?(Hash) && input.key?(selector.name)
+
+        result = input[selector.name]
+        return [result] unless @next
+
+        # Forward result to next selector
+        @next.interpret(result, root)
+      end
+    end
+  end
+end

data/lib/janeway/interpreters/root_node_interpreter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Janeway
+  module Interpreters
+    # Interprets the root identifer, returns results or forwards them to next selector.
+    #
+    # This is required at the beginning of every jsonpath query.
+    # It may also be used within filter selector expressions.
+    class RootNodeInterpreter < Base
+      # Start an expression chain using the entire, unfiltered input.
+      #
+      # @param _input [Array, Hash] the results of processing so far
+      # @param root [Array, Hash] the entire input
+      def interpret(_input, root)
+        return [root] unless @next
+
+        @next.interpret(root, root)
+      end
+    end
+  end
+end

data/lib/janeway/interpreters/tree_constructor.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Janeway
+  module Interpreters
+    # Constructs a tree of interpreter objects
+    module TreeConstructor
+      # Fake interpreter which just returns the given value
+      Literal = Struct.new(:value) do
+        def interpret(*)
+          value
+        end
+        alias_method :node, :interpret
+      end
+
+      def self.ast_node_to_interpreter(expr)
+        case expr
+        when AST::RootNode then Interpreters::RootNodeInterpreter.new(expr)
+        when AST::ArraySliceSelector then Interpreters::ArraySliceSelectorInterpreter.new(expr)
+        when AST::IndexSelector then Interpreters::IndexSelectorInterpreter.new(expr)
+        when AST::NameSelector then Interpreters::NameSelectorInterpreter.new(expr)
+        when AST::WildcardSelector then Interpreters::WildcardSelectorInterpreter.new(expr)
+        when AST::FilterSelector then Interpreters::FilterSelectorInterpreter.new(expr)
+        when AST::ChildSegment then Interpreters::ChildSegmentInterpreter.new(expr)
+        when AST::DescendantSegment then Interpreters::DescendantSegmentInterpreter.new(expr)
+        when AST::BinaryOperator then Interpreters::BinaryOperatorInterpreter.new(expr)
+        when AST::UnaryOperator then Interpreters::UnaryOperatorInterpreter.new(expr)
+        when AST::CurrentNode then Interpreters::CurrentNodeInterpreter.new(expr)
+        when AST::Function then Interpreters::FunctionInterpreter.new(expr)
+        when AST::StringType, AST::Number, AST::Null, AST::Boolean then Literal.new expr.value
+        when nil then nil # caller has no @next node
+        else
+          raise "Unknown AST expression: #{expr.inspect}"
+        end
+      end
+    end
+  end
+end