janeway-jsonpath 1.0.0 → 1.2.0

data/lib/janeway/normalized_path.rb

@@ -11,6 +11,15 @@ module Janeway
     # Characters that do not need escaping, defined by hexadecimal range
     NORMAL_UNESCAPED_RANGES = [(0x20..0x26), (0x28..0x5B), (0x5D..0xD7FF), (0xE000..0x10FFFF)].freeze
 
+    # Fast-path check for `escape`: a single anchored regex covering the same
+    # ranges as NORMAL_UNESCAPED_RANGES. Avoids allocating a `chars` array and
+    # scanning four Range objects per character on the common all-normal case.
+    NORMAL_UNESCAPED_REGEX = Regexp.new(
+      '\A[' +
+      NORMAL_UNESCAPED_RANGES.map { |r| "\\u{#{r.min.to_s(16)}}-\\u{#{r.max.to_s(16)}}" }.join +
+      ']*\z'
+    ).freeze
+
     def self.normalize(value)
       case value
       when String then normalize_name(value)
@@ -33,8 +42,8 @@ module Janeway
     end
 
     def self.escape(str)
-      # Common case, all chars are normal.
-      return str if str.chars.all? { |char| NORMAL_UNESCAPED_RANGES.any? { |range| range.include?(char.ord) } }
+      # Common case, all chars are normal — one regex match, no allocations.
+      return str if NORMAL_UNESCAPED_REGEX.match?(str)
 
       # Some escaping must be done
       str.chars.map { |char| escape_char(char) }.join

data/lib/janeway/parser.rb

@@ -16,6 +16,32 @@ module Janeway
     UNARY_OPERATORS = %w[! -].freeze
     BINARY_OPERATORS = %w[== != > < >= <= ,].freeze
     LOGICAL_OPERATORS = %w[&& ||].freeze
