janeway-jsonpath 0.5.0 → 0.6.0

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 = '0.6.0'
 end

data/lib/janeway.rb

@@ -1,59 +1,72 @@
 # 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.
+  #
+  # Otherwise, use Janeway.enum_for to parse the query and pair it with data in a single step.
   #
-  # 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
+  # @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)
 
-  Dir.children(absolute_path).sort.each do |filename|
-    next if File.directory?(File.join(absolute_path, filename))
-
-    rel_path = File.join(dir, filename)
-    require_relative(rel_path[0..-4]) # omits ".rb" extension
+  # Transform a jsonpath singular query into an array of values 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 NotImplementedError
   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: 0.6.0
 platform: ruby
 authors:
 - Fraser Hanson
 bindir: bin
 cert_chain: []
-date: 2025-01-30 00:00:00.000000000 Z
+date: 2025-02-05 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