janeway-jsonpath 0.3.0 → 0.4.0

data/lib/janeway/interpreter.rb

@@ -11,6 +11,7 @@ module Janeway
   # It should be created for a single query and then discarded.
   class Interpreter
     attr_reader :jsonpath, :output
+    include Interpreters
 
     # Interpret a query on the given input, return result
     # @param input [Hash, Array]
@@ -21,25 +22,38 @@ module Janeway
       new(ast).interpret(input)
     end
 
-    # @param query [AST::Query] abstract syntax tree of the jsonpath query
-    def initialize(query)
-      raise ArgumentError, "expect AST::Query, got #{query.inspect}" unless query.is_a?(AST::Query)
+    # @param query [Query] abstract syntax tree of the jsonpath query
+    def initialize(query, as: :finder, &block)
+      raise ArgumentError, "expect Query, got #{query.inspect}" unless query.is_a?(Query)
+      unless %i[finder iterator deleter].include?(as)
+        raise ArgumentError, "invalid interpreter type: #{as.inspect}"
+      end
 
       @query = query
+      @type = as
       @jsonpath = query.jsonpath
-      @input = nil
-      @pipeline = query_to_interpreter_pipeline(@query)
+      @root = query_to_interpreter_tree(@query, &block)
+    end
+
+    # Return multiline JSON string describing the interpreter tree.
+    #
+    # This is not used for parsing / interpretation.
+    # It is intended to represent the interpreter tree to help with debugging.
+    # This format makes the tree structure much clearer than the #inspect output does.
+    #
+    # @return [String]
+    def to_json(options = {})
+      JSON.pretty_generate(@root.as_json, *options)
     end
 
     # @param input [Array, Hash] object to be searched
     # @return [Object]
     def interpret(input)
-      @input = input
-      unless @input.is_a?(Hash) || @input.is_a?(Array)
+      unless input.is_a?(Hash) || input.is_a?(Array)
         return [] # can't query on any other types, but need to check because a string is also valid json
       end
 
-      @pipeline.first.interpret(nil, input)
+      @root.interpret(nil, nil, input, [])
     rescue StandardError => e
       # Error during interpretation. Convert it to a Janeway::Error and include the query in the message
       error = err(e.message)
@@ -47,24 +61,57 @@ module Janeway
       raise error
     end
 
-    # Append an interpreter onto the end of the pipeline
-    # @param [Interpreters::Base]
-    def push(node)
-      @pipeline.last.next = node
-    end
-
     private
 
+    # Build a tree of interpreter classes based on the query's abstract syntax tree.
+    #
+    # Child segments require special handling.
+    # See the detailed explanation at the end of this file.
+    #
     # @return [Interpreters::RootNodeInterpreter]
-    def query_to_interpreter_pipeline(query)
-      pipeline =
+    def query_to_interpreter_tree(query, &block)
+      # Build an interpreter for each selector
+      interpreters =
         query.node_list.map do |node|
           Interpreters::TreeConstructor.ast_node_to_interpreter(node)
         end
-      pipeline.each_with_index do |node, i|
-        node.next = pipeline[i + 1]
+
+      # Append iterotor / deleter as needed, to support #each, #delete operations
+      case @type
+      when :iterator then interpreters.push(Yielder.new(&block))
+      when :deleter then interpreters.push make_deleter(interpreters.pop)
+      end
+
+      # Link interpreters together
+      interpreters.each_with_index do |node, i|
+        node.next = interpreters[i + 1]
       end
-      pipeline
+
+      # Child segments which contain multiple selectors are branches in the interpreter tree.
+      #
+      # For every child segment, remove all following interpreters and push
+      # them "inside" the child segment interpreter.
+      #
+      # Work backwards in case there are multiple child segments.
+      # For full explanation see the explanation at the end of this file.
+      selectors = []
+      interpreters.reverse_each do |node|
+        if node.is_a?(Interpreters::ChildSegmentInterpreter)
+          node.next = nil
+          node.push(selectors.pop) until selectors.empty?
+          selectors = [node]
+        else
+          selectors << node
+        end
+      end
+
+      selectors.last
+    end
+
+    # Make a Deleter that will delete the results matched by a Selector.
+    # @param interpreter [Interpreters::Base] interpeter subclass
+    def make_deleter(interpreter)
+      TreeConstructor.ast_node_to_deleter(interpreter.node)
     end
 
     # Return an Interpreter::Error with the specified message, include the query.
