janeway-jsonpath 0.6.0 → 1.1.0

data/lib/janeway/error.rb

@@ -20,7 +20,12 @@ module Janeway
     # @param query [String] entire query string
     # @param location [Location] location of error
     def initialize(msg, query = nil, location = nil)
-      super("Jsonpath query #{query} - #{msg}")
+      full = +''
+      full << "Jsonpath query #{query}" if query
+      full << " (col #{location.col})" if location
+      full << ' - ' unless full.empty?
+      full << msg
+      super(full)
       @query = query
       @location = location
     end

data/lib/janeway/functions/count.rb

@@ -29,14 +29,7 @@ module Janeway
       raise Error, "Invalid parameter - count() expects node list, got #{arg.value.inspect}" if arg.literal?
       raise Error, 'Too many parameters for count() function call' unless current.type == :group_end
 
-      # Define function body
-      AST::Function.new('count', parameters) do |node_list|
-        if node_list.is_a?(Array)
-          node_list.size
-        else
-          1 # the count of a non-empty singular nodelist such as count(@) is always 1.
-        end
-      end
+      AST::Function.new('count', parameters)
     end
   end
 end

data/lib/janeway/functions/length.rb

@@ -21,18 +21,7 @@ module Janeway
       end
       raise err('Too many parameters for length() function call') unless current.type == :group_end
 
-      # Meaning of return value depends on the JSON type:
-      #   * string - number of Unicode scalar values in the string.
-      #   * array -  number of elements in the array.
-      #   * object - number of members in the object.
-      # For any other argument value, the result is the special result Nothing.
-      AST::Function.new('length', parameters) do |value|
-        if [Array, Hash, String].include?(value.class)
-          value.size
-        else
-          :nothing
-        end
-      end
+      AST::Function.new('length', parameters)
     end
   end
 end

data/lib/janeway/functions/match.rb

@@ -52,14 +52,9 @@ module Janeway
       parameters << parse_function_parameter
       raise Error, 'Too many parameters for match() function call' unless current.type == :group_end
 
-      AST::Function.new('match', parameters) do |str, str_iregexp|
-        if str.is_a?(String) && str_iregexp.is_a?(String)
-          regexp = translate_iregex_to_ruby_regex(str_iregexp)
-          regexp.match?(str)
-        else
-          false # result defined by RFC9535
-        end
-      end
+      # Body (including literal-regex fast path) is supplied by
+      # Functions::REGISTRY at FunctionInterpreter construction time.
+      AST::Function.new('match', parameters)
     end
   end
 end

data/lib/janeway/functions/search.rb

@@ -47,14 +47,9 @@ module Janeway
       parameters << parse_function_parameter
       raise Error, 'Too many parameters for match() function call' unless current.type == :group_end
 
-      AST::Function.new('search', parameters) do |str, str_iregexp|
-        if str.is_a?(String) && str_iregexp.is_a?(String)
-          regexp = translate_iregex_to_ruby_regex(str_iregexp, anchor: false)
-          regexp.match?(str)
-        else
-          false # result defined by RFC9535
-        end
-      end
+      # Body (including literal-regex fast path) is supplied by
+      # Functions::REGISTRY at FunctionInterpreter construction time.
+      AST::Function.new('search', parameters)
     end
   end
 end

data/lib/janeway/functions/value.rb

@@ -36,13 +36,7 @@ module Janeway
       parameters = [parse_function_parameter]
       raise Error, 'Too many parameters for value() function call' unless current.type == :group_end
 
-      AST::Function.new('value', parameters) do |nodes|
-        if nodes.is_a?(Array) && nodes.size == 1
-          nodes.first
-        else
-          :nothing
-        end
-      end
+      AST::Function.new('value', parameters)
     end
   end
 end

data/lib/janeway/functions.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 require_relative 'ast/function'
+require_relative 'ast/string_type'
 
 module Janeway
