janeway-jsonpath 0.5.0 → 1.0.0

data/lib/janeway/lexer.rb

@@ -5,50 +5,50 @@ require_relative 'token'
 require_relative 'error'
 
 module Janeway
-  OPERATORS = {
-    and: '&&',
-    array_slice_separator: ':',
-    child_end: ']',
-    child_start: '[',
-    current_node: '@',
-    descendants: '..',
-    dot: '.',
-    equal: '==',
-    filter: '?',
-    greater_than: '>',
-    greater_than_or_equal: '>=',
-    group_end: ')',
-    group_start: '(',
-    less_than: '<',
-    less_than_or_equal: '<=',
-    minus: '-',
-    not: '!',
-    not_equal: '!=',
-    or: '||',
-    root: '$',
-    union: ',',
-    wildcard: '*',
-  }.freeze
-  ONE_CHAR_LEX = OPERATORS.values.select { |lexeme| lexeme.size == 1 }.freeze
-  TWO_CHAR_LEX = OPERATORS.values.select { |lexeme| lexeme.size == 2 }.freeze
-  TWO_CHAR_LEX_FIRST = TWO_CHAR_LEX.map { |lexeme| lexeme[0] }.freeze
-  ONE_OR_TWO_CHAR_LEX = ONE_CHAR_LEX & TWO_CHAR_LEX.map { |str| str[0] }.freeze
-
-  WHITESPACE = " \t\n\r"
-  KEYWORD = %w[true false null].freeze
-  FUNCTIONS = %w[length count match search value].freeze
-
-  # faster to check membership in a string than an array of char (benchmarked ruby 3.1.2)
-  ALPHABET = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
-  DIGITS = '0123456789'
-
-  # chars that may be used as the first letter of member-name-shorthand
-  NAME_FIRST = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_'
-
   # Transforms source code into tokens
   class Lexer
     class Error < Janeway::Error; end
 
+    OPERATORS = {
+      and: '&&',
+      array_slice_separator: ':',
+      child_end: ']',
+      child_start: '[',
+      current_node: '@',
+      descendants: '..',
+      dot: '.',
+      equal: '==',
+      filter: '?',
+      greater_than: '>',
+      greater_than_or_equal: '>=',
+      group_end: ')',
+      group_start: '(',
+      less_than: '<',
+      less_than_or_equal: '<=',
+      minus: '-',
+      not: '!',
+      not_equal: '!=',
+      or: '||',
+      root: '$',
+      union: ',',
+      wildcard: '*',
+    }.freeze
+    ONE_CHAR_LEX = OPERATORS.values.select { |lexeme| lexeme.size == 1 }.freeze
+    TWO_CHAR_LEX = OPERATORS.values.select { |lexeme| lexeme.size == 2 }.freeze
+    TWO_CHAR_LEX_FIRST = TWO_CHAR_LEX.map { |lexeme| lexeme[0] }.freeze
+    ONE_OR_TWO_CHAR_LEX = ONE_CHAR_LEX & TWO_CHAR_LEX.map { |str| str[0] }.freeze
+
+    WHITESPACE = " \t\n\r"
+    KEYWORD = %w[true false null].freeze
+    FUNCTIONS = %w[length count match search value].freeze
+
+    # faster to check membership in a string than an array of char (benchmarked ruby 3.1.2)
+    ALPHABET = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
+    DIGITS = '0123456789'
+
+    # chars that may be used as the first letter of member-name-shorthand
+    NAME_FIRST = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_'
+
     attr_reader :source, :tokens
     attr_accessor :next_p, :lexeme_start_p
 
@@ -72,6 +72,7 @@ module Janeway
     end
 
     def start_tokenization
+      raise err('JSONPath query is empty') if @source.empty?
       if WHITESPACE.include?(@source[0]) || WHITESPACE.include?(@source[-1])
         raise err('JSONPath query may not start or end with whitespace')
       end
@@ -470,6 +471,7 @@ module Janeway
     end
 
     # Lex a member name that is found within dot notation.
+    # This name is not delimited and allows a subset of the characters that can appear in a delimited string.
     #
     # Recognize keywords and given them the correct type.
     # @see https://www.rfc-editor.org/rfc/rfc9535.html#section-2.5.1.1-3
@@ -477,6 +479,10 @@ module Janeway
     # @param ignore_keywords [Boolean]
     # @return [Token]
     def lex_member_name_shorthand(ignore_keywords: false)
