json_p3 0.2.1 → 0.3.0

data/lib/json_p3/patch.rb

@@ -0,0 +1,441 @@
+# frozen_string_literal: true
+
+require "English"
+require_relative "errors"
+
+module JSONP3
+  # Base class for all JSON Patch operations
+  class Op
+    # Return the name of the patch operation.
+    def name
+      raise "JSON Patch operations must implement #name"
+    end
+
+    # Apply the patch operation to _value_.
+    def apply(_value, _index)
+      raise "JSON Patch operations must implement apply(value, index)"
+    end
+
+    # Return a JSON-like representation of this patch operation.
+    def to_h
+      raise "JSON Patch operations must implement #to_h"
+    end
+  end
+
+  # The JSON Patch _add_ operation.
+  class OpAdd < Op
+    # @param pointer [JSONPointer]
+    # @param value [JSON-like value]
+    def initialize(pointer, value)
+      super()
+      @pointer = pointer
+      @value = value
+    end
+
+    def name
+      "add"
+    end
+
+    def apply(value, index)
+      parent, obj = @pointer.resolve_with_parent(value)
+      return @value if parent == JSONP3::JSONPointer::UNDEFINED && @pointer.tokens.empty?
+
+      if parent == JSONP3::JSONPointer::UNDEFINED
+        raise JSONPatchError,
+              "no such property or item '#{@pointer.parent}' (#{name}:#{index})"
+      end
+
+      target = @pointer.tokens.last
+      if parent.is_a?(Array)
+        if obj == JSONP3::JSONPointer::UNDEFINED
+          raise JSONPatchError, "index out of range (#{name}:#{index})" unless target == "-"
+
+          parent << @value
+        else
+          parent.insert(target.to_i, @value)
+        end
+      elsif parent.is_a?(Hash)
+        parent[target] = @value
+      else
+        raise JSONPatchError, "unexpected operation on #{parent.class} (#{name}:#{index})"
+      end
+
+      value
+    end
+
+    def to_h
+      { "op" => name, "path" => @pointer.to_s, "value" => @value }
+    end
+  end
+
+  # The JSON Patch _remove_ operation.
+  class OpRemove < Op
+    # @param pointer [JSONPointer]
+    def initialize(pointer)
+      super()
+      @pointer = pointer
+    end
+
+    def name
+      "remove"
+    end
+
+    def apply(value, index)
+      parent, obj = @pointer.resolve_with_parent(value)
+
+      if parent == JSONP3::JSONPointer::UNDEFINED && @pointer.tokens.empty?
+        raise JSONPatchError,
+              "can't remove root (#{name}:#{index})"
+      end
+
+      if parent == JSONP3::JSONPointer::UNDEFINED
+        raise JSONPatchError,
+              "no such property or item '#{@pointer.parent}' (#{name}:#{index})"
+      end
+
+      target = @pointer.tokens.last
+      if target == JSONP3::JSONPointer::UNDEFINED
+        raise JSONPatchError,
+              "unexpected operation (#{name}:#{index})"
+      end
+
+      if parent.is_a?(Array)
+        raise JSONPatchError, "no item to remove (#{name}:#{index})" if obj == JSONP3::JSONPointer::UNDEFINED
+
+        parent.delete_at(target.to_i)
+      elsif parent.is_a?(Hash)
+        raise JSONPatchError, "no property to remove (#{name}:#{index})" if obj == JSONP3::JSONPointer::UNDEFINED
+
+        parent.delete(target)
+      else
+        raise JSONPatchError, "unexpected operation on #{parent.class} (#{name}:#{index})"
+      end
+
+      value
+    end
+
+    def to_h
+      { "op" => name, "path" => @pointer.to_s }
+    end
+  end
+
+  # The JSON Patch _replace_ operation.
+  class OpReplace < Op
+    # @param pointer [JSONPointer]
+    # @param value [JSON-like value]
+    def initialize(pointer, value)
+      super()
+      @pointer = pointer
+      @value = value
+    end
+
+    def name
+      "replace"
+    end
+
+    def apply(value, index)
+      parent, obj = @pointer.resolve_with_parent(value)
+      return @value if parent == JSONP3::JSONPointer::UNDEFINED && @pointer.tokens.empty?
+
+      if parent == JSONP3::JSONPointer::UNDEFINED
+        raise JSONPatchError,
+              "no such property or item '#{@pointer.parent}' (#{name}:#{index})"
+      end
+
+      target = @pointer.tokens.last
+      if target == JSONP3::JSONPointer::UNDEFINED
+        raise JSONPatchError,
+              "unexpected operation (#{name}:#{index})"
+      end
+
+      if parent.is_a?(Array)
+        raise JSONPatchError, "no item to replace (#{name}:#{index})" if obj == JSONP3::JSONPointer::UNDEFINED
+
+        parent[target.to_i] = @value
+      elsif parent.is_a?(Hash)
+        raise JSONPatchError, "no property to replace (#{name}:#{index})" if obj == JSONP3::JSONPointer::UNDEFINED
+
+        parent[target] = @value
+      else
+        raise JSONPatchError, "unexpected operation on #{parent.class} (#{name}:#{index})"
+      end
+
+      value
+    end
+
+    def to_h
+      { "op" => name, "path" => @pointer.to_s, "value" => @value }
+    end
+  end
+
+  # The JSON Patch _move_ operation.
+  class OpMove < Op
+    # @param from [JSONPointer]
+    # @param pointer [JSONPointer]
+    def initialize(from, pointer)
+      super()
+      @from = from
+      @pointer = pointer
+    end
+
+    def name
+      "move"
+    end
+
+    def apply(value, index)
+      if @pointer.relative_to?(@from)
+        raise JSONPatchError,
+              "can't move object to one of its children (#{name}:#{index})"
+      end
+
+      # Grab the source value.
+      source_parent, source_obj = @from.resolve_with_parent(value)
+      if source_obj == JSONP3::JSONPointer::UNDEFINED
+        raise JSONPatchError,
+              "source object does not exist (#{name}:#{index})"
+      end
+
+      source_target = @from.tokens.last
+      if source_target == JSONP3::JSONPointer::UNDEFINED
+        raise JSONPatchError,
+              "unexpected operation (#{name}:#{index})"
+      end
+
+      # Delete the target value from the source location.
+      if source_parent.is_a?(Array)
+        source_parent.delete_at(source_target.to_i)
+      elsif source_parent.is_a?(Hash)
+        source_parent.delete(source_target)
+      end
+
+      # Find the parent of the destination pointer.
+      dest_parent, _dest_obj = @pointer.resolve_with_parent(value)
+      return source_obj if dest_parent == JSONP3::JSONPointer::UNDEFINED
+
+      dest_target = @pointer.tokens.last
+      if dest_target == JSONP3::JSONPointer::UNDEFINED
+        raise JSONPatchError,
+              "unexpected operation (#{name}:#{index})"
+      end
+
+      # Write the source value to the destination.
+      if dest_parent.is_a?(Array)
+        dest_parent[dest_target.to_i] = source_obj
+      elsif dest_parent.is_a?(Hash)
+        dest_parent[dest_target] = source_obj
+      end
+
+      value
+    end
+
+    def to_h
+      { "op" => name, "from" => @from.to_s, "path" => @pointer.to_s }
+    end
+  end
+
+  # The JSON Patch _copy_ operation.
+  class OpCopy < Op
+    # @param from [JSONPointer]
+    # @param pointer [JSONPointer]
+    def initialize(from, pointer)
+      super()
+      @from = from
+      @pointer = pointer
+    end
+
+    def name
+      "copy"
+    end
+
+    def apply(value, index)
+      # Grab the source value.
+      _source_parent, source_obj = @from.resolve_with_parent(value)
+      if source_obj == JSONP3::JSONPointer::UNDEFINED
+        raise JSONPatchError,
+              "source object does not exist (#{name}:#{index})"
+      end
+
+      # Find the parent of the destination pointer.
+      dest_parent, _dest_obj = @pointer.resolve_with_parent(value)
+      return deep_copy(source_obj) if dest_parent == JSONP3::JSONPointer::UNDEFINED
+
+      dest_target = @pointer.tokens.last
+      if dest_target == JSONP3::JSONPointer::UNDEFINED
+        raise JSONPatchError,
+              "unexpected operation (#{name}:#{index})"
+      end
+
+      # Write the source value to the destination.
+      if dest_parent.is_a?(Array)
+        dest_parent.insert(dest_target.to_i, deep_copy(source_obj))
+      elsif dest_parent.is_a?(Hash)
+        dest_parent[dest_target] = deep_copy(source_obj)
+      else
+        raise JSONPatchError, "unexpected operation on #{dest_parent.class} (#{name}:#{index})"
+      end
+
+      value
+    end
+
+    def to_h
+      { "op" => name, "from" => @from.to_s, "path" => @pointer.to_s }
+    end
+
+    private
+
+    def deep_copy(obj)
+      Marshal.load(Marshal.dump(obj))
+    end
+  end
+
+  # The JSON Patch _test_ operation.
+  class OpTest < Op
+    # @param pointer [JSONPointer]
+    # @param value [JSON-like value]
+    def initialize(pointer, value)
+      super()
+      @pointer = pointer
+      @value = value
+    end
+
+    def name
+      "test"
+    end
+
+    def apply(value, index)
+      obj = @pointer.resolve(value)
+      raise JSONPatchTestFailure, "test failed (#{name}:#{index})" if obj != @value
+
+      value
+    end
+
+    def to_h
+      { "op" => name, "path" => @pointer.to_s, "value" => @value }
+    end
+  end
+
+  # A JSON Patch containing zero or more patch operations.
+  class JSONPatch
+    # @param ops [Array<Op | Hash<String, untyped>>?]
+    def initialize(ops = nil)
+      @ops = []
+      build(ops) unless ops.nil?
+    end
+
+    # @param pointer [String | JSONPointer]
+    # @param value [JSON-like value]
+    # @return [self]
+    def add(pointer, value)
+      @ops.push(OpAdd.new(ensure_pointer(pointer, :add, @ops.length), value))
+      self
+    end
+
+    # @param pointer [String | JSONPointer]
+    # @return [self]
+    def remove(pointer)
+      @ops.push(OpRemove.new(ensure_pointer(pointer, :remove, @ops.length)))
+      self
+    end
+
+    # @param pointer [String | JSONPointer]
+    # @param value [JSON-like value]
+    # @return [self]
+    def replace(pointer, value)
+      @ops.push(OpReplace.new(ensure_pointer(pointer, :replace, @ops.length), value))
+      self
+    end
+
+    # @param from [String | JSONPointer]
+    # @param pointer [String | JSONPointer]
+    # @return [self]
+    def move(from, pointer)
+      @ops.push(OpMove.new(
+                  ensure_pointer(from, :move, @ops.length),
+                  ensure_pointer(pointer, :move, @ops.length)
+                ))
+      self
+    end
+
+    # @param from [String | JSONPointer]
+    # @param pointer [String | JSONPointer]
+    # @return [self]
+    def copy(from, pointer)
+      @ops.push(OpCopy.new(
+                  ensure_pointer(from, :copy, @ops.length),
+                  ensure_pointer(pointer, :copy, @ops.length)
+                ))
+      self
+    end
+
+    # @param pointer [String | JSONPointer]
+    # @param value [JSON-like value]
+    # @return [self]
+    def test(pointer, value)
+      @ops.push(OpTest.new(ensure_pointer(pointer, :test, @ops.length), value))
+      self
+    end
+
+    # Apply this patch to JSON-like value _value_.
+    def apply(value)
+      @ops.each_with_index { |op, i| value = op.apply(value, i) }
+      value
+    end
+
+    def to_a
+      @ops.map(&:to_h)
+    end
+
+    private
+
+    # @param ops [Array<Op | Hash<String, untyped>>?]
+    # @return void
+    def build(ops)
+      ops.each_with_index do |obj, i|
+        if obj.is_a?(Op)
+          @ops << obj
+          next
+        end
+
+        case obj["op"]
+        when "add"
+          add(op_pointer(obj, "path", "add", i), op_value(obj, "value", "add", i))
+        when "remove"
+          remove(op_pointer(obj, "path", "remove", i))
+        when "replace"
+          replace(op_pointer(obj, "path", "replace", i), op_value(obj, "value", "replace", i))
+        when "move"
+          move(op_pointer(obj, "from", "move", i), op_pointer(obj, "path", "move", i))
+        when "copy"
+          copy(op_pointer(obj, "from", "copy", i), op_pointer(obj, "path", "copy", i))
+        when "test"
+          test(op_pointer(obj, "path", "test", i), op_value(obj, "value", "test", i))
+        else
+          raise JSONPatchError,
+                "expected 'op' to be one of 'add', 'remove', 'replace', 'move', 'copy' or 'test' (#{obj["op"]}:#{i})"
+        end
+      end
+    end
+
+    def op_pointer(obj, key, op, index)
+      raise JSONPatchError, "missing property '#{key}' (#{op}:#{index})" unless obj.key?(key)
+
+      JSONP3::JSONPointer.new(obj[key])
+    rescue JSONPointerError
+      raise JSONPatchError, "#{$ERROR_INFO} (#{op}:#{index})"
+    end
+
+    def op_value(obj, key, op, index)
+      raise JSONPatchError, "missing property '#{key}' (#{op}:#{index})" unless obj.key?(key)
+
+      obj[key]
+    end
+
+    def ensure_pointer(pointer, op, index)
+      return pointer unless pointer.is_a?(String)
+
+      JSONP3::JSONPointer.new(pointer)
+    rescue JSONPointerError
+      raise JSONPatchError, "#{$ERROR_INFO} (#{op}:#{index})"
+    end
+  end
+end

