json_p3 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61e9c2e2224055046c93b4aff7c4f12cfaed22805507d0678e23e322a7d2ee60
-  data.tar.gz: b3460ee7b36ab677af85540b5962701c16313723a98bfba7a722c9ebf7aa0d52
+  metadata.gz: 2d20426353cc6a3b8f7be130f6b5d3dd8ff37dcad13ac2b81a7a421f70d0462c
+  data.tar.gz: c93805a6ca467e830881176da0b9203bf3cfce7d85690749621bf3609de43e1c
 SHA512:
-  metadata.gz: 5aba27e4070700def8c89ff758a244ebba2fc3f31fbeb882492b0bf9260c61b1f55be0bb655dc5885bc226b7a29f3640ddf78c3801eaabfa291b3937d8723496
-  data.tar.gz: 96df0d295a541d98e17100a72f10584780a023baef88e9141c108c0137456bc8f1524a5a3e627dc7c14db4368c107d69d7476c47271914a137e98bf26e8210c9
+  metadata.gz: 329b8946de0220d55a7d1358bfd3062bced99420247b14d95ec023ab7fbb22a336534d227ebbf37766890f2c2c68bf5dc482504e10860b12845830930c560d5f
+  data.tar.gz: d248901e8c95aaa4ca7336d56439542cb4c6208c94993a6324e48b9dcbf95c00ed84040f36d697c99fe8b629e48c58f5c01bd0d55a6e8eac2ffa2af23ce06779

data/.rubocop.yml

@@ -12,3 +12,22 @@ Style/StringLiterals:
 
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
+
+Metrics/AbcSize:
+  Max: 50
+
+Metrics/ClassLength:
+  Max: 500
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/MethodLength:
+  Max: 35
+
+Metrics/PerceivedComplexity:
+  Max: 20
+
+Naming/MethodParameterName:
+  AllowedNames:
+    - op

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## [0.3.0] - 2024-11-25
+
+- Implement JSON Pointer and Relative JSON Pointer
+- Implement JSON Patch
+
 ## [0.2.1] - 2024-10-24
 
 - Rename project and gem

data/README.md

@@ -11,6 +11,13 @@ We follow <a href="https://datatracker.ietf.org/doc/html/rfc9535">RFC 9535</a> s
   <a href="https://github.com/jg-rp/ruby-json-p3/actions">
     <img src="https://img.shields.io/github/actions/workflow/status/jg-rp/ruby-json-p3/main.yml?branch=main&label=tests&style=flat-square" alt="Tests">
   </a>
+  <br>
+  <a href="https://rubygems.org/gems/json_p3">
+    <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">
+  </a>
 </p>
 
 ---
