json_p3 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58f9239b2c34d2ad4b9bcd724f19cd2e6daab881befb2b568d44065ab3378864
-  data.tar.gz: a76e4a183e830bbfab1f925efde9e9e6e4fb36b2687c13ab0c85b609b01b5baf
+  metadata.gz: db1ec71125b99bc877ba9856434a65e3f8e1c11a48b9566443c3b1a8b6860169
+  data.tar.gz: ad176fdda64b4f741e9f86ab48d4c8e3ccd767187fc0fc0fe28a4e6967a071d2
 SHA512:
-  metadata.gz: c36a725f0856cfa9e2c8f91931a008db812dfd17b3d4ad1afad59cddf56afac0c91ad221d258950a2a755ffa988cef8ee0f5cf43f08ca0eccbf3c3be7facdf4f
-  data.tar.gz: a17d419c6dbd96c15596052eaf12b0615725590b5e448d33ffc48e44082d95011ea3f119e0c2529b871c7be16ded8d5c7c1296c3479c03bc16c8e81d2ce33034
+  metadata.gz: 3b153a665f534891e1ed1976ca6c180cd1c2427786b9f7b74fcea1953d7337135db669b3541d5eaba7fd2829dbd6c94e6c36236a4a6c6221d1bd5c0ac45f5a04
+  data.tar.gz: 52303daa1cd27c3f3ed7187949f6b9a2cf2c95483e61cd8cf7ced438f5511ad9067f39496b1fe53a85932a3de2be15ebfa2c791fdbc9002aceb0c85395c04839

data/.rubocop.yml

@@ -20,7 +20,7 @@ Metrics/ClassLength:
   Max: 500
 
 Metrics/CyclomaticComplexity:
-  Max: 15
+  Max: 20
 
 Metrics/MethodLength:
   Max: 50

data/.ruby-version

@@ -0,0 +1 @@
+3.3.6

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [0.4.0] - 2025-02-10
+
+- Added `JSONP3.find_enum`, `JSONP3::JSONPathEnvironment.find_enum` and `JSONP3::JSONPath.find_enum`. `find_enum` is like `find`, but returns an Enumerable (usually an Enumerator) of `JSONPathNode` instances instead of a `JSONPathNodeList`. `find_enum` can be more efficient for some combinations of query and data, especially for large data and recursive queries.
+- Added `JSONP3.match`, `JSONP3.match?`, `JSONP3.first` and equivalent methods for `JSONPathEnvironment` and `JSONPath`.
+
+## [0.3.2] - 2025-01-29
+
+- Fix normalized string representations of node locations as returned by `JSONPathNode.path`.
+- Fix canonical string representations of instances of `JSONPath`, as returned by `to_s`.
+- Fixed filter queries with multiple bracketed segments. Previously we were failing to tokenize queries like `$[?@[0][0]]`. See [#15](https://github.com/jg-rp/ruby-json-p3/issues/15).
+
 ## [0.3.1] - 2024-12-05
 
 - Fix JSON Patch `move` and `copy` operations when using the special JSON Pointer token `-`.

data/README.md

@@ -16,7 +16,7 @@ We follow <a href="https://datatracker.ietf.org/doc/html/rfc9535">RFC 9535</a> s
     <img alt="Gem Version" src="https://img.shields.io/gem/v/json_p3?style=flat-square">
   </a>
   <a href="https://github.com/jg-rp/ruby-json-p3">
-    <img alt="Static Badge" src="https://img.shields.io/badge/Ruby-3.1%20%7C%203.2%20%7C%203.3-CC342D?style=flat-square">
+    <img alt="Static Badge" src="https://img.shields.io/badge/Ruby-3.1%20%7C%203.2%20%7C%203.3%20%7C%203.4-CC342D?style=flat-square">
   </a>
 </p>
 
@@ -47,7 +47,7 @@ gem install json_p3
 
 ### Checksum
 
-JSON P3 is cryptographically signed. To be sure the gem you install hasn’t been tampered with, add my public key (if you haven’t already) as a trusted certificate:
+JSON P3 is cryptographically signed. To be sure the gem you install hasn't been tampered with, add my public key (if you haven't already) as a trusted certificate:
 
 ```
 gem cert --add <(curl -Ls https://raw.githubusercontent.com/jg-rp/ruby-json-p3/refs/heads/main/certs/jgrp.pem)
@@ -192,6 +192,23 @@ end
 # {"name"=>"John", "score"=>86, "admin"=>true} at $['users'][2]
 ```
 