data/lib/json_p3/pointer.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module JSONP3
+  # Identify a single value in JSON-like data, as per RFC 6901.
+  class JSONPointer
+    RE_INT = /\A(0|[1-9][0-9]*)\z/
+    UNDEFINED = :__undefined
+
+    attr_reader :tokens
+
+    # Encode an array of strings and integers into a JSON Pointer.
+    # @param tokens [Array<String | Integer> | nil]
+    # @return [String]
+    def self.encode(tokens)
+      return "" if tokens.nil? || tokens.empty?
+
+      encoded = tokens.map do |token|
+        token.is_a?(Integer) ? token.to_s : token.gsub("~", "~0").gsub("/", "~1")
+      end
+
+      "/#{encoded.join("/")}"
+    end
+
+    # @param pointer [String]
+    def initialize(pointer)
+      @tokens = parse(pointer)
+      @pointer = JSONPointer.encode(@tokens)
+    end
+
+    # Resolve this pointer against JSON-like data _value_.
+    # @param value [Object]
+    # @param default [Object] the value to return if this pointer can not be
+    #  resolved against _value_.
+    def resolve(value, default: UNDEFINED)
+      item = value
+
+      @tokens.each do |token|
+        item = get_item(item, token)
+        return default if item == UNDEFINED
+      end
+
+      item
+    end
+
+    # Resolve this pointer against _value_, returning the resolved object and its
+    # parent object.
+    #
+    # @param value [Object]
+    # @return [Array<Object>] an array with exactly two elements, one or both of
+    #   which could be undefined.
+    def resolve_with_parent(value)
+      return [UNDEFINED, resolve(value)] if @tokens.empty?
+
+      parent = value
+      (@tokens[...-1] || raise).each do |token|
+        parent = get_item(parent, token)
+        break if parent == UNDEFINED
+      end
+
+      [parent, get_item(parent, @tokens.last)]
+    end
+
+    # Return true if this pointer is relative to _pointer_.
+    # @param pointer [JSONPointer]
+    # @return [bool]
+    def relative_to?(pointer)
+      pointer.tokens.length < @tokens.length && @tokens[...pointer.tokens.length] == pointer.tokens
+    end
+
+    # @param parts [String]
+    # @return [JSONPointer]
+    def join(*parts)
+      pointer = self
+      parts.each do |part|
+        pointer = pointer._join(part)
+      end
+      pointer
+    end
+
+    # Return _true_ if this pointer can be resolved against _value_, even if the resolved
+    # value is false or nil.
+    # @param value [Object]
+    def exist?(value)
+      resolve(value) != UNDEFINED
+    end
+
+    # Return this pointer's parent as a new pointer. If this pointer points to the
+    # document root, self is returned.
+    def parent
+      return self if @tokens.empty?
+
+      JSONPointer.new(JSONPointer.encode((@tokens[...-1] || raise)))
+    end
+
+    # Return a new pointer relative to this pointer using Relative JSON Pointer syntax.
+    # @param rel [String | RelativeJSONPointer]
+    # @return [JSONPointer]
+    def to(rel)
+      p = rel.is_a?(String) ? RelativeJSONPointer.new(rel) : rel
+      p.to(self)
+    end
+
+    def to_s
+      @pointer
+    end
+
+    protected
+
+    # @param pointer [String]
+    # @return [Array<String | Integer>]
+    def parse(pointer)
+      if pointer.length.positive? && !pointer.start_with?("/")
+        raise JSONPointerSyntaxError,
+              "pointers must start with a slash or be the empty string"
+      end
+
+      return [] if pointer.empty?
+      return [""] if pointer == "/"
+
+      (pointer[1..] || raise).split("/", -1).map do |token|
+        token.match?(/\A(?:0|[1-9][0-9]*)\z/) ? Integer(token) : token.gsub("~1", "/").gsub("~0", "~")
+      end
+    end
+
+    # @param value [Object]
+    # @param token [String | Integer]
+    # @return [Object] the "fetched" object from _value_ or UNDEFINED.
+    def get_item(value, token)
+      if value.is_a?(Array)
+        if token.is_a?(String) && token.start_with?("#")
+          maybe_index = token[1..] || raise
+          return maybe_index.to_i if RE_INT.match?(maybe_index)
+        end
+
+        return UNDEFINED unless token.is_a?(Integer)
+        return UNDEFINED if token.negative? || token >= value.length
+
+        value[token]
+      elsif value.is_a?(Hash)
+        return value[token] if value.key?(token)
+
+        # Handle "#" from relative JSON pointer
+        return token[1..] if token.is_a?(String) && token.start_with?("#") && value.key?(token[1..])
+
+        # Token might be an integer. Force it to a string and try again.
+        string_token = token.to_s
+        value.key?(string_token) ? value[string_token] : UNDEFINED
+      else
+        UNDEFINED
+      end
+    end
+
+    # Like `#parse`, but assumes there's no leading slash.
+    # @param pointer [String]
+    # @return [Array<String | Integer>]
+    def _parse(pointer)
+      return [] if pointer.empty?
+
+      pointer.split("/", -1).map do |token|
+        token.match?(/\A(?:0|[1-9][0-9]*)\z/) ? Integer(token) : token.gsub("~1", "/").gsub("~0", "~")
+      end
+    end
+
+    def _join(other)
+      raise JSONPointerTypeError, "unsupported join part" unless other.is_a?(String)
+
+      part = other.lstrip
+      part.start_with?("/") ? JSONPointer.new(part) : JSONPointer.new(JSONPointer.encode(@tokens + _parse(part)))
+    end
+  end
+
+  # A relative JSON Pointer.
+  # See https://datatracker.ietf.org/doc/html/draft-hha-relative-json-pointer
+  class RelativeJSONPointer
+    RE_RELATIVE_POINTER = /\A(?<ORIGIN>\d+)(?<INDEX_G>(?<SIGN>[+-])(?<INDEX>\d))?(?<POINTER>.*)\z/m
+    RE_INT = /\A(0|[1-9][0-9]*)\z/
+
+    # @param rel [String]
+    def initialize(rel)
+      match = RE_RELATIVE_POINTER.match(rel)
+
+      raise JSONPointerSyntaxError, "failed to parse relative pointer" if match.nil?
+
+      @origin = parse_int(match[:ORIGIN] || raise)
+      @index = 0
+
+      if match[:INDEX_G]
+        @index = parse_int(match[:INDEX] || raise)
+        raise JSONPointerSyntaxError, "index offset can't be zero" if @index.zero?
+
+        @index = -@index if match[:SIGN] == "-"
+      end
+
+      @pointer = match[:POINTER] == "#" ? "#" : JSONPointer.new(match[:POINTER] || raise)
+    end
+
+    def to_s
+      sign = @index.positive? ? "+" : ""
+      index = @index.zero? ? "" : "#{sign}#{@index}"
+      "#{@origin}#{index}#{@pointer}"
+    end
+
+    # Return a new JSON Pointer by applying this relative pointer to _pointer_.
+    # @param pointer [String | JSONPointer]
+    # @return [JSONPointer]
+    def to(pointer)
+      p = pointer.is_a?(String) ? JSONPointer.new(pointer) : pointer
+
+      raise JSONPointerIndexError, "origin (#{@origin}) exceeds root (#{p.tokens.length})" if @origin > p.tokens.length
+
+      tokens = @origin < 1 ? p.tokens[0..] || raise : p.tokens[0...-@origin] || raise
+      tokens[-1] = (tokens[-1] || raise) + @index if @index != 0 && tokens.length.positive? && tokens[-1].is_a?(Integer)
+
+      if @pointer == "#"
+        tokens[-1] = "##{tokens[-1]}"
+      else
+        tokens.concat(@pointer.tokens) # steep:ignore
+      end
+
+      JSONPointer.new(JSONPointer.encode(tokens))
+    end
+
+    private
+
+    # @param token [String]
+    # @return [Integer]
+    def parse_int(token)
+      raise JSONPointerSyntaxError, "unexpected leading zero" if token.start_with?("0") && token.length > 1
+      raise JSONPointerSyntaxError, "expected an integer, found '#{token}'" unless RE_INT.match?(token)
+
+      token.to_i
+    end
+  end
+end

data/lib/json_p3/segment.rb

@@ -21,7 +21,7 @@ module JSONP3
   # The child selection segment.
   class ChildSegment < Segment
     def resolve(nodes)
-      rv = []
+      rv = [] # : Array[JSONPathNode]
       nodes.each do |node|
         @selectors.each do |selector|
           rv.concat selector.resolve(node)
@@ -50,7 +50,7 @@ module JSONP3
   # The recursive descent segment
   class RecursiveDescentSegment < Segment
     def resolve(nodes)
-      rv = []
+      rv = [] # : Array[JSONPathNode]
       nodes.each do |node|
         visit(node).each do |descendant|
           @selectors.each do |selector|
@@ -79,7 +79,7 @@ module JSONP3
 
     protected
 
-    def visit(node, depth = 1) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    def visit(node, depth = 1)
       raise JSONPathRecursionError.new("recursion limit exceeded", @token) if depth > @env.class::MAX_RECURSION_DEPTH
 
       rv = [node]