philiprehberger-dot_access 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6904bd424f71dc389f5dc2ac6c89e12c85b00fb3da9e0d3a8188e74441d7f12
-  data.tar.gz: adfd54811267a34f7b84c922df8f7f3c460250dd1b77b7013a212999846cbc2a
+  metadata.gz: c067bfe9e48161257e318e8504f10a2604d9899e4340dadbfc42a76f8df23466
+  data.tar.gz: ccf282fefd6897e5ae90bf664fffb8efda891d67a357bf226a2fdd1a3af79cce
 SHA512:
-  metadata.gz: 8d92a2e22c4cf47787560bb89843c23e915debc51649b52e658703d33edf0608f5bc446dc398e6984af0418f56695a0da670dc572d439e5cd6f60047802f87be
-  data.tar.gz: 6ee9cc79cd31fb360f38fd55db44306025d961746c571ee8919a5bf1beaa27fd9b6da89c8164d7665fe9f576bfdfc6df8b14ae8ee8cc20c31399c8f3debe8471
+  metadata.gz: e0f6ce17f68d1685a8742327c215a5af5a14879cf4a9560eccd20bf127d06a04fd99a81acfc0e15ae895836c3a87c8c5034e615336f255a8313ee09977deff4d
+  data.tar.gz: 31f94f7fa8ee543f7ee9304bd3814ef24cc30b7199108821ec61c4da4b6e54c9983c7d8fb0024dae94aace73c06017275019e9febcf7e88cdd7c2c5f77bfbb52

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-05-20
+
+### Added
+- JSON Pointer (RFC 6901) support: `Wrapper#get_pointer`, `#set_pointer`, `#delete_pointer`, and `#has_pointer?` plus the helper `Wrapper.parse_pointer`, for interop with JSON Schema and JSON Patch tooling
+- Card image reference in the README for registry-side rendering
+
+### Changed
+- Raised the `Metrics/ClassLength` RuboCop ceiling on `Wrapper` to fit the new pointer methods
+
 ## [0.7.0] - 2026-04-30
 
 ### Added

data/README.md