@@ -21,12 +28,38 @@ We follow <a href="https://datatracker.ietf.org/doc/html/rfc9535">RFC 9535</a> s
 - [Example](#example)
 - [Links](#links)
 - [Related projects](#related-projects)
-- [API](#api)
+- [Quick start](#quick-start)
 - [Contributing](#contributing)
 
 ## Install
 
-TODO: once published to RubyGems.org
+Add `'json_p3'` to your Gemfile:
+
+```
+gem 'json_p3', '~> 0.2.1'
+```
+
+Or
+
+```
+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:
+
+```
+gem cert --add <(curl -Ls https://raw.githubusercontent.com/jg-rp/ruby-json-p3/refs/heads/main/certs/jgrp.pem)
+```
+
+Followed by:
+
+```
+gem install json_p3 -P MediumSecurity
+```
+
+JSON P3 has no runtime dependencies, so `-P HighSecurity` is OK too. See https://guides.rubygems.org/security/ for more information.
 
 ## Example
 
@@ -97,7 +130,7 @@ end
 ## Links
 
 - Change log: https://github.com/jg-rp/ruby-json-p3/blob/main/CHANGELOG.md
-- TODO: RubyGems
+- RubyGems: https://rubygems.org/gems/json_p3
 - Source code: https://github.com/jg-rp/ruby-json-p3
 - Issue tracker: https://github.com/jg-rp/ruby-json-p3/issues
 
@@ -107,13 +140,13 @@ end
 - [Python JSONPath](https://github.com/jg-rp/python-jsonpath) - Another Python package implementing JSONPath, but with additional features and customization options.
 - [JSON P3](https://github.com/jg-rp/json-p3) - RFC 9535 implemented in TypeScript.
 
-## API
+## Quick start
 
 ### find
 
-`find(query, value) -> Array[JSONPathNode]`
+`find(query, value) -> Array<JSONPathNode>`
 
-Apply JSONPath expression _query_ to JSON-like data _value_. An array of JSONPathNode instance is returned, one node for each value matched by _query_. The returned array will be empty if there were no matches.
+Apply JSONPath expression _query_ to JSON-like data _value_. An array of JSONPathNode instances is returned, one node for each value matched by _query_. The returned array will be empty if there were no matches.
 
 Each `JSONPathNode` has:
 
@@ -229,7 +262,7 @@ nodes = jsonpath.find("$.*", { "a" => "b", "c" => "d" })
 pp nodes.map(&:value) # ["b", "d"]
 ```
 
-To configure an environment with custom filter functions or non-standard selectors, inherit from `JSONPathEnvironment` and override some of its constants or `#setup_function_extensions` method.
+To configure an environment with custom filter functions or non-standard selectors, inherit from `JSONPathEnvironment` and override some of its constants or the `#setup_function_extensions` method.
 
 ```ruby
 class MyJSONPathEnvironment < JSONP3::JSONPathEnvironment
@@ -253,7 +286,7 @@ class MyJSONPathEnvironment < JSONP3::JSONPathEnvironment
   NAME_SELECTOR = NameSelector
 
   # An implementation of the _index selector_. The default implementation will
-  # select value from arrays only. Implement your own by inheriting from
+  # select values from arrays only. Implement your own by inheriting from
   # {IndexSelector} and overriding `#resolve`.
   INDEX_SELECTOR = IndexSelector
 
@@ -286,45 +319,138 @@ JSONP3::JSONPathSyntaxError: unexpected trailing whitespace
   |      ^ unexpected trailing whitespace
 ```
 
+### resolve
+
+`resolve(pointer, value) -> Object`
+
+Resolve a JSON Pointer (RFC 6901) against some data using `JSONP3.resolve()`.
+
+```ruby
+require "json_p3"
+require "json"
+
+data = JSON.parse <<~JSON
+  {
+    "users": [
+      {
+        "name": "Sue",
+        "score": 100
+      },
+      {
+        "name": "Sally",
+        "score": 84,
+        "admin": false
+      },
+      {
+        "name": "John",
+        "score": 86,
+        "admin": true
+      },
+      {
+        "name": "Jane",
+        "score": 55
+      }
+    ],
+    "moderator": "John"
+  }
+JSON
+
+puts JSONP3.resolve("/users/1", data)
+# {"name"=>"Sally", "score"=>84, "admin"=>false}
+```
+
+If a pointer can not be resolved, `JSONP3::JSONPointer::UNDEFINED` is returned instead. You can use your own default value using the `default:` keyword argument.
+
+```ruby
+# continued from above
+
+pp JSONP3.resolve("/no/such/thing", data, default: nil) # nil
+```
+
+### apply
+
+`apply(ops, value) -> Object`
+
+Apply a JSON Patch ([RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902)) with `JSONP3.apply()`. **Data is modified in place**.
+
+```ruby
+require "json"
+require "json_p3"
+
+ops = <<~JSON
+  [
+    { "op": "add", "path": "/some/foo", "value": { "foo": {} } },
+    { "op": "add", "path": "/some/foo", "value": { "bar": [] } },
+    { "op": "copy", "from": "/some/other", "path": "/some/foo/else" },
+    { "op": "add", "path": "/some/foo/bar/-", "value": 1 }
+  ]
+JSON
+
+data = { "some" => { "other" => "thing" } }
+JSONP3.apply(JSON.parse(ops), data)
+pp data
+# {"some"=>{"other"=>"thing", "foo"=>{"bar"=>[1], "else"=>"thing"}}}
+```
+
+`JSONP3.apply(ops, value)` is a convenience method equivalent to `JSONP3::JSONPatch.new(ops).apply(value)`. Use the `JSONPatch` constructor when you need to apply the same patch to different data.
+
+As well as passing an array of hashes following RFC 6902 as ops to `JSONPatch`, we offer a builder API to construct JSON Patch documents programmatically.
+
+```ruby
+require "json_p3"
+
+data = { "some" => { "other" => "thing" } }
+
+patch = JSONP3::JSONPatch.new
+                         .add("/some/foo", { "foo" => [] })
+                         .add("/some/foo", { "bar" => [] })
+                         .copy("/some/other", "/some/foo/else")
+                         .copy("/some/foo/else", "/some/foo/bar/-")
+
+patch.apply(data)
+pp data
+# {"some"=>{"other"=>"thing", "foo"=>{"bar"=>["thing"], "else"=>"thing"}}}
+```
+
 ## Contributing
 
 Your contributions and questions are always welcome. Feel free to ask questions, report bugs or request features on the [issue tracker](https://github.com/jg-rp/ruby-json-p3/issues) or on [Github Discussions](https://github.com/jg-rp/ruby-json-p3/discussions). Pull requests are welcome too.
 
 ### Development
 
-The [JSONPath Compliance Test Suite](https://github.com/jsonpath-standard/jsonpath-compliance-test-suite) is included as a git [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules). Clone the Ruby JSONPath RFC 9535 git repository and initialize the CTS submodule.
+The [JSONPath Compliance Test Suite](https://github.com/jsonpath-standard/jsonpath-compliance-test-suite) is included as a git [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules). Clone the JSON P3 git repository and initialize the CTS submodule.
 
 ```shell
 $ git clone git@github.com:jg-rp/ruby-json-p3.git
-$ cd ruby-json-p3.git
+$ cd ruby-json-p3
 $ git submodule update --init
 ```
 
-We use [Bundler](https://bundler.io/) and [Rake](https://ruby.github.io/rake/). Install development dependencies with
+We use [Bundler](https://bundler.io/) and [Rake](https://ruby.github.io/rake/). Install development dependencies with:
 
 ```
 bundle install
 ```
 
-Run tests with
+Run tests with:
 
 ```
 bundle exec rake test
 ```
 
-Lint with
+Lint with:
 
 ```
 bundle exec rubocop
 ```
 
-And type check with
+And type check with:
 
 ```
 bundle exec steep
 ```
 
-Run one of the benchmarks with
+Run one of the benchmarks with:
 
 ```
 bundle exec ruby performance/benchmark_ips.rb
@@ -334,7 +460,7 @@ bundle exec ruby performance/benchmark_ips.rb
 
 #### CPU profile
 
-Dump profile data with `bundle exec ruby performance/profile.rb`, then generate an HTML flame graph with
+Dump profile data with `bundle exec ruby performance/profile.rb`, then generate an HTML flame graph with:
 
 ```
 bundle exec stackprof --d3-flamegraph .stackprof-cpu-just-compile.dump > flamegraph-cpu-just-compile.html

data/certs/jgrp.pem

@@ -0,0 +1,27 @@
+-----BEGIN CERTIFICATE-----
+MIIEhTCCAu2gAwIBAgIBATANBgkqhkiG9w0BAQsFADBEMRYwFAYDVQQDDA1qYW1l
+c2dyLnByaW9yMRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJk/IsZAEZ
+FgNjb20wHhcNMjQxMDI0MDcxNDAzWhcNMjUxMDI0MDcxNDAzWjBEMRYwFAYDVQQD
+DA1qYW1lc2dyLnByaW9yMRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJ
+k/IsZAEZFgNjb20wggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAwggGKAoIBgQDvtEeN
+ZNN153v2ZK+U+Tj7kfRgl52GzmZS7lIG83xvT5/K8xEG5G4Tqiq/aGuDdbnxtd/t
+TQf6CtkixPzwj7WGIwoV28AUHKOJ7UjqRhXIuAn3nmzRLRNK2gVYpvzLTNCyLhIb
+jyZqgvtjR9mmW/Uuq+9LcLN4iFfkW+4dSmcABnkZHWMWGZYMIwoYYpluEUS1KiRZ
+mIALPEGO5JcpVvjpDwaP6GqV0khgnLixz9KlAF+2DCyki21wxtJoxJTuL9H5Ogb+
+k+nDQd9ELFYfbn73UKYGPtoUxkQeNF/ajJAkb/8t0cwUeSgtpSPhWIITWBgdLq11
+svViBlK9UZZC+dWG9x1lueVTG9fXBl69NJ9VA7MaxmHVY133sEySqwZMCrtDYjPX
+wIzLI2U8iSDIsjxTq3F3pbxeD4ee85ZY/xAV9M6fpjmKJERibRZTUPQo9ujHAhVM
+YNbfAHhPRGphT64/ocBjCmonrvA0fB3jP5wduEa5vD3JPOSb7dtCnNzNvDcCAwEA
+AaOBgTB/MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQWBBSswivEK7I4
+DrAJcSgIMhgedOJm5DAiBgNVHREEGzAZgRdqYW1lc2dyLnByaW9yQGdtYWlsLmNv
+bTAiBgNVHRIEGzAZgRdqYW1lc2dyLnByaW9yQGdtYWlsLmNvbTANBgkqhkiG9w0B
+AQsFAAOCAYEAdq8q0kDj14XNFMVYdjv1dG6Zaom3hEIkWv7+AsaPVw33puAnffQU
+lb2H1FG0LOGailuzPUadop6w/7oHO2jefj/85V0Tk6Hhk8cQpYQrtQgOHA3nsbmJ
+9JksJ+Y8RbyZP5dDTyZjTG4N3kgwZeNozcLeLj2ONBZRvGAjh8fyHOdLMPVNpM2K
+naRHKdSqWSU728nHDiVvLlGVkRInDmC+gC1msKqSEnQrLiBl27jMbsce9GKi2cb7
+DNjDwDg37yrbWgU5LS97+DU6dbMGVE3zPpuZGPZMTdXqzWWy2VlTPXMvAVt3Y4YG
+90hO1nDIwLn/1w9+Vb76b/5xc8AWWLozK4IPjh3pTvL6tCDiZw7tOQYp2uIO1Id1
+hKbb8cJaj/A6UsTE00yz5CUyQMcLz3LaL9k7Ek0u7vCcJLicl1HbAeq1ah7ePLLX
+6dM18fnfBc3yA4KI7AO8UAmRkTscMYV6f/K4YZR6ZYCNWRpY7rkg+arhf05aoSQf
+vn9bO1bzwdnG
+-----END CERTIFICATE-----

data/lib/json_p3/cache.rb

@@ -24,7 +24,7 @@ module JSONP3
       if @data.key?(key)
         @data.delete(key)
       elsif @data.length >= @max_size
-        @data.delete(@data.first[0])
+        @data.delete((@data.first || raise)[0])
       end
       @data[key] = value
     end

data/lib/json_p3/environment.rb

@@ -35,7 +35,7 @@ module JSONP3
     NAME_SELECTOR = NameSelector
 
     # An implementation of the _index selector_. The default implementation will
-    # select value from arrays only. Implement your own by inheriting from
+    # select values from arrays only. Implement your own by inheriting from
     # {IndexSelector} and overriding `#resolve`.
     INDEX_SELECTOR = IndexSelector
 

data/lib/json_p3/errors.rb

@@ -13,7 +13,7 @@ module JSONP3
       @token = token
     end
 
-    def detailed_message(highlight: true, **_kwargs) # rubocop:disable Metrics/AbcSize
+    def detailed_message(highlight: true, **_kwargs)
       if @token.query.strip.empty?
         "empty query"
       else
@@ -46,4 +46,12 @@ module JSONP3
   class JSONPathTypeError < JSONPathError; end
   class JSONPathNameError < JSONPathError; end
   class JSONPathRecursionError < JSONPathError; end
+
+  class JSONPointerError < StandardError; end
+  class JSONPointerIndexError < JSONPointerError; end
+  class JSONPointerSyntaxError < JSONPointerError; end
+  class JSONPointerTypeError < JSONPointerError; end
+
+  class JSONPatchError < StandardError; end
+  class JSONPatchTestFailure < JSONPatchError; end
 end

data/lib/json_p3/filter.rb

@@ -356,10 +356,10 @@ module JSONP3 # rubocop:disable Style/Documentation
     # @param func [Proc]
     # @param args [Array<Object>]
     # @return [Array<Object>]
-    def unpack_node_lists(func, args) # rubocop:disable Metrics/MethodLength
+    def unpack_node_lists(func, args)
       unpacked_args = []
       args.each_with_index do |arg, i|
-        unless arg.is_a?(JSONPathNodeList) && func.class::ARG_TYPES[i] != ExpressionType::NODES
+        unless arg.is_a?(JSONPathNodeList) && func.class::ARG_TYPES[i] != :nodes_expression
           unpacked_args << arg
           next
         end
@@ -384,7 +384,7 @@ module JSONP3 # rubocop:disable Style/Documentation
     obj != false
   end
 
-  def self.eq?(left, right) # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize
+  def self.eq?(left, right)
     left = left.first.value if left.is_a?(JSONPathNodeList) && left.length == 1
     right = right.first.value if right.is_a?(JSONPathNodeList) && right.length == 1
 
@@ -403,7 +403,7 @@ module JSONP3 # rubocop:disable Style/Documentation
     left == right
   end
 
-  def self.lt?(left, right) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/AbcSize, Metrics/PerceivedComplexity
+  def self.lt?(left, right)
     left = left.first.value if left.is_a?(JSONPathNodeList) && left.length == 1
     right = right.first.value if right.is_a?(JSONPathNodeList) && right.length == 1
     return left < right if left.is_a?(String) && right.is_a?(String)

data/lib/json_p3/function.rb

@@ -1,12 +1,6 @@
 # frozen_string_literal: true
 
 module JSONP3
-  class ExpressionType
-    VALUE = :value_expression
-    LOGICAL = :logical_expression
-    NODES = :nodes_expression
-  end
-
   # Base class for all filter functions.
   class FunctionExtension
     def call(*_args, **_kwargs)

data/lib/json_p3/function_extensions/count.rb

@@ -5,8 +5,8 @@ require_relative "../function"
 module JSONP3
   # The standard `count` function.
   class Count < FunctionExtension
-    ARG_TYPES = [ExpressionType::NODES].freeze
-    RETURN_TYPE = ExpressionType::VALUE
+    ARG_TYPES = [:nodes_expression].freeze
+    RETURN_TYPE = :value_expression
 
     def call(node_list)
       node_list.length

data/lib/json_p3/function_extensions/length.rb

@@ -5,8 +5,8 @@ require_relative "../function"
 module JSONP3
   # The standard `length` function.
   class Length < FunctionExtension
-    ARG_TYPES = [ExpressionType::VALUE].freeze
-    RETURN_TYPE = ExpressionType::VALUE
+    ARG_TYPES = [:value_expression].freeze
+    RETURN_TYPE = :value_expression
 
     def call(obj)
       return :nothing unless obj.is_a?(Array) || obj.is_a?(Hash) || obj.is_a?(String)

data/lib/json_p3/function_extensions/match.rb

@@ -7,8 +7,8 @@ require_relative "pattern"
 module JSONP3
   # The standard `match` function.
   class Match < FunctionExtension
-    ARG_TYPES = [ExpressionType::VALUE, ExpressionType::VALUE].freeze
-    RETURN_TYPE = ExpressionType::LOGICAL
+    ARG_TYPES = %i[value_expression value_expression].freeze
+    RETURN_TYPE = :logical_expression
 
     # @param cache_size [Integer] the maximum size of the regexp cache. Set it to
     #   zero or negative to disable the cache.
@@ -24,7 +24,7 @@ module JSONP3
     # @param value [String]
     # @param pattern [String]
     # @return Boolean
-    def call(value, pattern) # rubocop:disable Metrics/MethodLength
+    def call(value, pattern)
       return false unless pattern.is_a?(String) && value.is_a?(String)
 
       if @cache_size.positive?

data/lib/json_p3/function_extensions/pattern.rb

@@ -4,7 +4,7 @@ module JSONP3 # rubocop:disable Style/Documentation
   # Map I-Regexp pattern to Ruby regex pattern.
   # @param pattern [String]
   # @return [String]
-  def self.map_iregexp(pattern) # rubocop:disable Metrics/MethodLength
+  def self.map_iregexp(pattern)
     escaped = false
     char_class = false
     mapped = String.new(encoding: "UTF-8")

data/lib/json_p3/function_extensions/search.rb

@@ -7,8 +7,8 @@ require_relative "pattern"
 module JSONP3
   # The standard `search` function.
   class Search < FunctionExtension
-    ARG_TYPES = [ExpressionType::VALUE, ExpressionType::VALUE].freeze
-    RETURN_TYPE = ExpressionType::LOGICAL
+    ARG_TYPES = %i[value_expression value_expression].freeze
+    RETURN_TYPE = :logical_expression
 
     # @param cache_size [Integer] the maximum size of the regexp cache. Set it to
     #   zero or negative to disable the cache.
@@ -24,7 +24,7 @@ module JSONP3
     # @param value [String]
     # @param pattern [String]
     # @return Boolean
-    def call(value, pattern) # rubocop:disable Metrics/MethodLength
+    def call(value, pattern)
       return false unless pattern.is_a?(String) && value.is_a?(String)
 
       if @cache_size.positive?

data/lib/json_p3/function_extensions/value.rb

@@ -5,8 +5,8 @@ require_relative "../function"
 module JSONP3
   # The standard `value` function.
   class Value < FunctionExtension
-    ARG_TYPES = [ExpressionType::NODES].freeze
-    RETURN_TYPE = ExpressionType::VALUE
+    ARG_TYPES = [:nodes_expression].freeze
+    RETURN_TYPE = :value_expression
 
     def call(node_list)
       node_list.length == 1 ? node_list.first.value : :nothing