+### find_enum
+
+`find_enum(query, value) -> Enumerable<JSONPathNode>`
+
+`find_enum` is an alternative to `find` which returns an enumerable (usually an enumerator) of `JSONPathNode` instances instead of an array. Depending on the query and the data the query is applied to, `find_enum` can be more efficient than `find`, especially for large data and queries using recursive descent segments.
+
+```ruby
+# ... continued from above
+
+JSONP3.find_enum("$.users[?@.score > 85]", data).each do |node|
+  puts "#{node.value} at #{node.path}"
+end
+
+# {"name"=>"Sue", "score"=>100} at $['users'][0]
+# {"name"=>"John", "score"=>86, "admin"=>true} at $['users'][2]
+```
+
 ### compile
 
 `compile(query) -> JSONPath`
@@ -238,14 +255,30 @@ end
 # {"name"=>"John", "score"=>86, "admin"=>true} at $['users'][2]
 ```
 
+### match / first
+
+`match(query, value) -> JSONPathNode | nil`
+
+`match` (alias `first`) returns a node for the first available match when applying _query_ to _value_, or `nil` if there were no matches.
+
+### match?
+
+`match?(query, value) -> bool`
+
+`match?` returns `true` if there was at least one match from applying _query_ to _value_, or `false` otherwise.
+
 ### JSONPathEnvironment
 
-The `find` and `compile` methods described above are convenience methods equivalent to
+The `find`, `find_enum` and `compile` methods described above are convenience methods equivalent to:
 
 ```
 JSONP3::DEFAULT_ENVIRONMENT.find(query, data)
 ```
 
+```
+JSONP3::DEFAULT_ENVIRONMENT.find_enum(query, data)
+```
+
 and
 
 ```

data/lib/json_p3/environment.rb

@@ -63,6 +63,41 @@ module JSONP3
       compile(query).find(value)
     end
 
+    # Apply JSONPath expression _query_ to _value_.
+    # @param query [String] the JSONPath expression
+    # @param value [JSON-like data] the target JSON "document"
+    # @return [Enumerable<JSONPath>]
+    def find_enum(query, value)
+      compile(query).find_enum(value)
+    end
+
+    # Apply JSONPath expression _query_ to _value_ an return the first
+    # available node.
+    # @param query [String] the JSONPath expression
+    # @param value [JSON-like data] the target JSON "document"
+    # @return [JSONPathNode | nil]
+    def match(path, value)
+      find_enum(path, value).first
+    end
+
+    # Apply JSONPath expression _query_ to _value_ an return `true` if there's at
+    # least one node, or nil if there were no matches.
+    # @param query [String] the JSONPath expression
+    # @param value [JSON-like data] the target JSON "document"
+    # @return [bool]
+    def match?(path, value)
+      !find_enum(path, value).first.nil?
+    end
+
+    # Apply JSONPath expression _query_ to _value_ an return the first
+    # available node, or nil if there were no matches.
+    # @param query [String] the JSONPath expression
+    # @param value [JSON-like data] the target JSON "document"
+    # @return [JSONPathNode | nil]
+    def first(path, value)
+      find_enum(path, value).first
+    end
+
     # Override this function to configure JSONPath function extensions.
     # By default, only the standard functions described in RFC 9535 are enabled.
     def setup_function_extensions

data/lib/json_p3/filter.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require "json"
 require_relative "function"
+require_relative "serialize"
 
 module JSONP3 # rubocop:disable Style/Documentation
   # Base class for all filter expression nodes.
@@ -33,7 +33,7 @@ module JSONP3 # rubocop:disable Style/Documentation
     end
 
     def to_s
-      @expression.to_s
+      to_canonical_string(@expression, Precedence::LOWEST)
     end
 
     def ==(other)
@@ -47,6 +47,39 @@ module JSONP3 # rubocop:disable Style/Documentation
     def hash
       [@expression, @token].hash
     end