@@ -76,3 +123,61 @@ module Janeway
     end
   end
 end
+__END__
+= Child Segment Handling
+
+== Interpreter Tree Layout
+
+The interpreter tree is a straight line of filter into filter, except for the case of child segments
+(brackets) that contain multiple selectors, eg. "$.store['bicycle', 'book']".
+
+Such child segments are branches in the tree.
+
+In Janeway, child segments that contain only one selector are not represented
+in the AST, only the selector itself is an AST node.
+For the remainder of this explanation, the term 'child segment' refers to child
+segments that contain multiple selectors.
+
+== Child segment evaluation -- original approach and problem
+
+The obvious approach to interpreting a child segment is to send the input to
+each of the selectors, combine the resulting values, and forward that to then
+'next' selector which follows the child segment.
+This is how I originally implemented the Janeway interpeter.
+
+That approach works fine when only values are being collected.
+However Janeway now supports iteration with #each, so each interpretation 
+step carries along some new context information:  the parent (object which
+contains the current input value) and the path (list of array indices or hash
+keys which define the path to the current input).
+
+Interpreting a child segment by interpeting its selectors separately and combining the results
+discards all of that context.  Fully interpreting selectors only returns
+values, not the parent or path data.
+
+== Child segment evaluation -- new approach
+
+Instead, embrace the idea of the child segment being a branch in the tree.
+
+Take the chain of selectors which comes after the child segment, and copy that chain
+onto the selectors inside the child segment.
+
+Consider this jsonpath:
+    $.store['book', 'bicycle'].price
+
+In the first approach, the interpretation tree has a diamond:
+
+             bicycle
+    $ store <          > price
+              book
+
+In the new approach, the interpretation tree splits into two separate branches
+
+              bicycle - price
+    $ store <
+              book - price
+
+This way, the parent and path information is passed down normally to the following selectors.
+
+When a Yielder is pushed onto the interpreter tree, copies of it must be pushed onto
+the end of every branch.

data/lib/janeway/interpreters/array_slice_selector_deleter.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Janeway
+  module Interpreters
+    # Interprets array slice selector and deletes matching values
+    class ArraySliceSelectorDeleter < ArraySliceSelectorInterpreter
+      # Delete values at the indices matched by the array slice selector
+      #
+      # @param input [Array, Hash] the results of processing so far
+      # @param _parent [Array, Hash] parent of the input object
+      # @param _root [Array, Hash] the entire input
+      # @param _path [Array<String>] elements of normalized path to the current input
+      # @return [Array]
+      def interpret(input, _parent, _root, _path)
+        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)
+
+        # Convert bounds and step to index values.
+        # Omit the final index, since no value is collected for that.
+        # Delete indexes from largest to smallest, so that deleting an index does
+        # not change the remaining indexes
+        results = []
+        if selector.step.positive?
+          indexes = lower.step(to: upper - 1, by: selector.step).to_a
+          indexes.reverse_each { |i| results << input.delete_at(i) }
+          results.reverse
+        else
+          indexes = upper.step(to: lower + 1, by: selector.step).to_a
+          indexes.each { |i| results << input.delete_at(i) }
+          results
+        end
+      end
+    end
+  end
+end

data/lib/janeway/interpreters/array_slice_selector_interpreter.rb

@@ -10,11 +10,12 @@ module Janeway
 
       # Filter the input by applying the array slice selector.
       #
-      # @param selector [ArraySliceSelector]
       # @param input [Array, Hash] the results of processing so far
+      # @param _parent [Array, Hash] parent of the input object
       # @param root [Array, Hash] the entire input
+      # @param path [Array<String>] elements of normalized path to the current input
       # @return [Array]
