json_p3 0.3.2 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afd5de1be45132d6071616dc7aa21425dc3d9beaed525315f017b343b434a42f
-  data.tar.gz: 19f0fc51ac0f8680e47808beda7f206ea9d911b33ebebaccb5803cd7bcd012c0
+  metadata.gz: c045dc201d7af17b4292488327d4bd01fbba11454df29c9ec78e344a1c6f3ea3
+  data.tar.gz: c10613058ceafbf844d39a0114be75255ae453aa0f78d0d422fac864d749f364
 SHA512:
-  metadata.gz: 9c6458e2fc86fa09988edbc032ad434cca4125f1d6a368e2f8e37e79e65b80fb404d12a3ec9dfb42ef007dbfc2977a4492814c9a8d689900921e2cfa885b6c11
-  data.tar.gz: 54580931a9a37165dcbb10f8a240c8142a8de013cbc9e76776f59a5f60b43743f98db65daae7d85968d61a6eda1983df26f9ae8d8aaf1571b3a45106236a8ed1
+  metadata.gz: c04571664ae937194618544cb6aac078d91519fa6cd750e355f20d4c7a9ed9056880a9ba91fbc856475baec508ee2e779939ef6ccfeff9d9963a32f9ccf52ad2
+  data.tar.gz: 6232640619d2d65acebd920a1a3d19b77bc194b4b639b46cea9e44abb23d852f09e5eb85c004e5dc6e1aec3dd21ad2c36dabe7a59677cedeb8b776a256d375bf

data/.rubocop.yml

@@ -1,6 +1,8 @@
 require:
   - rubocop-minitest
   - rubocop-rake
+
+plugins:
   - rubocop-performance
 
 AllCops:
@@ -20,7 +22,7 @@ Metrics/ClassLength:
   Max: 500
 
 Metrics/CyclomaticComplexity:
-  Max: 15
+  Max: 20
 
 Metrics/MethodLength:
   Max: 50

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [0.4.1] - 2025-03-18
+
+- Fixed `JSONPathSyntaxError` claiming "unbalanced parentheses" when the query has balanced brackets.
+
+## [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`.

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>
 
@@ -36,7 +36,7 @@ We follow <a href="https://datatracker.ietf.org/doc/html/rfc9535">RFC 9535</a> s
 Add `'json_p3'` to your Gemfile:
 
 ```
-gem 'json_p3', '~> 0.2.1'
+gem 'json_p3', '~> 0.4.0'
 ```
 
 Or
@@ -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

@@ -390,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

@@ -20,6 +20,12 @@ module JSONP3 # rubocop:disable Style/Documentation
                                     tokens.last)
     end
 
+    unless lexer.bracket_stack.empty?
+      ch, index = *lexer.bracket_stack.last
+      msg = "unbalanced brackets"
+      raise JSONPathSyntaxError.new(msg, Token.new(:token_error, ch, index, query, message: msg))
+    end
+
     tokens
   end
 
@@ -33,11 +39,12 @@ module JSONP3 # rubocop:disable Style/Documentation
     S_ESCAPES = Set["b", "f", "n", "r", "t", "u", "/", "\\"].freeze
 
     # @dynamic tokens
-    attr_reader :tokens
+    attr_reader :tokens, :bracket_stack
 
     def initialize(query)
       @filter_depth = 0
-      @paren_stack = []
+      @func_call_stack = []
+      @bracket_stack = []
       @tokens = []
       @start = 0
       @query = query.freeze
@@ -135,6 +142,7 @@ module JSONP3 # rubocop:disable Style/Documentation
         emit(:token_double_dot, "..")
         :lex_descendant_segment
       when "["
+        @bracket_stack << ["[", @start]
         emit(:token_lbracket, "[")
         :lex_inside_bracketed_segment
       else
@@ -157,6 +165,7 @@ module JSONP3 # rubocop:disable Style/Documentation
         emit(:token_wild, "*")
         :lex_segment
       when "["
+        @bracket_stack << ["[", @start]
         emit(:token_lbracket, "[")
         :lex_inside_bracketed_segment
       else
@@ -208,6 +217,13 @@ module JSONP3 # rubocop:disable Style/Documentation
 
         case c
         when "]"