+
+    private
+
+    class Precedence
+      LOWEST = 1
+      LOGICAL_OR = 3
+      LOGICAL_AND = 4
+      PREFIX = 7
+    end
+
+    def to_canonical_string(expression, parent_precedence)
+      if expression.instance_of? LogicalAndExpression
+        left = to_canonical_string(expression.left, Precedence::LOGICAL_AND)
+        right = to_canonical_string(expression.right, Precedence::LOGICAL_AND)
+        expr = "#{left} && #{right}"
+        return parent_precedence >= Precedence::LOGICAL_AND ? "(#{expr})" : expr
+      end
+
+      if expression.instance_of? LogicalOrExpression
+        left = to_canonical_string(expression.left, Precedence::LOGICAL_OR)
+        right = to_canonical_string(expression.right, Precedence::LOGICAL_OR)
+        expr = "#{left} || #{right}"
+        return parent_precedence >= Precedence::LOGICAL_OR ? "(#{expr})" : expr
+      end
+
+      if expression.instance_of? LogicalNotExpression
+        operand = to_canonical_string(expression.expression, Precedence::PREFIX)
+        expr = "!#{operand}"
+        return parent_precedence > Precedence::PREFIX ? `(#{expr})` : expr
+      end
+
+      expression.to_s
+    end
   end
 
   # Base class for expression literals.
@@ -85,7 +118,7 @@ module JSONP3 # rubocop:disable Style/Documentation
   # A double or single quoted string literal.
   class StringLiteral < FilterExpressionLiteral
     def to_s
-      JSON.generate(@value)
+      JSONP3.canonical_string(@value)
     end
   end
 
@@ -357,7 +390,7 @@ module JSONP3 # rubocop:disable Style/Documentation
     # @param args [Array<Object>]
     # @return [Array<Object>]
     def unpack_node_lists(func, args)
-      unpacked_args = []
+      unpacked_args = [] # : Array[Object]
       args.each_with_index do |arg, i|
         unless arg.is_a?(JSONPathNodeList) && func.class::ARG_TYPES[i] != :nodes_expression
           unpacked_args << arg

data/lib/json_p3/function_extensions/match.rb

@@ -44,7 +44,7 @@ module JSONP3
     private
 
     def full_match(pattern)
-      parts = []
+      parts = [] # : Array[String]
       explicit_caret = pattern.start_with?("^")
       explicit_dollar = pattern.end_with?("$")
 

data/lib/json_p3/lexer.rb

@@ -209,7 +209,7 @@ module JSONP3 # rubocop:disable Style/Documentation
         case c
         when "]"
           emit(:token_rbracket, "]")
-          return @filter_depth.positive? ? :lex_inside_filter : :lex_segment
+          return :lex_segment
         when ""
           error "unclosed bracketed selection"
           return nil

data/lib/json_p3/node.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "serialize"
+
 module JSONP3
   # A JSON-like value and its location.
   class JSONPathNode
@@ -19,7 +21,7 @@ module JSONP3
     # Return the normalized path to this node.
     # @return [String] the normalized path.
     def path
-      segments = @location.flatten.map { |i| i.is_a?(String) ? "['#{i}']" : "[#{i}]" }
+      segments = @location.flatten.map { |i| i.is_a?(String) ? "[#{JSONP3.canonical_string(i)}]" : "[#{i}]" }
       "$#{segments.join}"
     end
 

data/lib/json_p3/parser.rb

@@ -245,7 +245,7 @@ module JSONP3
       FilterSelector.new(@env, token, FilterExpression.new(token, expression))
     end
 
-    def parse_filter_expression(stream, precedence = Precedence::LOWEST) # rubocop:disable Metrics/CyclomaticComplexity
+    def parse_filter_expression(stream, precedence = Precedence::LOWEST)
       left = case stream.peek.type
              when :token_double_quote_string, :token_single_quote_string
                token = stream.next
@@ -477,7 +477,7 @@ module JSONP3
                                     expression.token)
     end
 
-    def validate_function_extension_signature(token, args) # rubocop:disable Metrics/CyclomaticComplexity
+    def validate_function_extension_signature(token, args)
       func = @env.function_extensions.fetch(token.value)
       count = func.class::ARG_TYPES.length
 

data/lib/json_p3/path.rb

@@ -20,11 +20,41 @@ module JSONP3
     def find(root)
       nodes = [JSONPathNode.new(root, [], root)]
       @segments.each { |segment| nodes = segment.resolve(nodes) }
-      JSONPathNodeList.new(nodes)
+      JSONPathNodeList.new(nodes) # TODO: use JSONPathNodeList internally?
     end
 
     alias apply find
 
+    # Apply this JSONPath expression to JSON-like value _root_.
+    # @param root [Array, Hash, String, Integer, nil] the root JSON-like value to apply this query to.
+    # @return [Enumerable<JSONPathNode>] the sequence of nodes found while applying this query to _root_.
+    def find_enum(root)
+      nodes = [JSONPathNode.new(root, [], root)] # : Enumerable[JSONPathNode]
+      @segments.each { |segment| nodes = segment.resolve_enum(nodes) }
+      nodes
+    end
+
+    # Return the first node from applying this JSONPath expression to JSON-like value _root_.
+    # @param root [Array, Hash, String, Integer, nil] the root JSON-like value to apply this query to.
+    # @return [JSONPathNode | nil] the first available node or nil if there were no matches.
+    def match(root)
+      find_enum(root).first
+    end
+
+    # Return `true` if this query results in at least one node, or `false` otherwise.
+    # @param root [Array, Hash, String, Integer, nil] the root JSON-like value to apply this query to.
+    # @return [bool] `true` if this query results in at least one node, or `false` otherwise.
+    def match?(root)
+      !find_enum(root).first.nil?
+    end
+
+    # Return the first node from applying this JSONPath expression to JSON-like value _root_.
+    # @param root [Array, Hash, String, Integer, nil] the root JSON-like value to apply this query to.
+    # @return [JSONPathNode | nil] the first available node or nil if there were no matches.
+    def first(root)
+      find_enum(root).first
+    end
+
     # Return _true_ if this JSONPath expression is a singular query.
     def singular?
       @segments.each do |segment|

data/lib/json_p3/segment.rb

@@ -13,9 +13,16 @@ module JSONP3
     end
 
     # Select the children of each node in _nodes_.
+    # @return [Array<JSONPathNode>]
     def resolve(_nodes)
       raise "segments must implement resolve(nodes)"
     end
+
+    # Select the children of each node in _nodes_.
+    # @return [Enumerable<JSONPathNode>]
+    def resolve_enum(_nodes)
+      raise "segments must implement resolve_enum(nodes)"
+    end
   end
 
   # The child selection segment.
@@ -30,6 +37,18 @@ module JSONP3
       rv
     end
 
+    def resolve_enum(nodes)
+      Enumerator.new do |yielder|
+        nodes.each do |node|
+          @selectors.each do |selector|
+            selector.resolve(node).each do |item|
+              yielder << item
+            end
+          end
+        end
+      end
+    end
+
     def to_s
       "[#{@selectors.map(&:to_s).join(", ")}]"
     end
@@ -61,6 +80,20 @@ module JSONP3
       rv
     end
 
+    def resolve_enum(nodes)
+      Enumerator.new do |yielder|
+        nodes.each do |node|
+          visit_enum(node).each do |descendant|
+            @selectors.each do |selector|
+              selector.resolve(descendant).each do |item|
+                yielder << item
+              end
+            end
+          end
+        end
+      end
+    end
+
     def to_s
       "..[#{@selectors.map(&:to_s).join(", ")}]"
     end
@@ -98,5 +131,28 @@ module JSONP3
 
       rv
     end
+
+    def visit_enum(node, depth = 1)
+      raise JSONPathRecursionError.new("recursion limit exceeded", @token) if depth > @env.class::MAX_RECURSION_DEPTH
+
+      Enumerator.new do |yielder|
+        yielder << node
+        if node.value.is_a? Array
+          node.value.each_with_index do |value, i|
+            child = JSONPathNode.new(value, [node.location, i], node.root)
+            visit_enum(child, depth + 1).each do |item|
+              yielder << item
+            end
+          end
+        elsif node.value.is_a? Hash
+          node.value.each do |key, value|
+            child = JSONPathNode.new(value, [node.location, key], node.root)
+            visit_enum(child, depth + 1).each do |item|
+              yielder << item
+            end
+          end
+        end
+      end
+    end
   end
 end

data/lib/json_p3/selector.rb