-      def interpret(input, root)
+      def interpret(input, _parent, root, path)
         return [] unless input.is_a?(Array)
         return [] if selector&.step&.zero? # RFC: When step is 0, no elements are selected.
 
@@ -22,23 +23,27 @@ module Janeway
         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 =
+        # Collect real index values. Omit the final index, since no value is collected for that.
+        indexes =
           if selector.step.positive?
-            lower.step(to: upper - 1, by: selector.step).map { input[_1] }
+            lower.step(to: upper - 1, by: selector.step).to_a
           else
-            upper.step(to: lower + 1, by: selector.step).map { input[_1] }
+            upper.step(to: lower + 1, by: selector.step).to_a
           end
-        return results unless @next
+        return indexes.map { |i| input[i] } 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)
+        indexes.each do |i|
+          results.concat @next.interpret(input[i], input, root, path + [i])
         end
         results
       end
+
+      # @return [Hash]
+      def as_json
+        { type: type, value: node.to_s, next: @next&.as_json }.compact
+      end
     end
   end
 end

data/lib/janeway/interpreters/base.rb

@@ -33,11 +33,35 @@ module Janeway
 
       # 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
+      # @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
+
+      # @return [String]
+      def to_s
+        @node.to_s
+      end
+
+      # Return hash representation of this selector interpreter
+      # @return [Hash]
+      def as_json
+        if node
+          { type: type, value: node&.value, next: @next&.as_json }.compact
+        else
+          { type: type, next: @next&.as_json }.compact
+        end
+      end
+
+      # @return [AST::Selector] AST node containing this interpreter's data
+      def selector
+        nil # subclass should implement
+      end
+
+      def type
+        self.class.to_s.split('::').last # eg. Janeway::AST::FunctionCall => "FunctionCall"
+      end
     end
   end
 end

data/lib/janeway/interpreters/binary_operator_interpreter.rb

@@ -24,17 +24,20 @@ module Janeway
       # 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 parent [Array, Hash] parent of the input object
       # @param root [Array, Hash] the entire input
-      def interpret(input, root)
+      # @param _path [Array] ignored
+      def interpret(input, parent, root, _path = nil)
+        # FIXME: this branch could be pushed into the constructor, to convert O(n) work to O(1)
         case operator.name
         when :and, :or
           # handle node list for existence check
-          lhs = @left.interpret(input, root)
-          rhs = @right.interpret(input, root)
+          lhs = @left.interpret(input, parent, root, [])
+          rhs = @right.interpret(input, parent, 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)
+          lhs = to_single_value @left.interpret(input, parent, root, [])
+          rhs = to_single_value @right.interpret(input, parent, root, [])
         else
           raise "Don't know how to handle binary operator #{operator.name.inspect}"
         end
@@ -54,8 +57,8 @@ module Janeway
       # 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]
+      # @param result [Object] node list, or single value of basic type
+      # @return [String, Integer, nil]
       def to_single_value(result)
         # Return basic types (ie. from AST::Number, AST::StringType, AST::Null)
         return result unless result.is_a?(Array)

data/lib/janeway/interpreters/child_segment_deleter.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'child_segment_interpreter'
+
+module Janeway
+  module Interpreters
+    # Child segment interpreter with selectors that delete matching elements
+    class ChildSegmentDeleter < ChildSegmentInterpreter 
+      # @param child_segment [AST::ChildSegment]
+      def initialize(child_segment)
+        super
+        @selectors =
+          child_segment.map do |expr|
+            TreeConstructor.ast_node_to_deleter(expr)
+          end
+      end
+    end
+  end
+end

data/lib/janeway/interpreters/child_segment_interpreter.rb

@@ -15,29 +15,69 @@ module Janeway
       # @param child_segment [AST::ChildSegment]
       def initialize(child_segment)
         super
-        @nodes =
+        @selectors =
           child_segment.map do |expr|
             TreeConstructor.ast_node_to_interpreter(expr)
           end
       end
 
