json_p3 0.4.0 → 1.0.0

data/lib/json_p3/path/query.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "node"
+
+module JSONP3
+  module Path
+    # A compiled JSONPath expression ready to be applied to JSON-like values.
+    class Query
+      def initialize(env, segments)
+        @env = env
+        @segments = segments
+      end
+
+      def to_s
+        "$#{@segments.join}"
+      end
+
+      # Apply this JSONPath expression to JSON-like value _root_.
+      # @param root [Array, Hash, String, Integer, nil] the root JSON-like value to apply this query to.
+      # @return [Array<Node>] the sequence of nodes found while applying this query to _root_.
+      def find(root)
+        nodes = [Node.new(root, [], root)]
+        @segments.each { |segment| nodes = segment.resolve(nodes) }
+        NodeList.new(nodes)
+      end
+
+      alias apply find
+
+      # Apply this JSONPath expression to JSON-like value _root_.
+      # @param root [Array, Hash, String, Integer, nil] the root JSON-like value to apply this query to.
+      # @return [Enumerable<Node>] the sequence of nodes found while applying this query to _root_.
+      def find_enum(root)
+        nodes = [Node.new(root, [], root)] # : Enumerable[Node]
+        @segments.each { |segment| nodes = segment.resolve_enum(nodes) }
+        nodes
+      end
+
+      # Return the first node from applying this JSONPath expression to JSON-like value _root_.
+      # @param root [Array, Hash, String, Integer, nil] the root JSON-like value to apply this query to.
+      # @return [Node | nil] the first available node or nil if there were no matches.
+      def match(root)
+        find_enum(root).first
+      end
+
+      # Return `true` if this query results in at least one node, or `false` otherwise.
+      # @param root [Array, Hash, String, Integer, nil] the root JSON-like value to apply this query to.
+      # @return [bool] `true` if this query results in at least one node, or `false` otherwise.
+      def match?(root)
+        !find_enum(root).first.nil?
+      end
+
+      # Return the first node from applying this JSONPath expression to JSON-like value _root_.
+      # @param root [Array, Hash, String, Integer, nil] the root JSON-like value to apply this query to.
+      # @return [Node | nil] the first available node or nil if there were no matches.
+      def first(root)
+        find_enum(root).first
+      end
+
+      # Return _true_ if this JSONPath expression is a singular query.
+      def singular?
+        @segments.each do |segment|
+          return false if segment.instance_of? DescendantSegment
+          return false unless segment.selectors.length == 1 && segment.selectors[0].singular?
+        end
+        true
+      end
+
+      # Return _true_ if this JSONPath expression has no segments.
+      def empty?
+        @segments.empty?
+      end
+    end
+  end
+end