@@ -17,6 +17,12 @@ module JSONP3
       raise "selectors must implement resolve(node)"
     end
 
+    # Apply this selector to _node_.
+    # @return [Enumerable<JSONPathNode>]
+    def resolve_enum(node)
+      resolve(node)
+    end
+
     # Return true if this selector is a singular selector.
     def singular?
       false
@@ -46,7 +52,7 @@ module JSONP3
     end
 
     def to_s
-      @name.inspect
+      JSONP3.canonical_string(@name)
     end
 
     def ==(other)
@@ -145,6 +151,24 @@ module JSONP3
       end
     end
 
+    def resolve_enum(node)
+      if node.value.is_a? Hash
+        Enumerator.new do |yielder|
+          node.value.each do |k, v|
+            yielder << node.new_child(v, k)
+          end
+        end
+      elsif node.value.is_a? Array
+        Enumerator.new do |yielder|
+          node.value.each.with_index do |e, i|
+            yielder << node.new_child(e, i)
+          end
+        end
+      else
+        []
+      end
+    end
+
     def to_s
       "*"
     end
@@ -178,24 +202,23 @@ module JSONP3
       length = node.value.length
       return [] if length.zero? || @step.zero?
 
-      norm_start = normalized_start(length)
-      norm_stop = normalized_stop(length)
+      normalized_start = if @start.nil?
+                           @step.negative? ? length - 1 : 0
+                         elsif @start&.negative?
+                           [length + (@start || raise), 0].max
+                         else
+                           [@start || raise, length - 1].min
+                         end
 
-      nodes = []
+      normalized_stop = if @stop.nil?
+                          @step.negative? ? -1 : length
+                        elsif @stop&.negative?
+                          [length + (@stop || raise), -1].max
+                        else
+                          [@stop || raise, length].min
+                        end
 
-      if @step.positive?
-
-        for i in (norm_start...norm_stop).step(@step) # rubocop:disable Style/For
-          nodes << node.new_child(node.value[i], i)
-        end
-      else
-        i = norm_start
-        while i > norm_stop
-          nodes << node.new_child(node.value[i], i)
-          i += @step
-        end
-      end
-      nodes
+      (normalized_start...normalized_stop).step(@step).map { |i| node.new_child(node.value[i], i) }
     end
 
     def to_s
@@ -218,24 +241,6 @@ module JSONP3
     def hash
       [@start, @stop, @step, @token].hash
     end
-
-    private
-
-    def normalized_start(length)
-      # NOTE: trying to please the type checker :(
-      return @step.negative? ? length - 1 : 0 if @start.nil?
-      return [length + (@start || raise), 0].max if @start&.negative?
-
-      [@start || raise, length - 1].min
-    end
-
-    def normalized_stop(length)
-      # NOTE: trying to please the type checker :(
-      return @step.negative? ? -1 : length if @stop.nil?
-      return [length + (@stop || raise), -1].max if @stop&.negative?
-
-      [@stop || raise, length].min
-    end
   end
 
   # Select array elements or hash values according to a filter expression.
@@ -266,6 +271,22 @@ module JSONP3
       nodes
     end
 
+    def resolve_enum(node)
+      Enumerator.new do |yielder|
+        if node.value.is_a?(Array)
+          node.value.each_with_index do |e, i|
+            context = FilterContext.new(@env, e, node.root)
+            yielder << node.new_child(e, i) if @expression.evaluate(context)
+          end
+        elsif node.value.is_a?(Hash)
+          node.value.each_pair do |k, v|
+            context = FilterContext.new(@env, v, node.root)
+            yielder << node.new_child(v, k) if @expression.evaluate(context)
+          end
+        end
+      end
+    end
+
     def to_s
       "?#{@expression}"
     end

data/lib/json_p3/serialize.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "json"
+
+module JSONP3 # rubocop:disable Style/Documentation
+  TRANS = { "\\\"" => "\"", "'" => "\\'" }.freeze
+
+  # Return _value_ formatted as a canonical string literal.
+  # @param value [String]
+  def self.canonical_string(value)
+    "'#{(JSON.dump(value)[1..-2] || raise).gsub(/('|\\")/, TRANS)}'"
+  end
+end

data/lib/json_p3/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JSONP3
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/lib/json_p3.rb

