json_p3 0.4.0 → 1.0.0

data/lib/json_p3/pointer.rb

@@ -1,15 +1,17 @@
 # frozen_string_literal: true
 
-require_relative "errors"
-
 module JSONP3
   # Identify a single value in JSON-like data, as per RFC 6901.
-  class JSONPointer
+  class Pointer
     RE_INT = /\A(0|[1-9][0-9]*)\z/
     UNDEFINED = :__undefined
 
     attr_reader :tokens
 
+    def self.resolve(pointer, value, default: UNDEFINED)
+      new(pointer).resolve(value, default: default)
+    end
+
     # Encode an array of strings and integers into a JSON Pointer.
     # @param tokens [Array<String | Integer> | nil]
     # @return [String]
@@ -26,7 +28,7 @@ module JSONP3
     # @param pointer [String]
     def initialize(pointer)
       @tokens = parse(pointer)
-      @pointer = JSONPointer.encode(@tokens)
+      @pointer = Pointer.encode(@tokens)
     end
 
     # Resolve this pointer against JSON-like data _value_.
@@ -63,14 +65,14 @@ module JSONP3
     end
 
     # Return true if this pointer is relative to _pointer_.
-    # @param pointer [JSONPointer]
+    # @param pointer [Pointer]
     # @return [bool]
     def relative_to?(pointer)
       pointer.tokens.length < @tokens.length && @tokens[...pointer.tokens.length] == pointer.tokens
     end
 
     # @param parts [String]
-    # @return [JSONPointer]
+    # @return [Pointer]
     def join(*parts)
       pointer = self
       parts.each do |part|
@@ -91,14 +93,14 @@ module JSONP3
     def parent
       return self if @tokens.empty?
 
-      JSONPointer.new(JSONPointer.encode((@tokens[...-1] || raise)))
+      Pointer.new(Pointer.encode(@tokens[...-1] || raise))
     end
 
     # Return a new pointer relative to this pointer using Relative JSON Pointer syntax.
-    # @param rel [String | RelativeJSONPointer]
-    # @return [JSONPointer]
+    # @param rel [String | RelativePointer]
+    # @return [Pointer]
     def to(rel)
-      p = rel.is_a?(String) ? RelativeJSONPointer.new(rel) : rel
+      p = rel.is_a?(String) ? RelativePointer.new(rel) : rel
       p.to(self)
     end
 
@@ -112,7 +114,7 @@ module JSONP3
     # @return [Array<String | Integer>]
     def parse(pointer)
       if pointer.length.positive? && !pointer.start_with?("/")
-        raise JSONPointerSyntaxError,
+        raise JSONP3::Pointer::SyntaxError,
               "pointers must start with a slash or be the empty string"
       end
 
@@ -164,73 +166,10 @@ module JSONP3
     end
 
     def _join(other)
-      raise JSONPointerTypeError, "unsupported join part" unless other.is_a?(String)
+      raise JSONP3::Pointer::TypeError, "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
+      part.start_with?("/") ? Pointer.new(part) : Pointer.new(Pointer.encode(@tokens + _parse(part)))
     end
   end
 end

data/lib/json_p3/relative_pointer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module JSONP3
+  # A relative JSON Pointer.
+  # See https://datatracker.ietf.org/doc/html/draft-hha-relative-json-pointer
+  class RelativePointer
+    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 JSONP3::Pointer::SyntaxError, "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 JSONP3::Pointer::SyntaxError, "index offset can't be zero" if @index.zero?
+
+        @index = -@index if match[:SIGN] == "-"
+      end
+
+      @pointer = match[:POINTER] == "#" ? "#" : Pointer.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 | Pointer]
+    # @return [Pointer]
+    def to(pointer)
+      p = pointer.is_a?(String) ? Pointer.new(pointer) : pointer
+
+      if @origin > p.tokens.length
+        raise JSONP3::Pointer::IndexError,
+              "origin (#{@origin}) exceeds root (#{p.tokens.length})"
+      end
+
+      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
+
+      Pointer.new(Pointer.encode(tokens))
+    end
+
+    private
+
+    # @param token [String]
+    # @return [Integer]
+    def parse_int(token)
+      raise JSONP3::Pointer::SyntaxError, "unexpected leading zero" if token.start_with?("0") && token.length > 1
+      raise JSONP3::Pointer::SyntaxError, "expected an integer, found '#{token}'" unless RE_INT.match?(token)
+
+      token.to_i
+    end
+  end
+end