+      # Append an interpreter onto each of the selector branches
+      # @param node [Interpreters::Base]
+      def push(node)
+        return unless node
+
+        node.next = nil
+        @selectors.each do |selector|
+          last_node = find_last(selector)
+          if last_node.is_a?(Interpreters::ChildSegmentInterpreter)
+            last_node.push(node.dup)
+          else
+            last_node.next = node.dup
+          end
+        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.
+      # All selectors are sent identical input, the results are combined.
       #
       # @param input [Array, Hash] the results of processing so far
+      # @param parent [Array, Hash] parent of the input object
       # @param root [Array, Hash] the entire input
+      # @param path [Array<String>] elements of normalized path to the current input
       # @return [Array]
-      def interpret(input, root)
+      def interpret(input, parent, root, path)
         # Apply each expression to the input, collect results
         results = []
-        @nodes.each do |node|
-          results.concat node.interpret(input, root)
+        @selectors.each do |selector|
+          results.concat selector.interpret(input, parent, root, path)
         end
 
-        # Return results, or forward them to the next selector
-        return results unless @next
+        results
+      end
 
-        @next.interpret(results, root)
+      # Return hash representation of this interpreter
+      # @return [Hash]
+      def as_json
+        {
+          type: type,
+          selectors: @selectors.map(&:as_json),
+          next: @next&.as_json,
+        }
+      end
+
+      private
+
+      # Find the last descendant of the given selector (ie. first one with no "next" selector)
+      # @param selector [Interpreters::Base]
+      # @return [Interpreters::Base]
+      def find_last(selector)
+        node = selector
+        loop do
+          break unless node.next
+
+          node = node.next
+        end
+        node
       end
     end
   end

data/lib/janeway/interpreters/current_node_interpreter.rb

@@ -18,12 +18,14 @@ module Janeway
       # 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 input [Array, Hash] the results of processing so far
+      # @param parent [Array, Hash] parent of the input object
       # @param root [Array, Hash] the entire input
+      # @param _path [Array] ignored
       # @return [Array] Node List containing all results from evaluating this node's selectors.
-      def interpret(input, root)
+      def interpret(input, parent, root, _path)
         if @next
-          @next.interpret(input, root)
+          @next.interpret(input, parent, root, [])
         else
           input
         end

data/lib/janeway/interpreters/descendant_segment_interpreter.rb

@@ -11,27 +11,31 @@ module Janeway
       # 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 parent [Array, Hash] parent of the input object
       # @param root [Array, Hash] the entire input
+      # @param path [Array<String>] elements of normalized path to the current input
       # @return [Array<AST::Expression>] node list
-      def interpret(input, root)
-        visit(input) do |node|
-          @next.interpret(node, root)
+      def interpret(input, parent, root, path)
+        visit(input, parent, path) do |node, parent_of_node, sub_path|
+          @next.interpret(node, parent_of_node, root, sub_path)
         end
       end
 
       # Visit all descendants of `input`.
       # Return results of applying `action` on each.
-      def visit(input, &action)
-        results = [yield(input)]
+      # @param input [Array, Hash] the results of processing so far
+      # @param path [Array<String>] elements of normalized path to the current input
+      # @param parent [Array, Hash] parent of the input object
+      def visit(input, parent, path, &block)
+        results = [yield(input, parent, path)]
 
         case input
         when Array
-          results.concat(input.map { |elt| visit(elt, &action) })
+          results.concat(input.map.with_index { |value, i| visit(value, input, path + [i], &block) })
         when Hash
-          results.concat(input.values.map { |value| visit(value, &action) })
-        else
-          input
+          results.concat(input.map { |key, value| visit(value, input, path + [key], &block) })
         end
+        # basic types are ignored, they will be added by one of the above
 
         results.flatten(1).compact
       end