@@ -13,10 +13,26 @@ module JSONP3
     DefaultEnvironment.find(path, data)
   end
 
+  def self.find_enum(path, data)
+    DefaultEnvironment.find_enum(path, data)
+  end
+
   def self.compile(path)
     DefaultEnvironment.compile(path)
   end
 
+  def self.match(path, data)
+    DefaultEnvironment.match(path, data)
+  end
+
+  def self.match?(path, data)
+    DefaultEnvironment.match?(path, data)
+  end
+
+  def self.first(path, data)
+    DefaultEnvironment.first(path, data)
+  end
+
   def self.resolve(pointer, value, default: JSONPointer::UNDEFINED)
     JSONPointer.new(pointer).resolve(value, default: default)
   end

data/performance/benchmark_ips.rb

@@ -26,4 +26,8 @@ Benchmark.ips do |x|
   x.report("just find:") do
     COMPILED_QUERIES.map { |p, d| p.find(d) }
   end
+
+  x.report("just find (enum):") do
+    COMPILED_QUERIES.map { |p, d| p.find_enum(d).to_a }
+  end
 end

data/performance/benchmark_small_citylots.rb

@@ -15,4 +15,12 @@ Benchmark.bm(15) do |x|
   x.report("shallow:") do
     JSONP3.find("$.features..properties", DATA)
   end
+
+  x.report("enum deep:") do
+    JSONP3.find_enum("$.features..properties.BLOCK_NUM", DATA).to_a
+  end
+
+  x.report("enum shallow:") do
+    JSONP3.find_enum("$.features..properties", DATA).to_a
+  end
 end

data/sig/json_p3.rbs

@@ -3,9 +3,17 @@ module JSONP3
   DefaultEnvironment: JSONPathEnvironment
 
   def self.find: (String path, untyped data) -> JSONPathNodeList
+               
+  def self.find_enum: (String path, untyped data) -> Enumerable[JSONPathNode]
 
   def self.compile: (String path) -> JSONPath
                   
+  def self.match: (String path, untyped data) -> (JSONPathNode | nil)
+                
+  def self.first: (String path, untyped data) -> (JSONPathNode | nil)
+                
+  def self.match?: (String path, untyped data) -> bool
+                  
   def self.resolve: (String pointer, untyped value, ?default: untyped) -> untyped
 
   def self.apply: (Array[Op | Hash[String, untyped]] ops, untyped value) -> untyped
@@ -65,6 +73,14 @@ module JSONP3
     # @param value [JSON-like data]
     # @return [Array<JSONPath>]
     def find: (String query, untyped value) -> JSONPathNodeList
+            
+    def find_enum: (String query, untyped value) -> Enumerable[JSONPathNode]
+                 
+    def match: (String query, untyped value) -> (JSONPathNode | nil)
+             
+    def match?: (String query, untyped value) -> bool
+              
+    def first: (String query, untyped value) -> (JSONPathNode | nil)
 
     def setup_function_extensions: () -> void
   end
@@ -126,7 +142,7 @@ module JSONP3
 
     def initialize: (Token token) -> void
 
-    # Evaluate the filter expressin in the given context.
+    # Evaluate the filter expression in the given context.
     def evaluate: (FilterContext _context) -> untyped
   end
 
@@ -147,6 +163,20 @@ module JSONP3
     alias eql? ==
 
     def hash: () -> Integer
+            
+    private
+
+    class Precedence
+      LOWEST: 1
+  
+      LOGICAL_OR: 3
+  
+      LOGICAL_AND: 4
+  
+      PREFIX: 7
+    end
+
+    def to_canonical_string: (Expression expression, Integer parent_precedence) -> String
   end
 
   # Base class for expression literals.
@@ -394,7 +424,7 @@ module JSONP3
   # @return [Array<Token>]
   def self.tokenize: (String query) -> Array[Token]
 
-  # JSONPath query expreession lexical scanner.
+  # JSONPath query expression lexical scanner.
   #
   # @see tokenize
   class Lexer
@@ -428,7 +458,7 @@ module JSONP3
     # Generate a new token with the given type.
     # @param token_type [Symbol] one of the constants defined on the _Token_ class.
     # @param value [String | nil] a the token's value, if it is known, otherwise the