data/lib/json_p3/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JSONP3
-  VERSION = "0.4.0"
+  VERSION = "1.0.0"
 end

data/lib/json_p3.rb

@@ -1,43 +1,80 @@
 # frozen_string_literal: true
 
 require_relative "json_p3/version"
-require_relative "json_p3/environment"
+require_relative "json_p3/errors"
+require_relative "json_p3/cache"
+require_relative "json_p3/path/environment"
 require_relative "json_p3/pointer"
+require_relative "json_p3/relative_pointer"
 require_relative "json_p3/patch"
+require_relative "json_p3/patch/op"
+require_relative "json_p3/patch/op_add"
+require_relative "json_p3/patch/op_copy"
+require_relative "json_p3/patch/op_move"
+require_relative "json_p3/patch/op_remove"
+require_relative "json_p3/patch/op_replace"
+require_relative "json_p3/patch/op_test"
 
-# RFC 9535 JSONPath query expressions for JSON.
+# JSONPath, JSON Pointer and JSONPatch.
 module JSONP3
-  DefaultEnvironment = JSONPathEnvironment.new
+  # JSONPath query expressions.
+  module Path
+    DefaultEnvironment = JSONP3::Path::Environment.new
+
+    def self.find(path, data)
+      DefaultEnvironment.find(path, data)
+    end
+
+    def self.find_enum(path, data)
+      DefaultEnvironment.find_enum(path, data)
+    end
+
+    def self.compile(path)
+      DefaultEnvironment.compile(path)
+    end
+
+    def self.match(path, data)
+      DefaultEnvironment.match(path, data)
+    end
+
+    def self.match?(path, data)
+      DefaultEnvironment.match?(path, data)
+    end
+
+    def self.first(path, data)
+      DefaultEnvironment.first(path, data)
+    end
+  end
 
   def self.find(path, data)
-    DefaultEnvironment.find(path, data)
+    Path.find(path, data)
   end
 
   def self.find_enum(path, data)
-    DefaultEnvironment.find_enum(path, data)
+    Path.find_enum(path, data)
   end
 
   def self.compile(path)
-    DefaultEnvironment.compile(path)
+    Path.compile(path)
   end
 
   def self.match(path, data)
-    DefaultEnvironment.match(path, data)
+    Path.match(path, data)
   end
 
   def self.match?(path, data)
-    DefaultEnvironment.match?(path, data)
+    Path.match?(path, data)
   end
 
   def self.first(path, data)
-    DefaultEnvironment.first(path, data)
+    Path.first(path, data)
   end
 
-  def self.resolve(pointer, value, default: JSONPointer::UNDEFINED)
-    JSONPointer.new(pointer).resolve(value, default: default)
+  def self.resolve(pointer, value, default: Pointer::UNDEFINED)
+    Pointer.resolve(pointer, value, default: default)
   end
 
-  def self.apply(ops, value)
-    JSONPatch.new(ops).apply(value)
+  def self.apply!(ops, value)
+    Patch.apply!(ops, value)
   end
 end

data/sig/json_p3/cache.rbs

@@ -0,0 +1,21 @@
+module JSONP3
+  # A least recently used cache relying on Ruby hash insertion order.
+  class LRUCache
+    @data: Hash[untyped, untyped]
+
+    @max_size: Integer
+
+    attr_reader max_size: Integer
+
+    def initialize: (?::Integer max_size) -> void
+
+    # Return the cached value or nil if _key_ does not exist.
+    def []: (untyped key) -> (nil | untyped)
+
+    def []=: (untyped key, untyped value) -> untyped
+
+    def length: () -> Integer
+
+    def keys: () -> Array[untyped]
+  end
+end

data/sig/json_p3/errors.rbs

@@ -0,0 +1,55 @@
+module JSONP3
+  # The base class for all errors raised from this gem.
+  class Error < StandardError
+  end
+
+  module Path
+    class Error < JSONP3::Error
+      @token: t_token
+
+      @query: String
+
+      FULL_MESSAGE: bool
+
+      def initialize: (String msg, t_token token, String query) -> void
+
+      def detailed_message: (?highlight: bool, **untyped _kwargs) -> String
+
+      def full_message: (?highlight: bool, ?order: ::Symbol) -> (::String | untyped)
+    end
+
+    class SyntaxError < Error
+    end
+
+    class TypeError < Error
+    end
+
+    class NameError < Error
+    end
+
+    class RecursionError < Error
+    end
+  end
+
+  class Pointer
+    class Error < JSONP3::Error
+    end
+
+    class IndexError < Error
+    end
+
+    class SyntaxError < Error
+    end
+
+    class TypeError < Error
+    end
+  end
+
+  class Patch
+    class Error < JSONP3::Error
+    end
+
+    class TestFailure < Error
+    end
+  end
+end

