philiprehberger-json_path 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78a07561ecdca899e8715c239ebaaa0e7ed9892a557445bcceb03b3cbb7f61a6
-  data.tar.gz: 3e418c526ccb1fff468d02485c7b76a071de30b84059c1205b9478e0d683c235
+  metadata.gz: cd62ae147160109624e6b6d186c60479cfca265cbe8c66f40755863a532abc1e
+  data.tar.gz: 2cac68f58e4ea420d84429d660730a07de443d71d8560b025c82a5166239ccb2
 SHA512:
-  metadata.gz: 40bd26003e395e6ca24f52cf469df2004096cecb5113365b65f5fab8153614bd8c0fa62acd49f11bfbc9da9971b56b6ba8aa839536796336a24ba0a47ea90b4d
-  data.tar.gz: 1694b53c1f359b143eeb54a336c3e1612044408a7ebd9fb4d4b036ca6829777ace260a44c23f86d1b5ebfbade802a8be4508a5116aee0bc863dc805457945e92
+  metadata.gz: b8f52edcf91f65be006493f1e9c60b03cbf6fbe83e935602622d96f07f729a560d02d49532976f72e5ba6c292a4c5f063298373cba732e158e2003ef5b2ad0a0
+  data.tar.gz: 027f7f078a753000cf26c1783b045e58dbf65100c8de3ca8496196d7f48c61ddf5e14e5904dc5aa5ea1981510780742301cb985ed9e73f698bcfd8e9147c2fa0

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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,29 @@ 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
 ```
 
+### 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 +88,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,15 +121,20 @@ 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 |
 
 ## Development

data/lib/philiprehberger/json_path/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module JsonPath
-    VERSION = '0.1.6'
+    VERSION = '0.2.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
@@ -37,6 +55,22 @@ module Philiprehberger
     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 +78,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 +153,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 +225,62 @@ 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
+
       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.2.0
 platform: ruby
 authors:
 - philiprehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-04 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: []