+          if @bracket_stack.empty? || @bracket_stack.last.first != "["
+            backup
+            error "unbalanced brackets"
+            return nil
+          end
+
+          @bracket_stack.pop
           emit(:token_rbracket, "]")
           return :lex_segment
         when ""
@@ -251,17 +267,13 @@ module JSONP3 # rubocop:disable Style/Documentation
           return nil
         when "]"
           @filter_depth -= 1
-          if @paren_stack.length == 1
-            error "unbalanced parentheses"
-            return nil
-          end
           backup
           return :lex_inside_bracketed_segment
         when ","
           emit(:token_comma, ",")
           # If we have unbalanced parens, we are inside a function call and a
           # comma separates arguments. Otherwise a comma separates selectors.
-          next if @paren_stack.length.positive?
+          next if @func_call_stack.length.positive?
 
           @filter_depth -= 1
           return :lex_inside_bracketed_segment
@@ -270,17 +282,25 @@ module JSONP3 # rubocop:disable Style/Documentation
         when '"'
           return :lex_double_quoted_string_inside_filter_expression
         when "("
+          @bracket_stack << ["(", @start]
           emit(:token_lparen, "(")
           # Are we in a function call? If so, a function argument contains parens.
-          @paren_stack[-1] += 1 if @paren_stack.length.positive?
+          @func_call_stack[-1] += 1 if @func_call_stack.length.positive?
         when ")"
+          if @bracket_stack.empty? || @bracket_stack.last.first != "("
+            backup
+            error "unbalanced brackets"
+            return nil
+          end
+
+          @bracket_stack.pop
           emit(:token_rparen, ")")
           # Are we closing a function call or a parenthesized expression?
-          if @paren_stack.length.positive?
-            if @paren_stack[-1] == 1
-              @paren_stack.pop
+          if @func_call_stack.length.positive?
+            if @func_call_stack[-1] == 1
+              @func_call_stack.pop
             else
-              @paren_stack[-1] -= 1
+              @func_call_stack[-1] -= 1
             end
           end
         when "$"
@@ -359,8 +379,9 @@ module JSONP3 # rubocop:disable Style/Documentation
             end
             # Function name
             # Keep track of parentheses for this function call.
-            @paren_stack << 1
+            @func_call_stack << 1
             emit :token_function
+            @bracket_stack << ["(", @start]
             self.next
             ignore # move past LPAREN
           else

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
@@ -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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JSONP3
-  VERSION = "0.3.2"
+  VERSION = "0.4.1"
 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
@@ -150,6 +166,16 @@ module JSONP3
             
     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
 
@@ -406,6 +432,8 @@ module JSONP3
 
     @paren_stack: Array[Integer]
 
+    @bracket_stack: Array[Array[untyped]]
+
     @tokens: Array[Token]
 
     @start: Integer
@@ -425,6 +453,9 @@ module JSONP3
     # @dynamic tokens
     attr_reader tokens: Array[Token]
 
+    # @dynamic tokens
+    attr_reader bracket_stack: Array[Array[untyped]]
+
     def initialize: (String query) -> void
 
     def run: () -> void
@@ -626,7 +657,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
 
@@ -657,11 +696,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
 
@@ -675,6 +719,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
 
@@ -685,6 +731,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
 
@@ -703,6 +750,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
@@ -718,6 +766,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
 
@@ -741,6 +790,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
 
@@ -762,7 +812,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
 
@@ -781,7 +832,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: () -> "*"
 
@@ -811,7 +863,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
 
@@ -820,12 +873,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.
@@ -837,7 +884,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
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: json_p3
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.1
 platform: ruby
 authors:
 - James Prior
@@ -36,7 +36,7 @@ cert_chain:
   6dM18fnfBc3yA4KI7AO8UAmRkTscMYV6f/K4YZR6ZYCNWRpY7rkg+arhf05aoSQf
   vn9bO1bzwdnG
   -----END CERTIFICATE-----
-date: 2025-01-29 00:00:00.000000000 Z
+date: 2025-03-18 00:00:00.000000000 Z
 dependencies: []
 description: JSONPath following RFC 9535
 email: