philiprehberger-json_path 0.1.6 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78a07561ecdca899e8715c239ebaaa0e7ed9892a557445bcceb03b3cbb7f61a6
-  data.tar.gz: 3e418c526ccb1fff468d02485c7b76a071de30b84059c1205b9478e0d683c235
+  metadata.gz: a5f622166e4beba5e485f24b63a4286e28b6745c120a1271cd3e663cfe87150f
+  data.tar.gz: 71dd674e321a36c295037a9672ab8c92f0eb87e6709a9ec7bbc98299abc14343
 SHA512:
-  metadata.gz: 40bd26003e395e6ca24f52cf469df2004096cecb5113365b65f5fab8153614bd8c0fa62acd49f11bfbc9da9971b56b6ba8aa839536796336a24ba0a47ea90b4d
-  data.tar.gz: 1694b53c1f359b143eeb54a336c3e1612044408a7ebd9fb4d4b036ca6829777ace260a44c23f86d1b5ebfbade802a8be4508a5116aee0bc863dc805457945e92
+  metadata.gz: ff4e5a102c7c9ab0d59add298fbd4b9b2d4f9feb2d88274cdebdbb7358cdcb97aeccd99c62e6d5e38990902a1840224e4c042cb3e03c5751cb21a27f14a95410
+  data.tar.gz: 1bb735639d90eb6827d01b6b5a37ad5b9c63d9dcece71dfd45ef124bae7cca27de0dab19335184e0351e3f86c1905603f2f39aa8b48325183542dfa60adac16e

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-17
+
+### Added
+- `JsonPath.paths(data, expression)` returns the canonical JSONPath strings of every match (complement to `.values`)
+
+## [0.2.0] - 2026-04-03
+
+### Added
+- Recursive descent operator `..` for matching keys at any nesting depth
+- `JsonPath.count(data, path)` method to return number of matches
+- `JsonPath.values(data, path)` method as an alias for `query`
+- Negation filter `!` support: `$[?(!@.key)]` matches items without a key
+- Filter comparison with `@.key.length` for arrays and strings
+
+## [0.1.7] - 2026-03-31
+
+### Added
+- Add GitHub issue templates, dependabot config, and PR template
+
 ## [0.1.6] - 2026-03-31
 
 ### Changed

data/README.md

@@ -4,7 +4,7 @@
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-json_path.svg)](https://rubygems.org/gems/philiprehberger-json_path)
 [![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-json-path)](https://github.com/philiprehberger/rb-json-path/commits/main)
 
-JSONPath expression evaluator with dot notation, wildcards, slices, and filters
+JSONPath expression evaluator with dot notation, wildcards, slices, filters, and recursive descent
 
 ## Requirements
 
@@ -42,13 +42,44 @@ data = {
 Philiprehberger::JsonPath.query(data, '$.store.books[*].title')
 # => ["Ruby", "Python", "Go"]
 
+Philiprehberger::JsonPath.values(data, '$.store.books[*].title')
+# => ["Ruby", "Python", "Go"]  (alias for query)
+
 Philiprehberger::JsonPath.first(data, '$.store.books[0].title')
 # => "Ruby"
 
+Philiprehberger::JsonPath.count(data, '$.store.books[*]')
+# => 3
+
 Philiprehberger::JsonPath.exists?(data, '$.store.books')
 # => true
 ```
 
+### Matched paths
+
+Use `paths` to get canonical JSONPath strings for every match, rather than the values themselves. Each returned path re-evaluates back to the single element it identifies, making it handy for diffing, patching, or reporting.
+
+```ruby
+Philiprehberger::JsonPath.paths(data, '$.store.books[*].title')
+# => ["$.store.books[0].title", "$.store.books[1].title", "$.store.books[2].title"]
+
+Philiprehberger::JsonPath.paths(data, '$.store.books[?(@.price>22)]')
+# => ["$.store.books[0]", "$.store.books[1]"]
+
+Philiprehberger::JsonPath.paths(data, '$.missing')
+# => []
+```
+
+### Recursive Descent
+
+```ruby
+Philiprehberger::JsonPath.query(data, '$..price')
+# => [30, 25, 20]
+
+Philiprehberger::JsonPath.query(data, '$..title')
+# => ["Ruby", "Python", "Go"]
+```
+
 ### Array Indexing and Slicing
 
 ```ruby
@@ -72,6 +103,29 @@ Philiprehberger::JsonPath.query(data, "$.store.books[?(@.title=='Go')].price")
 # => [20]
 ```
 
+### Negation Filters
+
+```ruby
+data = { 'items' => [{ 'name' => 'a', 'hidden' => true }, { 'name' => 'b' }] }
+
+Philiprehberger::JsonPath.query(data, '$.items[?(!@.hidden)].name')
+# => ["b"]
+```
+
+### Length Comparisons
+
+```ruby
+data = {
+  'groups' => [
+    { 'name' => 'team1', 'members' => ['Alice', 'Bob'] },
+    { 'name' => 'team2', 'members' => [] }
+  ]
+}
+
+Philiprehberger::JsonPath.query(data, '$.groups[?(@.members.length > 0)].name')
+# => ["team1"]
+```
+
 ### Supported Syntax
 
 | Syntax | Description |
@@ -82,16 +136,22 @@ Philiprehberger::JsonPath.query(data, "$.store.books[?(@.title=='Go')].price")
 | `[n]` | Array index (supports negative) |
 | `[*]` | Wildcard (all elements) |
 | `[start:end]` | Array slice |
+| `..key` | Recursive descent (match key at any depth) |
 | `[?(@.key>val)]` | Filter expression |
 | `[?(@.key)]` | Existence filter |
+| `[?(!@.key)]` | Negation filter |
+| `[?(@.key.length>n)]` | Length comparison filter |
 
 ## API
 
 | Method | Description |
 |--------|-------------|
 | `JsonPath.query(data, path)` | Return all matches as an array |
+| `JsonPath.values(data, path)` | Alias for `query` |
 | `JsonPath.first(data, path)` | Return the first match or nil |
+| `JsonPath.count(data, path)` | Return the number of matches |
 | `JsonPath.exists?(data, path)` | Check if any match exists |
+| `JsonPath.paths(data, path)` | Return canonical JSONPath strings for each match |
 
 ## Development
 

data/lib/philiprehberger/json_path/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module JsonPath
-    VERSION = '0.1.6'
+    VERSION = '0.3.0'
   end
 end

data/lib/philiprehberger/json_path.rb

@@ -16,6 +16,15 @@ module Philiprehberger
       evaluate(data, tokens)
     end
 
+    # Alias for query (more discoverable name)
+    #
+    # @param data [Hash, Array] the data structure to query
+    # @param path [String] JSONPath expression
+    # @return [Array] all matching values
+    def self.values(data, path)
+      query(data, path)
+    end
+
     # Query data and return the first match
     #
     # @param data [Hash, Array] the data structure to query
@@ -25,6 +34,15 @@ module Philiprehberger
       query(data, path).first
     end
 
+    # Return the number of matches for a JSONPath expression
+    #
+    # @param data [Hash, Array] the data structure to query
+    # @param path [String] JSONPath expression
+    # @return [Integer] number of matches
+    def self.count(data, path)
+      query(data, path).size
+    end
+
     # Check if a JSONPath expression matches anything
     #
     # @param data [Hash, Array] the data structure to query
@@ -34,9 +52,39 @@ module Philiprehberger
       !query(data, path).empty?
     end
 
+    # Return the canonical JSONPath strings for every match of an expression
+    #
+    # Each returned path is an unambiguous JSONPath that, when re-evaluated,
+    # resolves to the single element it identifies. Paths are returned in
+    # document order. Returns an empty array when no matches exist.
+    #
+    # @param data [Hash, Array] the data structure to query
+    # @param path [String] JSONPath expression
+    # @return [Array<String>] canonical JSONPath strings for each match
+    def self.paths(data, path)
+      tokens = tokenize(path)
+      evaluate_with_paths(data, tokens).map { |_node, p| p }
+    end
+
     class << self
       private
 
+      TOKEN_PATTERNS = [
+        [/\A\.\.(\w+)/, :recursive_pat],
+        [/\A\.(\w+)/, :key_pat],
+        [/\A\[(\d+)\]/, :index_pat],
+        [/\A\[\*\]/, :wildcard_pat],
+        [/\A\[(-?\d+):(-?\d+)\]/, :slice_both_pat],
+        [/\A\[:(-?\d+)\]/, :slice_end_pat],
+        [/\A\[(-?\d+):\]/, :slice_start_pat],
+        [/\A\[\?\(!@\.(\w+)\)\]/, :filter_not_exists_pat],
+        [/\A\[\?\(@\.([\w.]+)\.length\s*(==|!=|>|>=|<|<=)\s*([^\]]+)\)\]/, :filter_length_pat],
+        [/\A\[\?\(@\.(\w+)\s*(==|!=|>|>=|<|<=)\s*([^\]]+)\)\]/, :filter_pat],
+        [/\A\[\?\(@\.(\w+)\)\]/, :filter_exists_pat],
+        [/\A\['([^']+)'\]/, :bracket_single_pat],
+        [/\A\["([^"]+)"\]/, :bracket_double_pat]
+      ].freeze
+
       def tokenize(path)
         raise Error, 'Path must start with $' unless path.to_s.start_with?('$')
 
@@ -44,50 +92,44 @@ module Philiprehberger
         tokens = []
 
         until remaining.empty?
-          case remaining
-          when /\A\.(\w+)/
-            tokens << { type: :key, value: Regexp.last_match(1) }
-            remaining = remaining[Regexp.last_match(0).length..]
-          when /\A\[(\d+)\]/
-            tokens << { type: :index, value: Regexp.last_match(1).to_i }
-            remaining = remaining[Regexp.last_match(0).length..]
-          when /\A\[\*\]/
-            tokens << { type: :wildcard }
-            remaining = remaining[3..]
-          when /\A\[(-?\d+):(-?\d+)\]/
-            tokens << { type: :slice, start: Regexp.last_match(1).to_i, end: Regexp.last_match(2).to_i }
-            remaining = remaining[Regexp.last_match(0).length..]
-          when /\A\[:(-?\d+)\]/
-            tokens << { type: :slice, start: 0, end: Regexp.last_match(1).to_i }
-            remaining = remaining[Regexp.last_match(0).length..]
-          when /\A\[(-?\d+):\]/
-            tokens << { type: :slice, start: Regexp.last_match(1).to_i, end: nil }
-            remaining = remaining[Regexp.last_match(0).length..]
-          when /\A\[\?\(@\.(\w+)\s*(==|!=|>|>=|<|<=)\s*([^\]]+)\)\]/
-            tokens << {
-              type: :filter,
-              key: Regexp.last_match(1),
-              op: Regexp.last_match(2),
-              value: parse_filter_value(Regexp.last_match(3).strip)
-            }
-            remaining = remaining[Regexp.last_match(0).length..]
-          when /\A\[\?\(@\.(\w+)\)\]/
-            tokens << { type: :filter_exists, key: Regexp.last_match(1) }
-            remaining = remaining[Regexp.last_match(0).length..]
-          when /\A\['([^']+)'\]/
-            tokens << { type: :key, value: Regexp.last_match(1) }
-            remaining = remaining[Regexp.last_match(0).length..]
-          when /\A\["([^"]+)"\]/
-            tokens << { type: :key, value: Regexp.last_match(1) }
-            remaining = remaining[Regexp.last_match(0).length..]
-          else
-            raise Error, "Unexpected token at: #{remaining}"
-          end
+          token, consumed = match_token(remaining)
+          raise Error, "Unexpected token at: #{remaining}" unless token
+
+          tokens << token
+          remaining = remaining[consumed..]
         end
 
         tokens
       end
 
+      def match_token(remaining)
+        TOKEN_PATTERNS.each do |pattern, kind|
+          m = pattern.match(remaining)
+          next unless m
+
+          return build_token(kind, m), m[0].length
+        end
+        nil
+      end
+
+      def build_token(kind, m)
+        case kind
+        when :recursive_pat then { type: :recursive, value: m[1] }
+        when :key_pat then { type: :key, value: m[1] }
+        when :index_pat then { type: :index, value: m[1].to_i }
+        when :wildcard_pat then { type: :wildcard }
+        when :slice_both_pat then { type: :slice, start: m[1].to_i, end: m[2].to_i }
+        when :slice_end_pat then { type: :slice, start: 0, end: m[1].to_i }
+        when :slice_start_pat then { type: :slice, start: m[1].to_i, end: nil }
+        when :filter_not_exists_pat then { type: :filter_not_exists, key: m[1] }
+        when :filter_length_pat then { type: :filter_length, key_path: m[1], op: m[2], value: parse_filter_value(m[3].strip) }
+        when :filter_pat then { type: :filter, key: m[1], op: m[2], value: parse_filter_value(m[3].strip) }
+        when :filter_exists_pat then { type: :filter_exists, key: m[1] }
+        when :bracket_single_pat then { type: :key, value: m[1] }
+        when :bracket_double_pat then { type: :key, value: m[1] }
+        end
+      end
+
       def parse_filter_value(str)
         case str
         when /\A'(.*)'\z/ then Regexp.last_match(1)
@@ -125,6 +167,12 @@ module Philiprehberger
           apply_filter(node, token[:key], token[:op], token[:value])
         when :filter_exists
           apply_filter_exists(node, token[:key])
+        when :filter_not_exists
+          apply_filter_not_exists(node, token[:key])
+        when :filter_length
+          apply_filter_length(node, token[:key_path], token[:op], token[:value])
+        when :recursive
+          apply_recursive(node, token[:value])
         else
           []
         end
@@ -191,6 +239,219 @@ module Philiprehberger
         end
       end
 
+      def apply_filter_not_exists(node, key)
+        return [] unless node.is_a?(Array)
+
+        node.reject do |item|
+          next false unless item.is_a?(Hash)
+
+          item.key?(key) || item.key?(key.to_sym)
+        end
+      end
+
+      def apply_filter_length(node, key_path, op, value)
+        return [] unless node.is_a?(Array)
+
+        node.select do |item|
+          next false unless item.is_a?(Hash)
+
+          resolved = resolve_key_path(item, key_path)
+          next false if resolved.nil?
+
+          length = resolved.respond_to?(:length) ? resolved.length : nil
+          next false if length.nil?
+
+          compare(length, op, value)
+        end
+      end
+
+      def resolve_key_path(node, key_path)
+        keys = key_path.split('.')
+        current = node
+        keys.each do |key|
+          return nil unless current.is_a?(Hash)
+
+          current = current[key] || current[key.to_sym]
+          return nil if current.nil?
+        end
+        current
+      end
+
+      def apply_recursive(node, key)
+        results = []
+        collect_recursive(node, key, results)
+        results
+      end
+
+      def collect_recursive(node, key, results)
+        case node
+        when Hash
+          node.each do |k, v|
+            results << v if k.to_s == key
+            collect_recursive(v, key, results)
+          end
+        when Array
+          node.each { |item| collect_recursive(item, key, results) }
+        end
+      end
+
+      SAFE_KEY = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+
+      def evaluate_with_paths(data, tokens)
+        results = [[data, '$']]
+
+        tokens.each do |token|
+          results = results.flat_map { |node, path| apply_token_with_paths(node, path, token) }
+        end
+
+        results
+      end
+
+      def apply_token_with_paths(node, path, token)
+        case token[:type]
+        when :key
+          apply_key_with_paths(node, path, token[:value])
+        when :index
+          apply_index_with_paths(node, path, token[:value])
+        when :wildcard
+          apply_wildcard_with_paths(node, path)
+        when :slice
+          apply_slice_with_paths(node, path, token[:start], token[:end])
+        when :filter
+          apply_filter_with_paths(node, path, token[:key], token[:op], token[:value])
+        when :filter_exists
+          apply_filter_exists_with_paths(node, path, token[:key])
+        when :filter_not_exists
+          apply_filter_not_exists_with_paths(node, path, token[:key])
+        when :filter_length
+          apply_filter_length_with_paths(node, path, token[:key_path], token[:op], token[:value])
+        when :recursive
+          apply_recursive_with_paths(node, path, token[:value])
+        else
+          []
+        end
+      end
+
+      def key_segment(key)
+        str = key.to_s
+        SAFE_KEY.match?(str) ? ".#{str}" : "['#{str.gsub("'", "\\\\'")}']"
+      end
+
+      def apply_key_with_paths(node, path, key)
+        return [] unless node.is_a?(Hash)
+
+        sym_key = key.to_sym
+        if node.key?(key)
+          [[node[key], path + key_segment(key)]]
+        elsif node.key?(sym_key)
+          [[node[sym_key], path + key_segment(key)]]
+        else
+          []
+        end
+      end
+
+      def apply_index_with_paths(node, path, index)
+        return [] unless node.is_a?(Array)
+        return [] if index >= node.length || index < -node.length
+
+        normalized = index.negative? ? node.length + index : index
+        [[node[index], "#{path}[#{normalized}]"]]
+      end
+
+      def apply_wildcard_with_paths(node, path)
+        case node
+        when Array
+          node.each_with_index.map { |v, i| [v, "#{path}[#{i}]"] }
+        when Hash
+          node.map { |k, v| [v, path + key_segment(k)] }
+        else
+          []
+        end
+      end
+
+      def apply_slice_with_paths(node, path, start_idx, end_idx)
+        return [] unless node.is_a?(Array)
+
+        end_idx = node.length if end_idx.nil?
+        range = (start_idx...end_idx)
+        indices = range.to_a.select { |i| i >= 0 && i < node.length }
+        indices.map { |i| [node[i], "#{path}[#{i}]"] }
+      end
+
+      def apply_filter_with_paths(node, path, key, op, value)
+        return [] unless node.is_a?(Array)
+
+        matches = node.each_with_index.select do |item, _i|
+          next false unless item.is_a?(Hash)
+
+          actual = item[key] || item[key.to_sym]
+          next false if actual.nil? && !item.key?(key) && !item.key?(key.to_sym)
+
+          compare(actual, op, value)
+        end
+        matches.map { |item, i| [item, "#{path}[#{i}]"] }
+      end
+
+      def apply_filter_exists_with_paths(node, path, key)
+        return [] unless node.is_a?(Array)
+
+        matches = node.each_with_index.select do |item, _i|
+          next false unless item.is_a?(Hash)
+
+          item.key?(key) || item.key?(key.to_sym)
+        end
+        matches.map { |item, i| [item, "#{path}[#{i}]"] }
+      end
+
+      def apply_filter_not_exists_with_paths(node, path, key)
+        return [] unless node.is_a?(Array)
+
+        matches = node.each_with_index.reject do |item, _i|
+          next false unless item.is_a?(Hash)
+
+          item.key?(key) || item.key?(key.to_sym)
+        end
+        matches.map { |item, i| [item, "#{path}[#{i}]"] }
+      end
+
+      def apply_filter_length_with_paths(node, path, key_path, op, value)
+        return [] unless node.is_a?(Array)
+
+        matches = node.each_with_index.select do |item, _i|
+          next false unless item.is_a?(Hash)
+
+          resolved = resolve_key_path(item, key_path)
+          next false if resolved.nil?
+
+          length = resolved.respond_to?(:length) ? resolved.length : nil
+          next false if length.nil?
+
+          compare(length, op, value)
+        end
+        matches.map { |item, i| [item, "#{path}[#{i}]"] }
+      end
+
+      def apply_recursive_with_paths(node, path, key)
+        results = []
+        collect_recursive_with_paths(node, path, key, results)
+        results
+      end
+
+      def collect_recursive_with_paths(node, path, key, results)
+        case node
+        when Hash
+          node.each do |k, v|
+            child_path = path + key_segment(k)
+            results << [v, child_path] if k.to_s == key
+            collect_recursive_with_paths(v, child_path, key, results)
+          end
+        when Array
+          node.each_with_index do |item, i|
+            collect_recursive_with_paths(item, "#{path}[#{i}]", key, results)
+          end
+        end
+      end
+
       def compare(actual, op, value)
         case op
         when '==' then actual == value

metadata

@@ -1,18 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-json_path
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.3.0
 platform: ruby
 authors:
 - philiprehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-18 00:00:00.000000000 Z
 dependencies: []
 description: Evaluate JSONPath expressions against Ruby hashes and arrays. Supports
-  dot notation, array indexing, wildcards, slices, and filter expressions for querying
-  nested data.
+  dot notation, array indexing, wildcards, slices, filter expressions, recursive descent,
+  and length comparisons for querying nested data.
 email:
 - philiprehberger@users.noreply.github.com
 executables: []
@@ -24,11 +24,11 @@ files:
 - README.md
 - lib/philiprehberger/json_path.rb
 - lib/philiprehberger/json_path/version.rb
-homepage: https://github.com/philiprehberger/rb-json-path
+homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-json_path
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/philiprehberger/rb-json-path
+  homepage_uri: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-json_path
   source_code_uri: https://github.com/philiprehberger/rb-json-path
   changelog_uri: https://github.com/philiprehberger/rb-json-path/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/philiprehberger/rb-json-path/issues
@@ -51,5 +51,6 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: JSONPath expression evaluator with dot notation, wildcards, slices, and filters
+summary: JSONPath expression evaluator with dot notation, wildcards, slices, filters,
+  and recursive descent
 test_files: []