@@ -4,6 +4,8 @@
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-dot_access.svg)](https://rubygems.org/gems/philiprehberger-dot_access)
 [![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-dot-access)](https://github.com/philiprehberger/rb-dot-access/commits/main)
 
+![philiprehberger-dot_access](https://raw.githubusercontent.com/philiprehberger/rb-dot-access/main/package-card.webp)
+
 Dot-notation accessor for nested hashes with nil-safe traversal
 
 ## Requirements
@@ -230,6 +232,28 @@ config = Philiprehberger::DotAccess.wrap({ a: { b: 1 } })
 config.to_h  # => { a: { b: 1 } }
 ```
 
+### JSON Pointer (RFC 6901) Access
+
+Useful when interoperating with JSON Schema, JSON Patch, or any tooling that already speaks JSON Pointer paths.
+
+```ruby
+data = Philiprehberger::DotAccess.wrap(
+  users: [{ name: "alice" }, { name: "bob" }],
+  "a/b": { "c~d": 1 }
+)
+
+data.get_pointer("/users/0/name")          # => "alice"
+data.get_pointer("")                        # => the wrapper itself (root)
+data.get_pointer("/missing", default: :nf)  # => :nf
+
+# ~1 escapes /, ~0 escapes ~ — so the key "a/b" → "a~1b"
+data.get_pointer("/a~1b/c~0d")  # => 1
+
+data.has_pointer?("/users/1/name")  # => true
+updated = data.set_pointer("/users/0/name", "alex")
+trimmed = data.delete_pointer("/users/0/name")
+```
+
 ## API
 
 ### `Philiprehberger::DotAccess`
@@ -263,6 +287,10 @@ config.to_h  # => { a: { b: 1 } }
 | `#to_json` | Serialize back to a JSON string |
 | `#to_yaml` | Serialize back to a YAML string |
 | `#to_h` | Convert back to a plain hash |
+| `#get_pointer(pointer, default: nil)` | Retrieve a value by a JSON Pointer (RFC 6901) path |
+| `#has_pointer?(pointer)` | Check if a JSON Pointer path exists |
+| `#set_pointer(pointer, value)` | Return a new wrapper with the value set at a JSON Pointer path |
+| `#delete_pointer(pointer)` | Return a new wrapper without the value at a JSON Pointer path |
 
 ### `Philiprehberger::DotAccess::NullAccess`
 

data/lib/philiprehberger/dot_access/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module DotAccess
-    VERSION = '0.7.0'
+    VERSION = '0.8.0'
   end
 end

data/lib/philiprehberger/dot_access.rb

@@ -257,6 +257,100 @@ module Philiprehberger
         Wrapper.new(new_data)
       end
 
+      # Access a value by a JSON Pointer (RFC 6901) path.
+      #
+      # JSON Pointer paths start with `/`, separate segments with `/`, and escape
+      # `~` as `~0` and `/` as `~1`. An empty pointer (`""`) refers to the whole
+      # wrapped document.
+      #
+      # @param pointer [String] the JSON Pointer (e.g. `"/users/0/name"`)
+      # @param default [Object] value returned if the pointer is not found
+      # @return [Object] the value at the pointer, or ``default``
+      def get_pointer(pointer, default: nil)
+        segments = Wrapper.parse_pointer(pointer)
+        return self if segments.empty?
+
+        result = segments.reduce(@data) do |current, seg|
+          case current
+          when Hash then current[seg.to_sym]
+          when Array
+            index = array_index(seg, current)
+            return default if index.nil?
+
+            current[index]
+          else return default
+          end
+        end
+
+        result.nil? ? default : result
+      end
+
+      # Whether a JSON Pointer (RFC 6901) path exists in the wrapped structure.
+      #
+      # @param pointer [String] the JSON Pointer
+      # @return [Boolean]
+      def has_pointer?(pointer)
+        segments = Wrapper.parse_pointer(pointer)
+        return true if segments.empty?
+
+        current = @data
+        segments.each do |seg|
+          case current
+          when Hash
+            return false unless current.key?(seg.to_sym)
+
+            current = current[seg.to_sym]
+          when Array
+            index = array_index(seg, current)
+            return false if index.nil?
+
+            current = current[index]
+          else
+            return false
+          end
+        end
+        true
+      end
+
+      # Set a value at a JSON Pointer path, returning a new Wrapper.
+      #
+      # @param pointer [String] the JSON Pointer
+      # @param value [Object] the value to set
+      # @return [Wrapper] a new wrapper with the updated value
+      # @raise [Error] if the pointer is empty (would replace the entire document)
+      def set_pointer(pointer, value)
+        segments = Wrapper.parse_pointer(pointer)
+        raise Error, 'cannot set the root pointer' if segments.empty?
+
+        Wrapper.new(deep_set(to_h, segments, value))
+      end
+
+      # Delete the value at a JSON Pointer path, returning a new Wrapper.
+      #
+      # @param pointer [String] the JSON Pointer
+      # @return [Wrapper] a new wrapper without the specified pointer
+      # @raise [Error] if the pointer is empty
+      def delete_pointer(pointer)
+        segments = Wrapper.parse_pointer(pointer)
+        raise Error, 'cannot delete the root pointer' if segments.empty?
+
+        Wrapper.new(deep_delete(to_h, segments))
+      end
+
+      # Parse a JSON Pointer string into an array of unescaped segments.
+      # Public so callers and {#get_pointer}/{#set_pointer}/etc. share one parser.
+      #
+      # @param pointer [String]
+      # @return [Array<String>] the unescaped segments
+      # @raise [Error] if the pointer is not a String or does not start with `/`
+      def self.parse_pointer(pointer)
+        raise Error, 'pointer must be a String' unless pointer.is_a?(String)
+        return [] if pointer.empty?
+        raise Error, "JSON Pointer must start with '/' (got #{pointer.inspect})" unless pointer.start_with?('/')
+
+        pointer[1..].split('/', -1).map { |seg| seg.gsub('~1', '/').gsub('~0', '~') }
+      end
+
       # Flatten the nested structure into a hash whose keys are dot-paths.
       #
       # @return [Hash] flat hash where keys are dot-path strings

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-dot_access
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-30 00:00:00.000000000 Z
+date: 2026-05-20 00:00:00.000000000 Z
 dependencies: []
 description: Access deeply nested hash values using dot notation (config.database.host)
   with nil-safe traversal that never raises on missing keys. Supports path-based get/set,