-  # Mixin to provide JSONPath function handlers for Parser
+  # Mixin to provide JSONPath function handlers for Parser, plus the shared
+  # I-Regexp translation helper and the built-in function registry.
   module Functions
     # Convert IRegexp format to ruby regexp equivalent, following the instructions in rfc9485.
     # @see https://www.rfc-editor.org/rfc/rfc9485.html#name-pcre-re2-and-ruby-regexps
@@ -35,6 +37,7 @@ module Janeway
       regex_str = anchor ? format('\A(?:%s)\z', chars.join) : chars.join
       Regexp.new(regex_str)
     end
+    module_function :translate_iregex_to_ruby_regex
 
     # All jsonpath function parameters are one of these accepted types.
     # Parse the function parameter and return the result.
@@ -54,10 +57,80 @@ module Janeway
       consume
       result
     end
+
+    # Build a match/search body. When the pattern is a StringType literal we
+    # compile the regex once at parse time (see perf pass, commit fd8b92a).
+    # Otherwise fall back to per-call compilation.
+    def self.build_regex_body(parameters, anchor:)
+      literal_regexp =
+        if parameters[1].is_a?(AST::StringType)
+          begin
+            translate_iregex_to_ruby_regex(parameters[1].value, anchor: anchor)
+          rescue RegexpError
+            nil # fall back to per-call compilation, which will raise at eval time
+          end
+        end
+
+      if literal_regexp
+        ->(str, _pattern) { str.is_a?(String) && literal_regexp.match?(str) }
+      else
+        lambda do |str, pattern|
+          if str.is_a?(String) && pattern.is_a?(String)
+            translate_iregex_to_ruby_regex(pattern, anchor: anchor).match?(str)
+          else
+            false
+          end
+        end
+      end
+    end
+
+    # Metadata + body builder for every built-in JSONPath function.
+    #
+    #   arity          — number of parameters
+    #   literal_return — true when the result is a literal (see RFC 9535
+    #                    well-typedness of function extensions)
+    #   build          — proc that takes the parsed `parameters` list and
+    #                    returns the body proc (parameters allow per-instance
+    #                    optimization, e.g. literal-regex compilation)
+    REGISTRY = {
+      'count' => {
+        arity: 1,
+        literal_return: true,
+        build: ->(_) { ->(nodes) { nodes.is_a?(Array) ? nodes.size : 1 } },
+      },
+      'length' => {
+        arity: 1,
+        literal_return: true,
+        build: lambda { |_|
+          lambda { |value|
+            [Array, Hash, String].include?(value.class) ? value.size : :nothing
+          }
+        },
+      },
+      'value' => {
+        arity: 1,
+        literal_return: true,
+        build: lambda { |_|
+          lambda { |nodes|
+            nodes.is_a?(Array) && nodes.size == 1 ? nodes.first : :nothing
+          }
+        },
+      },
+      'match' => {
+        arity: 2,
+        literal_return: false,
+        build: ->(parameters) { Functions.build_regex_body(parameters, anchor: true) },
+      },
+      'search' => {
+        arity: 2,
+        literal_return: false,
+        build: ->(parameters) { Functions.build_regex_body(parameters, anchor: false) },
+      },
+    }.freeze
   end
 end
 
-# Require function definitions
+# Require function parse-method definitions
 Dir.children("#{__dir__}/functions/").each do |path|
   require_relative "functions/#{path[0..-4]}"
 end

data/lib/janeway/interpreter.rb

@@ -33,7 +33,7 @@ module Janeway
       @query = query
       @type = as
       @jsonpath = query.jsonpath
-      @root = query_to_interpreter_tree(@query, &block)
+      @root = query.interpreter_tree_for(@type) { query_to_interpreter_tree(@query, &block) }
     end
 
     # Return multiline JSON string describing the interpreter tree.
@@ -50,70 +50,85 @@ module Janeway
     # @param input [Array, Hash] object to be searched
     # @return [Object]
     def interpret(input)
-      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
-
       @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)
-      error.set_backtrace e.backtrace
-      raise error
+    rescue Janeway::Error => e
+      # Reformat known interpretation errors to include the query in the message.
+      # Real bugs (NoMethodError, TypeError, NameError, ...) are intentionally
+      # NOT caught here — they should surface with a real backtrace, not be
+      # masked as "Jsonpath query ..." messages.
+      raise if e.query # already annotated
+
+      annotated = err(e.message)
+      annotated.set_backtrace e.backtrace
+      raise annotated
     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.