+      # Abort if name is preceded by child_start.  Catches non-delimited identifiers in brackets,
+      # eg.  $["key"] is allowed, but $[key] is not
+      raise err('Identifier within brackets must be surrounded by quotes') if @tokens.last&.type == :child_start
+
       consume while name_char?(lookahead)
       identifier = source[lexeme_start_p..(next_p - 1)]
       type =

data/lib/janeway/normalized_path.rb

@@ -46,11 +46,18 @@ module Janeway
     def self.escape_char(char)
       # Character ranges defined by https://www.rfc-editor.org/rfc/rfc9535.html#section-2.7-8
       case char.ord
-      when 0x20..0x26, 0x28..0x5B, 0x5D..0xD7FF, 0xE000..0x10FFFF # normal-unescaped range
-        char # unescaped
-      when 0x62, 0x66, 0x6E, 0x72, 0x74, 0x27, 0x5C # normal-escapable range
-        # backspace, form feed, line feed, carriage return, horizontal tab, apostrophe, backslash
-        "\\#{char}" # escaped
+      # normal-unescaped range
+      when 0x20..0x26, 0x28..0x5B, 0x5D..0xD7FF, 0xE000..0x10FFFF then char # unescaped
+
+      # normal-escapable range
+      when 0x08 then '\\b' # backspace
+      when 0x0C then '\\f' # form feed
+      when 0x0A then '\\n' # line feed / newline
+      when 0x0D then '\\r' # carriage return
+      when 0x09 then '\\t' # horizontal tab
+      when 0x27 then '\\\'' # apostrophe
+      when 0x5C then '\\\\' # backslash
+
       else # normal-hexchar range
         hex_encode_char(char)
       end

data/lib/janeway/parser.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require_relative 'ast'
 require_relative 'error'
 require_relative 'functions'
 require_relative 'lexer'
+require_relative 'query'
 
 module Janeway
   # Transform a list of tokens into an Abstract Syntax Tree

data/lib/janeway/query.rb

@@ -30,10 +30,19 @@ module Janeway
       Janeway::Enumerator.new(self, input)
     end
 
+    # @return [String]
     def to_s
       @root.to_s
     end
 
+    # Return true if this query can only possibly match 0 or 1 elements in any input.
+    # Such a query must be composed exclusively of the root identifier followed by
+    # name selectors and / or index selectors.
+    # @return [Boolean]
+    def singular_query?
+      @root.singular_query?
+    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.
@@ -66,5 +75,34 @@ module Janeway
 
       result.flatten.join("\n")
     end
+
+    # Deep copy the query
+    # @return [Query]
+    def dup
+      Parser.parse(to_s)
+    end
+
+    # Delete the last element from the chain of selectors.
+    # For a singular query, this makes the query point to the match's parent instead of the match itself.
+    #
+    # Don't do this for a non-singular query, those may contain child segments and
+    # descendant segments which would lead to different results.
+    #
+    # @return [AST::Selector]
+    def pop
+      raise Janeway::Error.new('not allowed to pop from a non-singular query', to_s) unless singular_query?
+
+      # Sever the link to the last selector
+      nodes = node_list
+      if nodes.size == 1
+        # Special case: cannot pop from the query "$" even though it is a singular query
+        raise Janeway::Error.new('cannot pop from single-element query', to_s)
+      end
+
+      nodes[-2].next = nil
+
+      # Return the last selector
+      nodes.last
+    end
   end
 end

data/lib/janeway/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Janeway
-  VERSION = '0.5.0'
+  # Version for janeway-jsonpath gem
+  VERSION = '1.0.0'
 end

data/lib/janeway.rb

@@ -1,59 +1,85 @@
 # frozen_string_literal: true
 
 require 'English'
+require_relative 'janeway/enumerator'
+require_relative 'janeway/parser'
 
-# Janeway JSONPath parsing library
+# Janeway JSONPath query library
+#
+# https://github.com/gongfarmer/janeway
 module Janeway
-  # Abstract Syntax Tree
-  module AST
-    # These are the limits of what javascript's Number type can represent
-    INTEGER_MIN = -9_007_199_254_740_991
-    INTEGER_MAX = 9_007_199_254_740_991
-  end
-
-  # Pair a jsonpath query with data to make an enumerator.
-  # This can be used to apply the query to the data using Enumerator module
-  # methods such as #each and #map.
+  # Parse a jsonpath string and combine it with data to make an Enumerator.
+  #
+  # The Enumerator can be used to apply the query to the data using Enumerator
+  # module methods such as #each and #map.
+  #
+  # @example Apply query to data and search to get array of results
+  #   results = Janeway.parse('$.store.books[? length(@.title) > 20]').search
+  #
+  # @example Apply query to data and iterate over results
+  #   enum = Janeway.parse('$.store.books[? length(@.title) > 20]')
+  #   enum.each do |book|
+  #     results << book
+  #   end
+  #
+  # @see Janeway::Enumerator docs for more ways to use the Enumerator
   #
   # @param jsonpath [String] jsonpath query
   # @param data [Array, Hash] input data
   # @return [Janeway::Enumerator]
   def self.enum_for(jsonpath, data)