+
+    # O(1)-lookup Hash companions to the arrays above, plus the union used by
+    # determine_infix_function. Building these inline in the hot path
+    # allocated a fresh Array per token; hoisting eliminates it.
+    UNARY_OPERATOR_SET = UNARY_OPERATORS.each_with_object({}) { |op, h| h[op] = true }.freeze
+    BINARY_OPERATOR_SET = BINARY_OPERATORS.each_with_object({}) { |op, h| h[op] = true }.freeze
+    INFIX_OPERATOR_SET =
+      (BINARY_OPERATORS + LOGICAL_OPERATORS).each_with_object({}) { |op, h| h[op] = true }.freeze
+    PARSE_METHOD_TYPES =
+      %I[identifier number string true false nil function if while root current_node]
+      .each_with_object({}) { |t, h| h[t] = true }.freeze
+    TERMINATOR_TYPES = %I[child_end union eof].each_with_object({}) { |t, h| h[t] = true }.freeze
+
+    # O(1) dispatch table for determine_parsing_function's type-driven cases.
+    # Sits next to the PARSE_METHOD_TYPES set (the other type branch) so both
+    # are visible when adding a new token type.
+    PARSE_DISPATCH_BY_TYPE = {
+      group_start: :parse_grouped_expr,
+      :"\n" => :parse_terminator,
+      eof: :parse_terminator,
+      child_start: :parse_child_segment,
+      dot: :parse_dot_notation,
+      descendants: :parse_descendant_segment,
+      filter: :parse_filter_selector,
+      null: :parse_null,
+    }.freeze
     LOWEST_PRECEDENCE = 0
     OPERATOR_PRECEDENCE = {
       ',' => 0,
@@ -65,12 +91,8 @@ module Janeway
 
     private
 
-    def pending_tokens?
-      @next_p < tokens.length
-    end
-
     def next_not_terminator?
-      next_token && next_token.type != :"\n" && next_token.type != :eof
+      next_token && next_token.type != :eof
     end
 
     # Make "next" token become "current" by moving the pointer
@@ -135,33 +157,21 @@ module Janeway
     end
 
     def determine_parsing_function
-      parse_methods = %I[identifier number string true false nil function if while root current_node]
-      if parse_methods.include?(current.type)
-        :"parse_#{current.type}"
-      elsif current.type == :group_start # (
-        :parse_grouped_expr
-      elsif %I[\n eof].include?(current.type)
-        :parse_terminator
-      elsif UNARY_OPERATORS.include?(current.lexeme)
-        :parse_unary_operator
-      elsif current.type == :child_start # [
-        :parse_child_segment
-      elsif current.type == :dot # .
-        :parse_dot_notation
-      elsif current.type == :descendants # ..
-        :parse_descendant_segment
-      elsif current.type == :filter # ?
-        :parse_filter_selector
-      elsif current.type == :null # null
-        :parse_null
-      else
-        raise err("Don't know how to parse #{current}")
-      end
+      # Two type-driven tables plus a lexeme-driven check for unary operators.
+      # PARSE_METHOD_TYPES synthesizes the method name (`:parse_<type>`);
+      # PARSE_DISPATCH_BY_TYPE maps to a fixed method name.
+      return :"parse_#{current.type}" if PARSE_METHOD_TYPES.include?(current.type)
+
+      dispatch = PARSE_DISPATCH_BY_TYPE[current.type]
+      return dispatch if dispatch
+      return :parse_unary_operator if UNARY_OPERATOR_SET.include?(current.lexeme)
+
+      raise err("Don't know how to parse #{current}")
     end
 
     # @return [nil, Symbol]
     def determine_infix_function(token = current)
-      return unless (BINARY_OPERATORS + LOGICAL_OPERATORS).include?(token.lexeme)
+      return unless INFIX_OPERATOR_SET.include?(token.lexeme)
 
       :parse_binary_operator
     end
@@ -174,7 +184,7 @@ module Janeway
     end
 
     def parse_string
-      AST::StringType.new(current.literal)
+      AST::StringType.new(current.literal).tap { |node| node.token = current }
     end
 
     def parse_number
@@ -198,14 +208,16 @@ module Janeway
       end
 
       # '-' must be followed by a number token.
-      # Parse number and apply - sign to its literal value
+      # Consume the minus, then replace the following number token in the
+      # token stream with a copy that has the negated literal. Replacing —
+      # rather than mutating in place — keeps Token immutable.
       consume
-      parse_number
       unless current.literal.is_a?(Numeric)
         raise err("Minus operator \"-\" must be followed by number, got #{current.lexeme.inspect}")
       end
 
-      current.literal *= -1
+      original = current
+      @tokens[@next_p - 1] = Token.new(original.type, original.lexeme, -original.literal, original.location)
       current
     end
 
@@ -481,11 +493,10 @@ module Janeway
     # Feed tokens to the FilterSelector until hitting a terminator
     def parse_filter_selector
       selector = AST::FilterSelector.new
-      terminator_types = %I[child_end union eof]
-      while next_token && !terminator_types.include?(next_token.type)
+      while next_token && !TERMINATOR_TYPES.include?(next_token.type)
         consume
         node =
-          if BINARY_OPERATORS.include?(current.lexeme)
+          if BINARY_OPERATOR_SET.include?(current.lexeme)
             parse_binary_operator(selector.value)
           else
             parse_expr_recursively
@@ -529,6 +540,7 @@ module Janeway
 
       consume
       op.right = parse_expr_recursively(op_precedence)
+      op.validate!
 
       op
     end

data/lib/janeway/query.rb

@@ -43,6 +43,26 @@ module Janeway
       @root.singular_query?
     end
 
+    # Return a cached interpreter tree for the given type, building it via
+    # the block on the first call. Only stateless interpreter types
+    # (`:finder`, `:deleter`) benefit from caching — `:iterator` and
+    # `:delete_if` capture the caller's block, so their trees are
+    # per-call.
+    #
+    # No-op (yields fresh every time) if the Query is frozen — respecting
+    # the docstring's "can be frozen" contract.
+    #
+    # @param type [Symbol] :finder, :deleter, :iterator, :delete_if
+    # @yield build the tree if not cached
+    # @return [Interpreters::Base]
+    def interpreter_tree_for(type)
+      return yield unless %i[finder deleter].include?(type)
+      return yield if frozen?
+
+      @interpreter_tree_cache ||= {}
+      @interpreter_tree_cache[type] ||= yield
+    end
+
     # Return a list of the nodes in the AST.
     # The AST of a jsonpath query is a straight line, so this is expressible as an array.
     # The only part of the AST with branches is inside a filter selector, but that doesn't show up here.
@@ -76,10 +96,23 @@ module Janeway
       result.flatten.join("\n")
     end
 
-    # Deep copy the query
+    # Deep copy the query.
+    #
+    # Only the top-level linked list of segments/selectors is cloned — that is
+    # the only part `pop` mutates. Nested contents (filter expressions,
+    # function parameters, child-segment members) are shared with the original,
+    # which is safe because the interpreter never mutates the AST.
+    #
+    # The tree cache is intentionally NOT shared with the dup: cached trees
+    # reference the original's top-level chain and are invalid for a dup that
+    # may later be popped.
+    #
     # @return [Query]
     def dup
-      Parser.parse(to_s)
+      cloned = node_list.map(&:dup)
+      cloned.each_cons(2) { |a, b| a.next = b }
+      cloned.last.next = nil
+      Query.new(cloned.first, @jsonpath)
     end
 
     # Delete the last element from the chain of selectors.
@@ -104,5 +137,17 @@ module Janeway
       # Return the last selector
       nodes.last
     end
+
+    # Return a data-free split of this singular query into a "parent" Query
+    # plus the leaf selector — the parent addresses one level up from what
+    # `self` addresses. Used by Enumerator#insert to locate the container
+    # that a new value should be inserted into.
+    #
+    # @return [Array(Query, AST::Selector)] [parent_query, leaf_selector]
+    def parent_query
+      parent = dup
+      leaf = parent.pop
+      [parent, leaf]
+    end
   end
 end

data/lib/janeway/token.rb

@@ -1,24 +1,59 @@
 # frozen_string_literal: true
 
 require 'forwardable'
+require_relative 'location'
 
 module Janeway
   # Tokens are produced by the lexer, they represent jsonpath query elements in a low-level, non-hierarchical way.
   class Token
     extend Forwardable
 
-    attr_reader :type, :lexeme, :location
+    attr_reader :type, :lexeme, :literal, :location
 
-    # write-access so '-' operator can modify number value
-    attr_accessor :literal
+    # For a string token, the index within the lexeme of each character of the decoded literal,
+    # so lexeme[offsets[i]] is where literal[i] came from. It differs from i when the string
+    # contains escape sequences or the lexeme starts with a quote. Nil for other token types.
+    # @return [Array<Integer>, nil]
+    attr_reader :offsets
 
     def_delegators :@location, :line, :col, :length
 
-    def initialize(type, lexeme, literal, location)
+    def initialize(type, lexeme, literal, location, offsets = nil)
       @type = type
       @lexeme = lexeme
       @literal = literal
       @location = location
+      @offsets = offsets
+    end
+
+    # Find where a character of a string token's decoded value came from in the query.
+    #
+    # Relies on two invariants: offsets[i] is the index within the lexeme of the start of literal[i],
+    # and location.col is the column of the lexeme in the query.
+    # @param index [Integer] index of a character in the decoded value
+    # @return [Integer, nil] column in the query of that character (or of the backslash that starts its
+    #   escape); nil when the token has no offsets, or no character at that index
+    def column_of(index)
+      return nil if @offsets.nil? || !index.between?(0, @offsets.length - 1)
+
+      offset = @offsets[index]
+      offset && (@location.col + offset)
+    end
+
+    # Find where a run of characters of a string token's decoded value came from in the query.
+    # @param offset [Integer, nil] index in the decoded value of the first character
+    # @param length [Integer, nil] number of decoded characters, treated as 1 if nil or not positive
+    # @return [Location] from the first character to the start of the last one; the location of the whole
+    #   token when offset is nil or the range cannot be found in the token
+    def location_of(offset, length = 1)
+      return @location unless offset
+
+      length = 1 unless length&.positive?
+      first = column_of(offset)
+      last = column_of(offset + length - 1)
+      return @location unless first && last
+
+      Location.new(first, last - first + 1)
     end
 
     def to_s
@@ -31,7 +66,7 @@ module Janeway
       when Integer, String then @literal == other
       when Symbol then @type == other
       when Token
-        @type == other.type && @lexeme == other.lexem && @literal = other.literal
+        @type == other.type && @lexeme == other.lexeme && @literal == other.literal
       else
         raise ArgumentError, "don't know how to compare Token with #{other.inspect}"
       end

data/lib/janeway/version.rb

@@ -2,5 +2,5 @@
 
 module Janeway
   # Version for janeway-jsonpath gem
-  VERSION = '1.0.0'
+  VERSION = '1.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: janeway-jsonpath
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Fraser Hanson
@@ -62,35 +62,29 @@ files:
 - lib/janeway/functions/value.rb
 - lib/janeway/interpreter.rb
 - lib/janeway/interpreters/array_slice_selector_delete_if.rb
-- lib/janeway/interpreters/array_slice_selector_deleter.rb
 - lib/janeway/interpreters/array_slice_selector_interpreter.rb
 - lib/janeway/interpreters/base.rb
 - lib/janeway/interpreters/binary_operator_interpreter.rb
 - lib/janeway/interpreters/child_segment_delete_if.rb
-- lib/janeway/interpreters/child_segment_deleter.rb
 - lib/janeway/interpreters/child_segment_interpreter.rb
 - lib/janeway/interpreters/current_node_interpreter.rb
 - lib/janeway/interpreters/descendant_segment_interpreter.rb
 - lib/janeway/interpreters/filter_selector_delete_if.rb
-- lib/janeway/interpreters/filter_selector_deleter.rb
 - lib/janeway/interpreters/filter_selector_interpreter.rb
 - lib/janeway/interpreters/function_interpreter.rb
 - lib/janeway/interpreters/index_selector_delete_if.rb
-- lib/janeway/interpreters/index_selector_deleter.rb
 - lib/janeway/interpreters/index_selector_interpreter.rb
 - lib/janeway/interpreters/iteration_helper.rb
 - lib/janeway/interpreters/name_selector_delete_if.rb
-- lib/janeway/interpreters/name_selector_deleter.rb
 - lib/janeway/interpreters/name_selector_interpreter.rb
 - lib/janeway/interpreters/root_node_delete_if.rb
-- lib/janeway/interpreters/root_node_deleter.rb
 - lib/janeway/interpreters/root_node_interpreter.rb
 - lib/janeway/interpreters/tree_constructor.rb
 - lib/janeway/interpreters/unary_operator_interpreter.rb
 - lib/janeway/interpreters/wildcard_selector_delete_if.rb
-- lib/janeway/interpreters/wildcard_selector_deleter.rb
 - lib/janeway/interpreters/wildcard_selector_interpreter.rb
 - lib/janeway/interpreters/yielder.rb
+- lib/janeway/iregexp.rb
 - lib/janeway/lexer.rb
 - lib/janeway/location.rb
 - lib/janeway/normalized_path.rb

data/lib/janeway/interpreters/array_slice_selector_deleter.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'array_slice_selector_interpreter'
-
-module Janeway
-  module Interpreters
-    # Interprets array slice selector and deletes matching values
-    class ArraySliceSelectorDeleter < ArraySliceSelectorInterpreter
-      # Delete values 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/child_segment_deleter.rb

@@ -1,19 +0,0 @@
-# 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/filter_selector_deleter.rb

@@ -1,65 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'filter_selector_interpreter'
-
-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/index_selector_deleter.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'index_selector_interpreter'
-
-module Janeway
-  module Interpreters
-    # Interprets an index selector, and deletes the matched value.
-    class IndexSelectorDeleter < IndexSelectorInterpreter
-      # Interpret selector on the given 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
-      # @param _path [Array<String>] elements of normalized path to the current input
-      def interpret(input, _parent, _root, _path)
-        return [] unless input.is_a?(Array)
-
-        index = selector.value
-        result = input.fetch(index) # raises IndexError if no such index
-        input.delete_at(index) # returns nil if deleted value is nil, or if no value was deleted
-        [result]
-      rescue IndexError
-        []
-      end
-    end
-  end
-end

data/lib/janeway/interpreters/name_selector_deleter.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'name_selector_interpreter'
-
-module Janeway
-  module Interpreters
-    # Interprets a name selector, and deletes the matched values.
-    class NameSelectorDeleter < NameSelectorInterpreter
-      # Interpret selector on the given 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
-      # @param _path [Array<String>] elements of normalized path to the current input
-      def interpret(input, _parent, _root, _path)
-        return [] unless input.is_a?(Hash) && input.key?(name)
-
-        [input.delete(name)]
-      end
-
-      # Return hash representation of this interpreter
-      # @return [Hash]
-      def as_json
-        { type: type, value: name, next: @next&.as_json }
-      end
-    end
-  end
-end

data/lib/janeway/interpreters/root_node_deleter.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'root_node_interpreter'
-
-module Janeway
-  module Interpreters
-    # Interprets the root node for deletion
-    class RootNodeDeleter < RootNodeInterpreter
-      # Delete all values from the root node.
-      #
-      # TODO: unclear, for deletion is there a difference between queries '$' and '$.*'?
-      #
-      # @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] deleted elements
-      def interpret(_input, _parent, root, _path)
-        case root
-        when Array
-          results = root.dup
-          root.clear
-          results
-        when Hash
-          results = root.values
-          root.clear
-          results
-        else
-          []
-        end
-      end
-    end
-  end
-end

data/lib/janeway/interpreters/wildcard_selector_deleter.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'wildcard_selector_interpreter'
-
-module Janeway
-  module Interpreters
-    # Interprets a wildcard selector, and deletes the results.
-    class WildcardSelectorDeleter < WildcardSelectorInterpreter
-      # Delete all elements from 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
-      # @param _path [Array<String>] elements of normalized path to the current input
-      # @return [Array] deleted elements
-      def interpret(input, _parent, _root, _path)
-        case input
-        when Array
-          results = input.dup
-          input.clear
-          results
-        when Hash
-          results = input.values
-          input.clear
-          results
-        else
-          []
-        end
-      end
-    end
-  end
-end