+    # Four phases, one per private helper:
+    #   1. build_interpreters  — one interpreter per AST node
+    #   2. append_terminal     — Yielder / Deleter / DeleteIf for the caller's mode
+    #   3. link_next_pointers  — wire each interpreter to the next one
+    #   4. rewire_child_segments — push tail selectors into each ChildSegmentInterpreter
+    #      (branch rewrite explained in the docstring at the end of this file)
     #
     # @return [Interpreters::RootNodeInterpreter]
     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
+      interpreters = build_interpreters(query)
+      append_terminal(interpreters, &block)
+      link_next_pointers(interpreters)
+      rewire_child_segments(interpreters)
+    end
 
-      # Append iterotor / deleter as needed, to support #each, #delete operations
+    # Phase 1: one interpreter per AST node in the query's top-level chain.
+    def build_interpreters(query)
+      query.node_list.map { |node| Interpreters::TreeConstructor.ast_node_to_interpreter(node) }
+    end
+
+    # Phase 2: append the terminal interpreter that matches the caller's mode.
+    # Deleter / delete_if REPLACE the last selector (the terminal semantics
+    # live in the leaf itself); iterator APPENDS a Yielder after it.
+    def append_terminal(interpreters, &block)
       case @type
       when :iterator then interpreters.push(Yielder.new(&block))
-      when :deleter then interpreters.push make_deleter(interpreters.pop)
-      when :delete_if then interpreters.push make_delete_if(interpreters.pop, &block)
+      when :deleter then interpreters.push(make_deleter(interpreters.pop))
+      when :delete_if then interpreters.push(make_delete_if(interpreters.pop, &block))
       end
+    end
 
-      # Link interpreters together
+    # Phase 3: link `.next` from each interpreter to the following one.
+    def link_next_pointers(interpreters)
       interpreters.each_with_index do |node, i|
         node.next = interpreters[i + 1]
       end
+    end
 
-      # 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 = []
+    # Phase 4: for every ChildSegmentInterpreter, remove the interpreters that
+    # follow it in the flat chain and push them into the child segment as
+    # branches. Work backwards so nested child segments compose correctly.
+    # @return [Interpreters::Base] root of the resulting tree
+    def rewire_child_segments(interpreters)
+      pending = []
       interpreters.reverse_each do |node|
         if node.is_a?(Interpreters::ChildSegmentInterpreter)
           node.next = nil
-          node.push(selectors.pop) until selectors.empty?
-          selectors = [node]
+          node.push(pending.pop) until pending.empty?
+          pending = [node]
         else
-          selectors << node
+          pending << node
         end
       end
-
-      selectors.last
+      pending.last
     end
 
     # Make a Deleter that will delete the results matched by a Selector.
+    # Implemented as a DeleteIf with the PASS_ALL sentinel block — the
+    # separate Deleter classes were folded into DeleteIf.
     # @param interpreter [Interpreters::Base] interpeter subclass
     def make_deleter(interpreter)
-      TreeConstructor.ast_node_to_deleter(interpreter.node)
+      TreeConstructor.ast_node_to_delete_if(interpreter.node, &Interpreters::IterationHelper::PASS_ALL)
     end
 
     # Make a DeleteIf that will delete the results matched by a Selector,

data/lib/janeway/interpreters/array_slice_selector_delete_if.rb

@@ -27,19 +27,13 @@ module Janeway
       # @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.
+        return [] if effective_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
+        # Delete matching indexes from largest to smallest so that deletion
+        # does not shift the remaining indexes.
+        indexes = index_range(input.size)
         results = []
-        if selector.step.positive?
-          indexes = lower.step(to: upper - 1, by: selector.step).to_a
+        if effective_step.positive?
           indexes.reverse_each do |i|
             next unless @yield_proc.call(input[i], input, path + [i])
 
@@ -47,8 +41,11 @@ module Janeway
           end
           results.reverse
         else
-          indexes = upper.step(to: lower + 1, by: selector.step).to_a
-          indexes.each { |i| results << input.delete_at(i) }
+          indexes.each do |i|
+            next unless @yield_proc.call(input[i], input, path + [i])
+
+            results << input.delete_at(i)
+          end
           results
         end
       end

data/lib/janeway/interpreters/array_slice_selector_interpreter.rb

@@ -17,19 +17,9 @@ module Janeway
       # @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)
-
-        # 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).to_a
-          else
-            upper.step(to: lower + 1, by: selector.step).to_a
-          end
+        return [] if effective_step.zero? # RFC: When step is 0, no elements are selected.
+
+        indexes = index_range(input.size)
         return indexes.map { |i| input[i] } unless @next
 
         # Apply child selector to each node in the output node list
@@ -44,6 +34,59 @@ module Janeway
       def as_json
         { type: type, value: node.to_s, next: @next&.as_json }.compact
       end
+
+      protected
+
+      # Concrete list of source-array indexes this slice selects, in
+      # iteration order. Consumed by both this interpreter and
+      # ArraySliceSelectorDeleteIf.
+      #
+      # @param input_size [Integer]
+      # @return [Array<Integer>]
+      def index_range(input_size)
+        lower, upper = bounds(input_size)
+        if effective_step.positive?
+          lower.step(to: upper - 1, by: effective_step).to_a
+        else
+          upper.step(to: lower + 1, by: effective_step).to_a
+        end
+      end
+
+      # Effective step: raw @step from the AST, or 1 if unspecified.
+      def effective_step
+        selector.step || 1
+      end
+
+      # Compute lower/upper bounds for the slice given the input array size.
+      # RFC 9535 pseudocode lives here (formerly on AST::ArraySliceSelector).
+      # @see https://www.rfc-editor.org/rfc/rfc9535.html#section-2.3.4.2.2
+      #
+      # @param input_size [Integer]
+      # @return [Array(Integer, Integer)] [lower, upper]
+      def bounds(input_size)
+        if effective_step >= 0
+          start = selector.start || 0
+          end_ = selector.end || input_size
+        else
+          start = selector.start || (input_size - 1)
+          end_ = selector.end || ((-1 * input_size) - 1)
+        end
+
+        n_start = normalize(start, input_size)
+        n_end = normalize(end_, input_size)
+
+        if effective_step >= 0
+          [n_start.clamp(0, input_size), n_end.clamp(0, input_size)]
+        else
+          [n_end.clamp(-1, input_size - 1), n_start.clamp(-1, input_size - 1)]
+        end
+      end
+
+      # IETF: slice parameters must be normalized before use as bounds —
+      # negative values count from the end of the array.
+      def normalize(index, len)
+        index >= 0 ? index : len + index
+      end
     end
   end
 end

data/lib/janeway/interpreters/binary_operator_interpreter.rb

@@ -13,6 +13,18 @@ module Janeway
         super
         @left = TreeConstructor.ast_node_to_interpreter(operator.left)
         @right = TreeConstructor.ast_node_to_interpreter(operator.right)
+
+        # Bind the per-op behavior at construction time to avoid dispatching
+        # on operator.name and allocating a symbol on every candidate value.
+        case operator.name
+        when :and, :or
+          @extract_single_value = false
+        when :equal, :not_equal, :less_than, :greater_than, :less_than_or_equal, :greater_than_or_equal
+          @extract_single_value = true
+        else
+          raise "Don't know how to handle binary operator #{operator.name.inspect}"
+        end
+        @op = method(:"interpret_#{operator.name}")
       end
 
       # The binary operators are all comparison operators that test equality.
@@ -28,20 +40,13 @@ module Janeway
       # @param root [Array, Hash] the entire input
       # @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, 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, parent, root, [])
-          rhs = to_single_value @right.interpret(input, parent, root, [])
-        else
-          raise "Don't know how to handle binary operator #{operator.name.inspect}"
+        lhs = @left.interpret(input, parent, root, [])
+        rhs = @right.interpret(input, parent, root, [])
+        if @extract_single_value
+          lhs = to_single_value(lhs)
+          rhs = to_single_value(rhs)
         end