data/lib/json_p3/path/segment.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module JSONP3
+  module Path
+    # Base class for all JSONPath segments.
+    class Segment
+      # @dynamic token, selectors
+      attr_reader :token, :selectors
+
+      def initialize(env, token, selectors)
+        @env = env
+        @token = token
+        @selectors = selectors
+      end
+
+      # Select the children of each node in _nodes_.
+      # @return [Array<Node>]
+      def resolve(_nodes)
+        raise "segments must implement resolve(nodes)"
+      end
+
+      # Select the children of each node in _nodes_.
+      # @return [Enumerable<Node>]
+      def resolve_enum(_nodes)
+        raise "segments must implement resolve_enum(nodes)"
+      end
+    end
+
+    # The child selection segment.
+    class ChildSegment < Segment
+      def resolve(nodes)
+        rv = [] # : Array[Node]
+        nodes.each do |node|
+          @selectors.each do |selector|
+            rv.concat selector.resolve(node)
+          end
+        end
+        rv
+      end
+
+      def resolve_enum(nodes)
+        Enumerator.new do |yielder|
+          nodes.each do |node|
+            @selectors.each do |selector|
+              selector.resolve(node).each do |item|
+                yielder << item
+              end
+            end
+          end
+        end
+      end
+
+      def to_s
+        "[#{@selectors.join(", ")}]"
+      end
+
+      def ==(other)
+        self.class == other.class &&
+          @selectors == other.selectors &&
+          @token == other.token
+      end
+
+      alias eql? ==
+
+      def hash
+        [@selectors, @token].hash
+      end
+    end
+
+    # The descendant segment
+    class DescendantSegment < Segment
+      def resolve(nodes)
+        rv = [] #: Array[Node]
+        nodes.each do |node|
+          visit(node).each do |descendant|
+            @selectors.each do |selector|
+              rv.concat selector.resolve(descendant)
+            end
+          end
+        end
+        rv
+      end
+
+      def resolve_enum(nodes)
+        Enumerator.new do |yielder|
+          nodes.each do |node|
+            visit_enum(node).each do |descendant|
+              @selectors.each do |selector|
+                selector.resolve(descendant).each do |item|
+                  yielder << item
+                end
+              end
+            end
+          end
+        end
+      end
+
+      def to_s
+        "..[#{@selectors.join(", ")}]"
+      end
+
+      def ==(other)
+        self.class == other.class &&
+          @selectors == other.selectors &&
+          @token == other.token
+      end
+
+      alias eql? ==
+
+      def hash
+        ["..", @selectors, @token].hash
+      end
+
+      protected
+
+      def visit(node, depth = 1)
+        if depth > @env.class::MAX_RECURSION_DEPTH
+          raise JSONP3::Path::RecursionError.new(
+            "recursion limit exceeded",
+            @token,
+            ""
+          )
+        end
+
+        rv = [node]
+
+        if node.value.is_a? Array
+          node.value.each_with_index do |value, i|
+            child = Node.new(value, [node.location, i], node.root)
+            rv.concat visit(child, depth + 1)
+          end
+        elsif node.value.is_a? Hash
+          node.value.each do |key, value|
+            child = Node.new(value, [node.location, key], node.root)
+            rv.concat visit(child, depth + 1)
+          end
+        end
+
+        rv
+      end
+
+      def visit_enum(node, depth = 1)
+        if depth > @env.class::MAX_RECURSION_DEPTH
+          raise JSONP3::Path::RecursionError.new(
+            "recursion limit exceeded",
+            @token,
+            ""
+          )
+        end
+
+        Enumerator.new do |yielder|
+          yielder << node
+          if node.value.is_a? Array
+            node.value.each_with_index do |value, i|
+              child = Node.new(value, [node.location, i], node.root)
+              visit_enum(child, depth + 1).each do |item|
+                yielder << item
+              end
+            end
+          elsif node.value.is_a? Hash
+            node.value.each do |key, value|
+              child = Node.new(value, [node.location, key], node.root)
+              visit_enum(child, depth + 1).each do |item|
+                yielder << item
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/json_p3/path/selector.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+module JSONP3
+  module Path
+    # Base class for all JSONPath selectors
+    class Selector
+      attr_reader :token
+
+      def initialize(env, token)
+        @env = env
+        @token = token
+      end
+
+      # Apply this selector to _node_.
+      # @return [Array<Node>]
+      def resolve(_node)
+        raise "selectors must implement resolve(node)"
+      end
+
+      # Apply this selector to _node_.
+      # @return [Enumerable<Node>]
+      def resolve_enum(node)
+        resolve(node)
+      end
+
+      # Return true if this selector is a singular selector.
+      def singular?
+        false
+      end
+    end
+
+    # The name selector select values from hashes given a key.
+    class NameSelector < Selector
+      attr_reader :name
+
+      def initialize(env, token, name)
+        super(env, token)
+        @name = name
+      end
+
+      def resolve(node)
+        if node.value.is_a?(Hash) && node.value.key?(@name)
+          [node.new_child(node.value[@name], @name)]
+        else
+          []
+        end
+      end
+
+      def singular?
+        true
+      end
+
+      def to_s
+        JSONP3::Path.canonical_string(@name)
+      end
+
+      def ==(other)
+        self.class == other.class &&
+          @name == other.name &&
+          @token == other.token
+      end
+
+      alias eql? ==
+
+      def hash
+        [@name, @token].hash
+      end
+    end
+
+    # This non-standard name selector selects values from hashes given a string or
+    # symbol key.
+    class SymbolNameSelector < NameSelector
+      def initialize(env, token, name)
+        super
+        @sym = @name.to_sym
+      end
+
+      def resolve(node)
+        if node.value.is_a?(Hash)
+          if node.value.key?(@name)
+            [node.new_child(node.value[@name], @name)]
+          elsif node.value.key?(@sym)
+            [node.new_child(node.value[@sym], @name)]
+          else
+            []
+          end
+        else
+          []
+        end
+      end
+    end
+
+    # The index selector selects values from arrays given an index.
+    class IndexSelector < Selector
+      attr_reader :index
+
+      def initialize(env, token, index)
+        super(env, token)
+        @index = index
+      end
+
+      def resolve(node)
+        if node.value.is_a?(Array)
+          norm_index = normalize(@index, node.value.length)
+          return [] if norm_index.negative? || norm_index >= node.value.length
+
+          [node.new_child(node.value[@index], norm_index)]
+        else
+          []
+        end
+      end
+
+      def singular?
+        true
+      end
+
+      def to_s
+        @index.to_s
+      end
+
+      def ==(other)
+        self.class == other.class &&
+          @index == other.index &&
+          @token == other.token
+      end
+
+      alias eql? ==
+
+      def hash
+        [@index, @token].hash
+      end
+
+      private
+
+      def normalize(index, length)
+        index.negative? && length >= index.abs ? length + index : index
+      end
+    end
+
+    # The wildcard selector selects all elements from an array or values from a hash.
+    class WildcardSelector < Selector
+      def resolve(node)
+        if node.value.is_a? Hash
+          node.value.map { |k, v| node.new_child(v, k) }
+        elsif node.value.is_a? Array
+          node.value.map.with_index { |e, i| node.new_child(e, i) }
+        else
+          []
+        end
+      end
+
+      def resolve_enum(node)
+        if node.value.is_a? Hash
+          Enumerator.new do |yielder|
+            node.value.each do |k, v|
+              yielder << node.new_child(v, k)
+            end
+          end
+        elsif node.value.is_a? Array
+          Enumerator.new do |yielder|
+            node.value.each.with_index do |e, i|
+              yielder << node.new_child(e, i)
+            end
+          end
+        else
+          []
+        end
+      end
+
+      def to_s
+        "*"
+      end
+
+      def ==(other)
+        self.class == other.class && @token == other.token
+      end
+
+      alias eql? ==
+
+      def hash
+        @token.hash
+      end
+    end
+
+    # The slice selector selects a range of elements from an array.
+    class SliceSelector < Selector
+      attr_reader :start, :stop, :step
+
+      def initialize(env, token, start, stop, step)
+        super(env, token)
+        @start = start
+        @stop = stop
+        @step = step || 1
+      end
+
+      def resolve(node)
+        return [] unless node.value.is_a?(Array)
+
+        length = node.value.length
+        return [] if length.zero? || @step.zero?
+
+        normalized_start = if @start.nil?
+                             @step.negative? ? length - 1 : 0
+                           elsif @start&.negative?
+                             [length + (@start || raise), 0].max
+                           else
+                             [@start || raise, length - 1].min
+                           end
+
+        normalized_stop = if @stop.nil?
+                            @step.negative? ? -1 : length
+                          elsif @stop&.negative?
+                            [length + (@stop || raise), -1].max
+                          else
+                            [@stop || raise, length].min
+                          end
+
+        (normalized_start...normalized_stop).step(@step).map { |i| node.new_child(node.value[i], i) }
+      end
+
+      def to_s
+        start = @start || ""
+        stop = @stop || ""
+        step = @step || 1
+        "#{start}:#{stop}:#{step}"
+      end
+
+      def ==(other)
+        self.class == other.class &&
+          @start == other.start &&
+          @stop == other.stop &&
+          @step == other.step &&
+          @token == other.token
+      end
+
+      alias eql? ==
+
+      def hash
+        [@start, @stop, @step, @token].hash
+      end
+    end
+
+    # Select array elements or hash values according to a filter expression.
+    class FilterSelector < Selector
+      attr_reader :expression
+
+      def initialize(env, token, expression)
+        super(env, token)
+        @expression = expression
+      end
+
+      def resolve(node)
+        # @type var nodes: Array[Node]
+        nodes = []
+
+        if node.value.is_a?(Array)
+          node.value.each_with_index do |e, i|
+            context = FilterContext.new(@env, e, node.root)
+            nodes << node.new_child(e, i) if @expression.evaluate(context)
+          end
+        elsif node.value.is_a?(Hash)
+          node.value.each_pair do |k, v|
+            context = FilterContext.new(@env, v, node.root)
+            nodes << node.new_child(v, k) if @expression.evaluate(context)
+          end
+        end
+
+        nodes
+      end
+
+      def resolve_enum(node)
+        Enumerator.new do |yielder|
+          if node.value.is_a?(Array)
+            node.value.each_with_index do |e, i|
+              context = FilterContext.new(@env, e, node.root)
+              yielder << node.new_child(e, i) if @expression.evaluate(context)
+            end
+          elsif node.value.is_a?(Hash)
+            node.value.each_pair do |k, v|
+              context = FilterContext.new(@env, v, node.root)
+              yielder << node.new_child(v, k) if @expression.evaluate(context)
+            end
+          end
+        end
+      end
+
+      def to_s
+        "?#{@expression}"
+      end
+
+      def ==(other)
+        self.class == other.class &&
+          @expression == other.start &&
+          @token == other.token
+      end
+
+      alias eql? ==
+
+      def hash
+        [@expression, @token].hash
+      end
+    end
+  end
+end