data/sig/json_p3/patch.rbs

@@ -0,0 +1,145 @@
+module JSONP3
+  # A JSON Patch containing zero or more patch operations.
+  class Patch
+    @ops: Array[Op]
+
+    def self.apply!: (Array[Patch::Op | Hash[String, untyped]] ops, untyped value) -> untyped
+
+    # Base class for all JSON Patch operations
+    class Op
+      # Return the name of the patch operation.
+      def name: () -> String
+
+      # Apply the patch operation to _value_.
+      def apply!: (untyped _value, Integer _index) -> untyped
+
+      # Return a JSON-like representation of this patch operation.
+      def to_h: () -> untyped
+    end
+
+    # The JSON Patch _add_ operation.
+    class OpAdd < Op
+      @pointer: JSONP3::Pointer
+
+      @value: untyped
+
+      # @param pointer [JSONP3::Pointer]
+      # @param value [JSON-like value]
+      def initialize: (JSONP3::Pointer pointer, untyped value) -> void
+
+      def name: () -> "add"
+    end
+
+    # The JSON Patch _remove_ operation.
+    class OpRemove < Op
+      @pointer: JSONP3::Pointer
+
+      # @param pointer [JSONP3::Pointer]
+      def initialize: (JSONP3::Pointer pointer) -> void
+
+      def name: () -> "remove"
+    end
+
+    # The JSON Patch _replace_ operation.
+    class OpReplace < Op
+      @pointer: JSONP3::Pointer
+
+      @value: untyped
+
+      # @param pointer [JSONP3::Pointer]
+      # @param value [JSON-like value]
+      def initialize: (JSONP3::Pointer pointer, untyped value) -> void
+
+      def name: () -> "replace"
+    end
+
+    # The JSON Patch _move_ operation.
+    class OpMove < Op
+      @from: JSONP3::Pointer
+
+      @pointer: JSONP3::Pointer
+
+      # @param from [JSONP3::Pointer]
+      # @param pointer [JSONP3::Pointer]
+      def initialize: (JSONP3::Pointer from, JSONP3::Pointer pointer) -> void
+
+      def name: () -> "move"
+    end
+
+    # The JSON Patch _copy_ operation.
+    class OpCopy < Op
+      @from: JSONP3::Pointer
+
+      @pointer: JSONP3::Pointer
+
+      # @param from [JSONP3::Pointer]
+      # @param pointer [JSONP3::Pointer]
+      def initialize: (JSONP3::Pointer from, JSONP3::Pointer pointer) -> void
+
+      def name: () -> "copy"
+              
+      def deep_copy: (untyped obj) -> untyped
+    end
+
+    # The JSON Patch _test_ operation.
+    class OpTest < Op
+      @pointer: JSONP3::Pointer
+
+      @value: untyped
+
+      # @param pointer [JSONP3::Pointer]
+      # @param value [JSON-like value]
+      def initialize: (JSONP3::Pointer pointer, untyped value) -> void
+
+      def name: () -> "test"
+    end
+
+    # @param ops [Array<Op>?]
+    def initialize: (?Array[Op | Hash[String, untyped]]? ops) -> void
+
+    # @param pointer [String | JSONP3::Pointer]
+    # @param value [JSON-like value]
+    # @return [self]
+    def add: (JSONP3::Pointer | String pointer, untyped value) -> self
+
+    # @param pointer [String | JSONP3::Pointer]
+    # @return [self]
+    def remove: (JSONP3::Pointer | String pointer) -> self
+
+    # @param pointer [String | JSONP3::Pointer]
+    # @param value [JSON-like value]
+    # @return [self]
+    def replace: (JSONP3::Pointer | String pointer, untyped value) -> self
+
+    # @param from [String | JSONP3::Pointer]
+    # @param pointer [String | JSONP3::Pointer]
+    # @return [self]
+    def move: (JSONP3::Pointer | String from, JSONP3::Pointer | String pointer) -> self
+
+    # @param from [String | JSONP3::Pointer]
+    # @param pointer [String | JSONP3::Pointer]
+    # @return [self]
+    def copy: (JSONP3::Pointer | String from, JSONP3::Pointer | String pointer) -> self
+
+    # @param pointer [String | JSONP3::Pointer]
+    # @param value [JSON-like value]
+    # @return [self]
+    def test: (JSONP3::Pointer | String pointer, untyped value) -> self
+
+    # Apply this patch to JSON-like value _value_.
+    def apply!: (untyped value) -> untyped
+
+    def to_a: () -> Array[untyped]
+
+    private
+
+    def ensure_pointer: (JSONP3::Pointer | String pointer, Symbol op, Integer index) -> JSONP3::Pointer
+                      
+    def build: (Array[Op | Hash[String, untyped]]) -> void
+             
+    def op_pointer: (Hash[String, untyped] obj, String key, String op, Integer index) -> JSONP3::Pointer
+
+    def op_value: (Hash[String, untyped] obj, String key, String op, Integer index) -> untyped
+            
+  end
+end