-    query = compile(jsonpath)
+    query = parse(jsonpath)
     Janeway::Enumerator.new(query, data)
   end
 
-  # Compile a JSONPath query into an Abstract Syntax Tree.
+  # Parse a JSONPath string into a Janeway::Query object.
+  #
+  # This object can be combined with data to create Enumerators that apply the query to the data.
+  #
+  # Use this method if you want to parse the query once and re-use it for multiple data sets.
   #
-  # This can be combined with inputs (using #enum_for) to create Enumerators.
-  # @example
-  #     query = Janeway.compile('$.store.books[? length(@.title) > 20]')
-  #     long_title_books = query.enum_for(some_data).search
-  #     query.enum_for(other_data).each do |book|
-  #       long_title_books << book
-  #     end
+  # Otherwise, use Janeway.enum_for to parse the query and pair it with data in a single step.
+  #
+  # @example Use a query to search several JSON files
+  #   results = []
+  #   query = Janeway.parse('$.store.books[? length(@.title) > 20]')
+  #   data_files.each do |path|
+  #     data = JSON.parse File.read(path)
+  #     results.concat query.enum_for(data).search
+  #   end
   #
   # @param query [String] jsonpath query
   # @return [Janeway::AST::Query]
-  def self.compile(query)
+  def self.parse(query)
     Janeway::Parser.parse(query)
   end
-end
 
-# Require ruby source files in the given dir. Do not recurse to subdirs.
-# @param dir [String] dir path relative to __dir__
-# @return [void]
-def require_libs(dir)
-  absolute_path = File.join(__dir__, dir)
-  raise "No such dir: #{dir.inspect}" unless File.directory?(absolute_path)
+  # Transform a jsonpath singular query into an array of hash keys and/or array
+  # indexes suitable for providing to Hash#dig or Array#dig.
+  #
+  # Only singular queries are allowed, meaning queries that contain only name
+  # selectors (ie. hash keys) and index selectors (array indexes.)
+  # The paths that are yielded to Enumerator#each are all suitable for this.
+  #
+  # @example convert normalized jsonpath to array of hash keys / array indices
+  #   Janeway.path_to_diggable('$["a"].b.c[0]') => ["a", "b", "c", 0]
+  #
+  # @param jsonpath [String] jsonpath query
+  # @return [Array<String, Integer>]
+  def self.path_to_diggable(jsonpath)
+    raise Janeway::Error.new('Query has nothing to dig', jsonpath) if jsonpath == '$'
+
+    # Parse query and determine whether it can be converted
+    query = parse(jsonpath)
+    unless query.singular_query?
+      raise Janeway::Error.new('Only a singular query can be converted to dig parameters', jsonpath)
+    end
 
-  Dir.children(absolute_path).sort.each do |filename|
-    next if File.directory?(File.join(absolute_path, filename))
+    # Convert query to a list of name and index selectors
+    nodes = query.node_list
+    nodes.shift # discard the root identifier
 
-    rel_path = File.join(dir, filename)
-    require_relative(rel_path[0..-4]) # omits ".rb" extension
+    # Extract values from selectors
+    nodes.map(&:value)
   end
 end
-
-require_libs('janeway/ast')
-require_libs('janeway')

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: janeway-jsonpath
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Fraser Hanson
 bindir: bin
 cert_chain: []
-date: 2025-01-30 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |+
   JSONPath is a query language for selecting and extracting values from a JSON text.
@@ -31,6 +31,7 @@ files:
 - README.md
 - bin/janeway
 - lib/janeway.rb
+- lib/janeway/ast.rb
 - lib/janeway/ast/array_slice_selector.rb
 - lib/janeway/ast/binary_operator.rb
 - lib/janeway/ast/boolean.rb
@@ -60,25 +61,33 @@ files:
 - lib/janeway/functions/search.rb
 - 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
@@ -107,7 +116,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: jsonpath parser which implements the finalized IETF standard of Goessner
   JSONPath