-    #   value will be sliced from @query. This is a performance optimisation.
+    #   value will be sliced from @query. This is a performance optimization.
     def emit: (token_t token_type, ?untyped value) -> void
 
     def next: () -> String
@@ -488,7 +518,7 @@ module JSONP3
 
     # @param value [JSON-like] the value at this node.
     # @param location [Array<String | Integer | Array<String | Integer>>] the sequence of
-    #   names and/or indicies leading to _value_ in _root_.
+    #   names and/or indices leading to _value_ in _root_.
     # @param root [JSON-like] the root value containing _value_ at _location_.
     def initialize: (untyped value, Array[location_element] location, untyped root) -> void
 
@@ -498,7 +528,7 @@ module JSONP3
 
     # Return a new node that is a child of this node.
     # @param value the JSON-like value at the new node.
-    # @param key [Integer, String] the array index or hash key assiciated with _value_.
+    # @param key [Integer, String] the array index or hash key associated with _value_.
     def new_child: (untyped value, String | Integer key) -> JSONPathNode
 
     def to_s: () -> ::String
@@ -622,7 +652,15 @@ module JSONP3
     # Apply this JSONPath expression to JSON-like value _root_.
     # @param root [Array, Hash, String, Integer] the root JSON-like value to apply this query to.
     # @return [Array<JSONPathNode>] the sequence of nodes found while applying this query to _root_.
-    def find: (untyped root) -> untyped
+    def find: (untyped root) -> JSONPathNodeList
+
+    def find_enum: (untyped root) -> Enumerable[JSONPathNode]
+
+    def match: (untyped root) -> (JSONPathNode | nil)
+
+    def match?: (untyped root) -> bool
+
+    def first: (untyped root) -> (JSONPathNode | nil)
 
     alias apply find
 
@@ -653,11 +691,16 @@ module JSONP3
 
     # Select the children of each node in _nodes_.
     def resolve: (Array[JSONPathNode] _nodes) -> Array[JSONPathNode]
+
+    # Select the children of each node in _nodes_.
+    def resolve_enum: (Enumerable[JSONPathNode] _nodes) -> Enumerable[JSONPathNode]
   end
 
   # The child selection segment.
   class ChildSegment < Segment
     def resolve: (Array[JSONPathNode] nodes) -> Array[JSONPathNode]
+               
+    def resolve_enum: (Enumerable[JSONPathNode] nodes) -> Enumerable[JSONPathNode]
 
     def to_s: () -> ::String
 
@@ -671,6 +714,8 @@ module JSONP3
   # The recursive descent segment
   class RecursiveDescentSegment < Segment
     def resolve: (Array[JSONPathNode] nodes) -> Array[JSONPathNode]
+               
+    def resolve_enum: (Enumerable[JSONPathNode] nodes) -> Enumerable[JSONPathNode]
 
     def to_s: () -> ::String
 
@@ -681,6 +726,7 @@ module JSONP3
     def hash: () -> Integer
 
     def visit: (JSONPathNode node, ?::Integer depth) -> Array[JSONPathNode]
+    def visit_enum: (JSONPathNode node, ?::Integer depth) -> Enumerable[JSONPathNode]
   end
 end
 
@@ -699,6 +745,7 @@ module JSONP3
     # Apply this selector to _node_.
     # @return [Array<JSONPathNode>]
     def resolve: (JSONPathNode _node) -> Array[JSONPathNode]
+    def resolve_enum: (JSONPathNode _node) -> Enumerable[JSONPathNode]
 
     # Return true if this selector is a singular selector.
     def singular?: () -> false
@@ -714,6 +761,7 @@ module JSONP3
     def initialize: (JSONPathEnvironment env, Token token, String name) -> void
 
     def resolve: (JSONPathNode node) -> ::Array[JSONPathNode]
+    def resolve_enum: (JSONPathNode node) -> Enumerable[JSONPathNode]
 
     def singular?: () -> true
 
@@ -737,6 +785,7 @@ module JSONP3
     def initialize: (JSONPathEnvironment env, Token token, String name) -> void
 
     def resolve: (JSONPathNode node) -> ::Array[JSONPathNode]
+    def resolve_enum: (JSONPathNode node) -> Enumerable[JSONPathNode]
 
     def singular?: () -> true
 