data/sig/json_p3/path/environment.rbs

@@ -0,0 +1,81 @@
+module JSONP3
+  module Path
+    # JSONPath configuration
+    #
+    # Configure an environment by inheriting from `Environment` and setting one
+    # or more constants and/or overriding {setup_function_extensions}.
+    class Environment
+      @function_extensions: Hash[String, FunctionExtension]
+
+      # The maximum integer allowed when selecting array items by index.
+      MAX_INT_INDEX: Numeric
+
+      # The minimum integer allowed when selecting array items by index.
+      MIN_INT_INDEX: Numeric
+
+      # The maximum number of arrays and hashes the recursive descent segment will
+      # traverse before raising a {JSONPathRecursionError}.
+      MAX_RECURSION_DEPTH: Integer
+
+      # One of the available implementations of the _name selector_.
+      #
+      # - {NameSelector} (the default) will select values from hashes using string keys.
+      # - {SymbolNameSelector} will select values from hashes using string or symbol keys.
+      #
+      # Implement your own name selector by inheriting from {NameSelector} and overriding
+      # `#resolve`.
+      NAME_SELECTOR: untyped
+
+      # An implementation of the _index selector_. The default implementation will
+      # select values from arrays only. Implement your own by inheriting from
+      # {IndexSelector} and overriding `#resolve`.
+      INDEX_SELECTOR: untyped
+
+      attr_accessor function_extensions: Hash[String, FunctionExtension]
+
+      def initialize: () -> void
+
+      # Prepare JSONPath expression _query_ for repeated application.
+      # @param query [String]
+      # @return [Query]
+      def compile: (String query) -> Query
+
+      # Apply JSONPath expression _query_ to _value_.
+      # @param query [String] the JSONPath expression
+      # @param value [JSON-like data] the target JSON "document"
+      # @return [Array<JSONPath>]
+      def find: (String query, untyped value) -> JSONP3::Path::NodeList
+
+      # Apply JSONPath expression _query_ to _value_.
+      # @param query [String] the JSONPath expression
+      # @param value [JSON-like data] the target JSON "document"
+      # @return [Enumerable<Query>]
+      def find_enum: (String query, untyped value) -> Enumerable[JSONP3::Path::Node]
+
+      # Apply JSONPath expression _query_ to _value_ an return the first
+      # available node.
+      # @param query [String] the JSONPath expression
+      # @param value [JSON-like data] the target JSON "document"
+      # @return [Node | nil]
+      def match: (String path, untyped value) -> (JSONP3::Path::Node | nil)
+
+      # Apply JSONPath expression _query_ to _value_ an return `true` if there's at
+      # least one node, or nil if there were no matches.
+      # @param query [String] the JSONPath expression
+      # @param value [JSON-like data] the target JSON "document"
+      # @return [bool]
+      def match?: (String path, untyped value) -> bool
+
+      # Apply JSONPath expression _query_ to _value_ an return the first
+      # available node, or nil if there were no matches.
+      # @param query [String] the JSONPath expression
+      # @param value [JSON-like data] the target JSON "document"
+      # @return [Node | nil]
+      def first: (untyped path, untyped value) -> (JSONP3::Path::Node | nil)
+
+      # Override this function to configure JSONPath function extensions.
+      # By default, only the standard functions described in RFC 9535 are enabled.
+      def setup_function_extensions: () -> untyped
+    end
+  end
+end