-        send(:"interpret_#{operator.name}", lhs, rhs)
+        @op.call(lhs, rhs)
       end
 
       # Interpret a node and extract its value, in preparation for using the node

data/lib/janeway/interpreters/descendant_segment_interpreter.rb

@@ -21,23 +21,42 @@ module Janeway
         end
       end
 
-      # Visit all descendants of `input`.
-      # Return results of applying `action` on each.
+      # Visit all descendants of `input` and concatenate the results of
+      # `block` at each node. Iterative depth-first pre-order — a recursive
+      # implementation would risk SystemStackError on deep JSON and allocated
+      # an array-per-node plus a flatten pass.
+      #
       # @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)]
+      # @param path [Array<String>] elements of normalized path to the current input
+      def visit(input, parent, path)
+        results = []
+        stack = [[input, parent, path]]
+        until stack.empty?
+          node, node_parent, node_path = stack.pop
+          results.concat(yield(node, node_parent, node_path))
 
-        case input
-        when Array
-          results.concat(input.map.with_index { |value, i| visit(value, input, path + [i], &block) })
-        when Hash
-          results.concat(input.map { |key, value| visit(value, input, path + [key], &block) })
+          case node
+          when Array
+            # Push in reverse so the leftmost child is popped first (pre-order).
+            i = node.size - 1
+            while i >= 0
+              stack.push([node[i], node, node_path + [i]])
+              i -= 1
+            end
+          when Hash
+            # Iterate to an array once so we can walk it in reverse.
+            pairs = node.to_a
+            i = pairs.size - 1
+            while i >= 0
+              k, v = pairs[i]
+              stack.push([v, node, node_path + [k]])
+              i -= 1
+            end
+          end
+          # Basic (non-container) types have no descendants — nothing to push.
         end
-        # basic types are ignored, they will be added by one of the above
-
-        results.flatten(1).compact
+        results
       end
     end
   end

data/lib/janeway/interpreters/filter_selector_interpreter.rb

@@ -43,27 +43,9 @@ module Janeway
       # @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
+        input.each { |key, value| node_list << [key, value] if filter_match?(value, root) }
+        forward_matches(node_list, input, root, path)
       end
 
       # Interpret selector on the input.
@@ -71,29 +53,39 @@ module Janeway
       # @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 = []
-        input.each_with_index do |value, i|
-          # Run filter and interpret result
-          result = @expr.interpret(value, nil, root, [])
-          case result
-          when TrueClass then node_list << [i, value] # comparison test - pass
-          when FalseClass then nil # comparison test - fail
-          when Array then node_list << [i, value] unless result.empty? # existence test - node list
-          else
-            node_list << [i, value] # existence test. Null values here == success.
-          end
+        input.each_with_index { |value, i| node_list << [i, value] if filter_match?(value, root) }
+        forward_matches(node_list, input, root, path)
+      end
+
+      private
+
+      # Classify the result of running the filter expression against a value.
+      # Returns true if the value should be kept.
+      def filter_match?(value, root)
+        result = @expr.interpret(value, nil, root, [])
+        case result
+        when TrueClass then true    # comparison test - pass
+        when FalseClass then false  # comparison test - fail
+        when Array then !result.empty? # existence test - non-empty node list
+        else true                   # existence test - null / other values count as success
         end
+      end
+
+      # Given a node_list of [key_or_index, value] pairs, apply @next to each
+      # and concat the results. If no @next, return just the values.
+      def forward_matches(node_list, input, root, path)
         return node_list.map(&:last) unless @next
 
-        # Apply child selector to each node in the output node list
         results = []
-        node_list.each do |i, value|
-          results.concat @next.interpret(value, input, root, path + [i])
+        node_list.each do |key, value|
+          results.concat @next.interpret(value, input, root, path + [key])
         end
         results
       end
 
+      public
+
       # @return [Hash]
       def as_json
         { type: type, value: node.to_s, next: @next&.as_json }.compact