@@ -758,7 +807,8 @@ module JSONP3
 
     def initialize: (JSONPathEnvironment env, Token token, Integer index) -> void
 
-    def resolve: (JSONPathNode node) -> Array[JSONPathNode]
+    def resolve: (JSONPathNode node) -> ::Array[JSONPathNode]
+    def resolve_enum: (JSONPathNode node) -> Enumerable[JSONPathNode]
 
     def singular?: () -> true
 
@@ -777,7 +827,8 @@ module JSONP3
 
   # The wildcard selector selects all elements from an array or values from a hash.
   class WildcardSelector < Selector
-    def resolve: (JSONPathNode node) -> Array[JSONPathNode]
+    def resolve: (JSONPathNode node) -> ::Array[JSONPathNode]
+    def resolve_enum: (JSONPathNode node) -> Enumerable[JSONPathNode]
 
     def to_s: () -> "*"
 
@@ -807,7 +858,8 @@ module JSONP3
 
     def initialize: (JSONPathEnvironment env, Token token, (Integer | nil) start, (Integer | nil) stop, (Integer | nil) step) -> void
 
-    def resolve: (JSONPathNode node) -> Array[JSONPathNode]
+    def resolve: (JSONPathNode node) -> ::Array[JSONPathNode]
+    def resolve_enum: (JSONPathNode node) -> Enumerable[JSONPathNode]
 
     def to_s: () -> ::String
 
@@ -816,12 +868,6 @@ module JSONP3
     alias eql? ==
 
     def hash: () -> Integer
-
-    private
-
-    def normalized_start: (Integer length) -> Integer
-                        
-    def normalized_stop: (Integer length) -> Integer
   end
 
   # Select array elements or hash values according to a filter expression.
@@ -833,7 +879,8 @@ module JSONP3
 
     def initialize: (JSONPathEnvironment env, Token token, Expression expression) -> void
 
-    def resolve: (JSONPathNode node) -> Array[JSONPathNode]
+    def resolve: (JSONPathNode node) -> ::Array[JSONPathNode]
+    def resolve_enum: (JSONPathNode node) -> Enumerable[JSONPathNode]
 
     def to_s: () -> ::String
 
@@ -926,7 +973,7 @@ module JSONP3
   # @param value [String]
   # @param quote [String] one of '"' or "'".
   # @param token [Token]
-  # @return [String] A new string without escape seqeuences.
+  # @return [String] A new string without escape sequences.
   def self.unescape_string: (String value, String quote, Token token) -> String
 
   def self.decode_hex_char: (untyped value, untyped index, Token token) -> ::Array[untyped]
@@ -938,6 +985,8 @@ module JSONP3
   def self.low_surrogate?: (untyped code_point) -> untyped
 
   def self.code_point_to_string: (untyped code_point, Token token) -> untyped
+
+  def self.canonical_string: (untyped String) -> ::String
 end
 
 module JSONP3
@@ -1162,7 +1211,7 @@ module JSONP3
   class OpRemove < Op
     @pointer: JSONPointer
 
-    # @param papointerth [JSONPointer]
+    # @param pointer [JSONPointer]
     def initialize: (JSONPointer pointer) -> void
 
     def name: () -> "remove"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: json_p3
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - James Prior
@@ -36,7 +36,7 @@ cert_chain:
   6dM18fnfBc3yA4KI7AO8UAmRkTscMYV6f/K4YZR6ZYCNWRpY7rkg+arhf05aoSQf
   vn9bO1bzwdnG
   -----END CERTIFICATE-----
-date: 2024-12-05 00:00:00.000000000 Z
+date: 2025-02-10 00:00:00.000000000 Z
 dependencies: []
 description: JSONPath following RFC 9535
 email:
@@ -46,6 +46,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
+- ".ruby-version"
 - ".yardopts"
 - CHANGELOG.md
 - LICENCE
@@ -73,6 +74,7 @@ files:
 - lib/json_p3/pointer.rb
 - lib/json_p3/segment.rb
 - lib/json_p3/selector.rb
+- lib/json_p3/serialize.rb
 - lib/json_p3/token.rb
 - lib/json_p3/unescape.rb
 - lib/json_p3/version.rb
@@ -106,7 +108,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.27
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: 'JSONPath: Query Expressions for JSON in Ruby'