data/lib/janeway/interpreters/filter_selector_deleter.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Janeway
+  module Interpreters
+    # Interprets a filter selector, and deletes matching values
+    class FilterSelectorDeleter < FilterSelectorInterpreter
+      # Interpret selector on the input.
+      # @param input [Hash] the results of processing so far
+      # @param root [Array, Hash] the entire input
+      # @param _path [Array<String>] elements of normalized path to the current input
+      def interpret_hash(input, root, _path)
+        # Apply filter expressions to the input data
+        results = []
+        input.each do |key, value|
+          # Run filter and interpret result
+          result = @expr.interpret(value, nil, root, [])
+          case result
+          when TrueClass then results << value # comparison test - pass
+          when FalseClass then next # comparison test - fail
+          when Array
+            next if result.empty?
+
+            results << value # existence test - node list
+          else
+            results << value # existence test. Null values here == success.
+          end
+          input.delete(key)
+        end
+        results
+      end
+
+      # Interpret selector on the input.
+      # @param input [Array] the results of processing so far
+      # @param root [Array, Hash] the entire input
+      # @param _path [Array<String>] elements of normalized path to the current input
+      def interpret_array(input, root, _path)
+        # Apply filter expressions to the input data
+        results = []
+
+        # Iterate in reverse order so that deletion does not alter the remaining indexes
+        i = input.size
+        input.reverse_each do |value|
+          i -= 1 # calculate array index
+
+          # Run filter and interpret result
+          result = @expr.interpret(value, nil, root, [])
+          case result
+          when TrueClass then results << value # comparison test - pass
+          when FalseClass then next # comparison test - fail
+          when Array
+            next if result.empty?
+
+            results << value # existence test - node list
+          else
+            results << value # existence test. Null values here == success.
+          end
+          input.delete_at(i)
+        end
+        results.reverse
+      end
+    end
+  end
+end

data/lib/janeway/interpreters/filter_selector_interpreter.rb

@@ -27,37 +27,77 @@ module Janeway
 
       # Interpret selector on the input.
       # @param input [Array, Hash] the results of processing so far
+      # @param _parent [Array, Hash] parent of the input object
       # @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
+      # @param path [Array<String>] elements of normalized path to the current input
+      def interpret(input, _parent, root, path)
+        case input
+        when Array then interpret_array(input, root, path)
+        when Hash then interpret_hash(input, root, path)
+        else [] # early exit
+        end
+      end
+
+      # Interpret selector on the input.
+      # @param input [Hash] the results of processing so far
+      # @param root [Array, Hash] the entire input
+      # @param path [Array<String>] elements of normalized path to the current input
+      def interpret_hash(input, root, path)
+        # Apply filter expressions to the input data
+        node_list = []
+        input.each do |key, value|
+          # Run filter and interpret result
+          result = @expr.interpret(value, nil, root, [])
+          case result
+          when TrueClass then node_list << [key, value] # comparison test - pass
+          when FalseClass then nil # comparison test - fail
+          when Array then node_list << [key, value] unless result.empty? # existence test - node list
+          else
+            node_list << [key, value] # existence test. Null values here == success.
           end
+        end
+        return node_list.map(&:last) unless @next
 
+        # Apply child selector to each node in the output node list
+        results = []
+        node_list.each do |key, value|
+          results.concat @next.interpret(value, input, root, path + [key])
+        end
+        results
+      end
+
+      # Interpret selector on the input.
+      # @param input [Array] the results of processing so far
+      # @param root [Array, Hash] the entire input
+      # @param path [Array<String>] elements of normalized path to the current input
+      def interpret_array(input, root, path)
         # Apply filter expressions to the input data
         node_list = []
-        values.each do |value|
+        input.each_with_index do |value, i|
           # Run filter and interpret result
-          result = @expr.interpret(value, root)
+          result = @expr.interpret(value, nil, root, [])
           case result
-          when TrueClass then node_list << value # comparison test - pass
+          when TrueClass then node_list << [i, value] # comparison test - pass
           when FalseClass then nil # comparison test - fail
-          when Array then node_list << value unless result.empty? # existence test - node list
+          when Array then node_list << [i, value] unless result.empty? # existence test - node list
           else
-            node_list << value # existence test. Null values here == success.
+            node_list << [i, value] # existence test. Null values here == success.
           end
         end
-        return node_list unless @next
+        return node_list.map(&:last) 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)
+        node_list.each do |i, value|
+          results.concat @next.interpret(value, input, root, path + [i])
         end
         results
       end
+
+      # @return [Hash]
+      def as_json
+        { type: type, value: node.to_s, next: @next&.as_json }.compact
+      end
     end
   end
 end