data/lib/json_p3/path/serialize.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "json"
+
+module JSONP3
+  # JSONPath query expressions.
+  module Path
+    TRANS = { "\\\"" => "\"", "'" => "\\'" }.freeze
+
+    # Return _value_ formatted as a canonical string literal.
+    # @param value [String]
+    def self.canonical_string(value)
+      "'#{(JSON.dump(value)[1..-2] || raise).gsub(/('|\\")/, TRANS)}'"
+    end
+  end
+end

data/lib/json_p3/path/unescape.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module JSONP3
+  # JSONPath query expressions.
+  module Path
+    RE_SLASH_U = /\\u([0-9a-fA-F]{4})/
+
+    # Replace escape sequences with their equivalent Unicode code point.
+    def self.unescape(value, token, query)
+      unescaped = String.new(encoding: "UTF-8")
+      scanner = StringScanner.new(value)
+
+      until scanner.eos?
+        if scanner.scan(RE_SLASH_U)
+          code_point = (scanner.captures&.first || raise).to_i(16)
+
+          if low_surrogate?(code_point)
+            raise JSONP3::Path::SyntaxError.new(
+              "unexpected low surrogate",
+              token,
+              query
+            )
+          end
+
+          if high_surrogate?(code_point)
+            unless scanner.scan(RE_SLASH_U)
+              raise JSONP3::Path::SyntaxError.new(
+                "expected a low surrogate",
+                token,
+                query
+              )
+            end
+
+            low_surrogate = (scanner.captures&.first || raise).to_i(16)
+
+            unless low_surrogate?(low_surrogate)
+              raise JSONP3::Path::SyntaxError.new(
+                "expected a low surrogate",
+                token,
+                query
+              )
+            end
+
+            code_point = 0x10000 + (
+              ((code_point & 0x03FF) << 10) | (low_surrogate & 0x03FF)
+            )
+          end
+
+          if code_point <= 0x1f
+            raise JSONP3::Path::SyntaxError.new(
+              "invalid character #{code_point}",
+              token,
+              query
+            )
+          end
+
+          unescaped << code_point.chr(Encoding::UTF_8)
+          next
+        end
+
+        ch = scanner.getch
+
+        break if ch.nil?
+
+        unless ch == "\\"
+          if ch.ord <= 0x1f
+            raise JSONP3::Path::SyntaxError.new(
+              "invalid character #{ch.ord}",
+              token,
+              query
+            )
+          end
+          unescaped << ch
+          next
+        end
+
+        ch = scanner.getch
+
+        case ch
+        when "\""
+          if token.first == :token_single_quoted_esc_string
+            raise JSONP3::Path::SyntaxError.new(
+              "unexpected \\\" escape in single quoted string",
+              token,
+              query
+            )
+          end
+          unescaped << "\""
+        when "'"
+          if token.first == :token_double_quoted_esc_string
+            raise JSONP3::Path::SyntaxError.new(
+              "unexpected \\' escape in double quoted string",
+              token,
+              query
+            )
+          end
+          unescaped << "'"
+        when "\\"
+          unescaped << "\\"
+        when "/"
+          unescaped << "/"
+        when "b"
+          unescaped << "\x08"
+        when "f"
+          unescaped << "\x0c"
+        when "n"
+          unescaped << "\n"
+        when "r"
+          unescaped << "\r"
+        when "t"
+          unescaped << "\t"
+        when "u"
+          raise JSONP3::Path::SyntaxError.new("unexpected \\u escape sequence", token, query)
+        when nil
+          raise JSONP3::Path::SyntaxError.new("incomplete escape sequence", token, query)
+        else
+          raise JSONP3::Path::SyntaxError.new("unknown escape sequence", token, query)
+        end
+      end
+
+      unescaped
+    end
+
+    def self.high_surrogate?(code_point)
+      code_point.between?(0xD800, 0xDBFF)
+    end
+
+    def self.low_surrogate?(code_point)
+      code_point.between?(0xDC00, 0xDFFF)
+    end
+  end
+end