json-mask 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf429554b940fea4a030589830ad3eb3ad509983d365f19c0c371c5ff026b530
-  data.tar.gz: 8ff525f2b92a3c4f8634c4c28b96f2dc54d2652a0b5a760f267cf3b7f9885627
+  metadata.gz: 9f93379e92b79b7ec9a8395dcc291f069f019fc3224557afef20c2d9727cea7b
+  data.tar.gz: 753a718f86cabc8e38314c41c865de587299bf83b7d9eaae6d1d0710607d25a4
 SHA512:
-  metadata.gz: fb6a7be61059829fb6219b874fcfa41369070aecbd4792889e70a63a6d3c9aeb0b45b727a2cd80c6a2ee4297d695790d72b8c61fc668a1b2c73db64388805537
-  data.tar.gz: 52f4c5e63190f7fe5cc238eb13b65b86e93696470d5a0b34704b14e7c46f814b76cf37fb5eea90c02d2d5befa600beaa209f7405f44d4c1289f2f04be8f39d41
+  metadata.gz: 9506600ebe233ba5b26cb97d2e76c887e6110429bcad82330a8ad531cfdf4dd0011d33fc159bf4ce23867591d9122e221d942d4564c82c4e9d638b75bb22b4d9
+  data.tar.gz: 3ea692d7b1969ec754177713345fd81cc5fd9b294f3697d118359b3564dd4d8f17bfc9b6f69efea4f6c696d414c77dd99a0de4c0cb689ed2432743d92d2be26e

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.3.0 - 2026-09-09
+
+- Add `CompiledMask#each_path` to enumerate selected paths with decoded field names and a distinct
+  `JsonMask::WILDCARD` token. Whole-field selections absorb descendants, and terminal wildcards
+  absorb sibling selections.
+- Add `JsonMask.format_path` to turn a path or prefix into an escaped slash-separated selector.
+
 ## 0.2.0 - 2026-09-04
 
 - Expose compiled selectors for inspection. `CompiledMask#selection_tree` returns the root

data/README.md

@@ -121,6 +121,48 @@ produce one by inspecting the compiled selector.
 
 ## Inspecting a compiled selector
 
+### Selected paths
+
+`CompiledMask#each_path` yields a fresh array of segments for each selected path. Without a block,
+it returns an `Enumerator`:
+
+```ruby
+mask = JsonMask.compile("id,assets(url,width),*/name")
+
+mask.each_path.to_a
+# => [["id"], ["assets", "url"], ["assets", "width"], [JsonMask::WILDCARD, "name"]]
+
+mask.each_path { |path| puts JsonMask.format_path(path) }
+# id
+# assets/url
+# assets/width
+# */name
+```
+
+Named segments are unescaped strings. `JsonMask::WILDCARD` (the symbol `:*`) represents a wildcard;
+the string `"*"` represents a literal field named `*`.
+
+Paths follow the compiled tree: named fields are visited depth first, then the wildcard at each
+level. Repeated named selections are merged. Selecting a whole field absorbs its descendants,
+and a terminal wildcard absorbs its siblings: `id,id/extra` yields only `["id"]`, while `*,typo`
+yields only `[JsonMask::WILDCARD]`. Nested wildcard paths stay separate from named paths.
+Blank selectors yield no paths. With a block, `each_path` returns the compiled mask.
+
+`JsonMask.format_path` converts a yielded path, or a prefix of one, into an escaped slash-separated
+selector. It escapes structural characters, whitespace, and NUL so literal names survive parsing:
+
+```ruby
+JsonMask.format_path(["a/b", "name"])            # => "a\\/b/name"
+JsonMask.format_path(["*", "id"])                # => "\\*/id"
+JsonMask.format_path([JsonMask::WILDCARD, "id"])  # => "*/id"
+JsonMask.format_path([])                        # => ""
+```
+
+This lets an application inspect or validate paths without traversing the selection tree or
+handling selector escaping itself.
+
+### Selection tree
+
 `JsonMask::CompiledMask#selection_tree` exposes the parsed selector as an immutable tree, for
 callers that need to examine a selector rather than apply it:
 

data/lib/json_mask/compiled_mask.rb

@@ -20,5 +20,34 @@ module JsonMask
     end
 
     alias filter call
+
+    # Yields selected paths with unescaped names and JsonMask::WILDCARD segments.
+    # Whole-field selections absorb descendants; a terminal wildcard absorbs siblings.
+    #
+    # @yieldparam path [Array<String, Symbol>] a fresh array for each selected path
+    # @return [Enumerator, CompiledMask] an enumerator without a block; self with a block
+    def each_path(&block)
+      return enum_for(__method__) unless block
+
+      walk_paths(selection_tree, [], &block) if selection_tree
+      self
+    end
+
+    private
+
+    def walk_paths(tree, prefix, &block)
+      return yield(prefix + [WILDCARD]) if tree.wildcard&.leaf?
+
+      selections = tree.named.to_a
+      selections << [WILDCARD, tree.wildcard] if tree.wildcard
+      selections.each do |name, selection|
+        path = prefix + [name]
+        if selection.leaf?
+          yield path
+        else
+          walk_paths(selection.children, path, &block)
+        end
+      end
+    end
   end
 end

data/lib/json_mask/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JsonMask
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/json_mask.rb

@@ -8,6 +8,8 @@ require_relative 'json_mask/projector'
 require_relative 'json_mask/compiled_mask'
 
 module JsonMask
+  WILDCARD = :*
+
   class << self
     def call(value, fields, **options)
       compile(fields, **options).call(value)
@@ -15,6 +17,16 @@ module JsonMask
 
     alias mask call
 
+    # Formats a path from CompiledMask#each_path, or a prefix of one, as a selector.
+    #
+    # @param path [Array<String, Symbol>] unescaped field names and WILDCARD segments
+    # @return [String] a slash-separated selector with literal names escaped
+    def format_path(path)
+      path.map do |name|
+        name == WILDCARD ? '*' : name.gsub(%r{[\\,/()*\s\x00]}) { |character| "\\#{character}" }
+      end.join('/')
+    end
+
     def compile(
       fields,
       max_length: Parser::DEFAULT_MAX_LENGTH,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: json-mask
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Robert Sheldon