jmespath-ruby 0.1.0

data/lib/jmespath/functions/signature.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module JMESPath
+  class Functions
+    # @api private
+    class Signature
+      TYPES = %i[any null boolean number string array object expref array_number array_string].freeze
+
+      # Identifies the invocation that created a validation failure.
+      module FailureOrigin
+        attr_reader :origin
+
+        def initialize(message = nil, origin: nil)
+          @origin = origin
+          super(message)
+        end
+      end
+
+      # An error raised by the library's argument validator.
+      class TypeMismatch < Errors::InvalidTypeError
+        include FailureOrigin
+      end
+
+      # An error raised by the library's arity validator.
+      class ArityMismatch < Errors::InvalidArityError
+        include FailureOrigin
+      end
+
+      def initialize(arguments, variadic: false)
+        raise ArgumentError, "Invalid function signature" unless valid_definition?(arguments)
+        raise ArgumentError, "Variadic signatures require an argument" if variadic && arguments.empty?
+
+        @arguments = arguments.map { |types| types.dup.freeze }.freeze
+        @variadic = variadic
+        freeze
+      end
+
+      def validate!(values, name, origin: nil)
+        unless valid_arity?(values.length)
+          raise ArityMismatch.new("Invalid number of arguments for #{name}", origin: origin)
+        end
+
+        values.each_with_index do |value, index|
+          types = @arguments.fetch(index) { @arguments.fetch(-1) }
+          next if types.any? { |type| matches?(value, type) }
+
+          raise TypeMismatch.new("Invalid argument #{index + 1} for #{name}: #{Types.name(value)}", origin: origin)
+        end
+      end
+
+      private
+
+      def valid_definition?(arguments)
+        arguments.is_a?(Array) && arguments.all? do |types|
+          types.is_a?(Array) && !types.empty? && (types - TYPES).empty?
+        end
+      end
+
+      def valid_arity?(count)
+        @variadic ? count >= @arguments.length : count == @arguments.length
+      end
+
+      def matches?(value, type)
+        return true if type == :any
+        return array_matches?(value, :number) if type == :array_number
+        return array_matches?(value, :string) if type == :array_string
+
+        Types.name(value) == type
+      end
+
+      def array_matches?(value, type)
+        array = DataAccess.array(value)
+        array&.all? { |item| Types.name(item) == type }
+      end
+    end
+  end
+end

data/lib/jmespath/functions.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module JMESPath
+  # Immutable definitions for functions available to an expression.
+  class Functions
+    # @api private
+    Definition = Data.define(:signature, :implementation)
+
+    # Create an empty immutable function registry.
+    def initialize
+      # @type var definitions: Hash[String, Definition]
+      definitions = {}
+      @definitions = definitions.freeze
+      freeze
+    end
+
+    # Return an independent registry with one additional definition.
+    # @param name [String] unquoted function identifier
+    # @param signature [Array<Array<Symbol>>] accepted types for each argument
+    # @param variadic [Boolean] repeat the final argument type
+    # @param override [Boolean] explicitly replace a definition
+    # @yieldparam arguments [Object] evaluated arguments
+    # @yieldreturn [Object] the function result
+    # @raise [ArgumentError] the definition is invalid or duplicates an existing name
+    # @return [Functions] the extended registry
+    def with(name, signature:, variadic: false, override: false, &block)
+      raise ArgumentError, "A function block is required" unless block
+
+      definition = Definition.new(Signature.new(signature, variadic: variadic), block)
+      add(name, definition, override: override)
+    end
+
+    # @api private
+    def with_builtin(name, signature:, handler:, variadic: false)
+      definition = Definition.new(Signature.new(signature, variadic: variadic), handler)
+      add(name, definition, override: false)
+    end
+
+    # Evaluate a registered function with checked arguments.
+    # @param name [String] function identifier
+    # @param arguments [Array<Object>] evaluated values
+    # @param disable_visit_errors [Boolean] return nil for validation failures
+    # @return [Object] the callback result
+    # @raise [Errors::UnknownFunctionError] the name is absent
+    # @raise [Errors::InvalidTypeError] argument types are incompatible
+    # @raise [Errors::InvalidArityError] the number of arguments is invalid
+    def call(name, arguments, disable_visit_errors: false)
+      definition = @definitions.fetch(name) { raise Errors::UnknownFunctionError, "Unknown function: #{name}" }
+      invocation = disable_visit_errors ? FunctionCall.new : FunctionCall::STRICT
+      invocation.call(definition, name, arguments, disable_visit_errors: disable_visit_errors)
+    end
+
+    # @api private
+    def definition(name)
+      @definitions[name]
+    end
+
+    private
+
+    def add(name, definition, override:)
+      unless name.is_a?(String) && name.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+        raise ArgumentError, "Invalid function name"
+      end
+      raise ArgumentError, "Function #{name} is already registered" if @definitions.key?(name) && !override
+
+      result = dup
+      result.instance_variable_set(:@definitions, @definitions.merge(name.dup.freeze => definition).freeze)
+      result.freeze
+    end
+  end
+end
+
+require_relative "functions/signature"

data/lib/jmespath/input.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "stringio"
+
+module JMESPath
+  # @api private
+  module Input
+    def self.load(data)
+      return data if data.is_a?(Hash) || data.is_a?(Array) || data.is_a?(Struct)
+
+      case data
+      when Pathname then File.open(data, "r", encoding: "UTF-8") { |file| JSON.parse(file.read) }
+      when IO, StringIO then JSON.parse(data.read.to_s)
+      else data
+      end
+    end
+  end
+end

data/lib/jmespath/lexer.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "json"
+
+module JMESPath
+  # @api private
+  class Lexer
+    SINGLE = {
+      "[" => :lbracket, "]" => :rbracket, "{" => :lbrace, "}" => :rbrace,
+      "(" => :lparen, ")" => :rparen, "," => :comma, ":" => :colon,
+      "." => :dot, "*" => :star, "@" => :current, "&" => :expref,
+      "|" => :pipe, "!" => :not, "<" => :lt, ">" => :gt
+    }.freeze
+    DOUBLE = {
+      "[]" => :flatten, "[?" => :filter, "&&" => :and, "||" => :or,
+      "==" => :eq, "!=" => :ne, "<=" => :lte, ">=" => :gte
+    }.freeze
+    WHITESPACE = [9, 10, 13, 32].freeze
+
+    attr_reader :source
+
+    def initialize(source, max_depth: 128)
+      @source = source.encode(Encoding::UTF_8).freeze
+      raise Encoding::InvalidByteSequenceError unless @source.valid_encoding?
+
+      @index = 0
+      @max_depth = max_depth
+    rescue EncodingError
+      raise Errors::SyntaxError, "Expression has invalid encoding"
+    end
+
+    def tokens
+      # @type var result: Array[Token?]
+      result = []
+      result << next_token while @index < source.bytesize
+      result << Token.new(:eof, nil, @index, @index)
+      result.compact.freeze
+    end
+
+    private
+
+    def next_token
+      start = @index
+      byte = source.getbyte(@index)
+      return skip_whitespace if WHITESPACE.include?(byte)
+      return quoted_token(start, byte) if [34, 39, 96].include?(byte)
+      return word_token(start) if identifier_start?(byte)
+      return number_token(start) if byte == 45 || digit?(byte)
+
+      operator_token(start)
+    end
+
+    def skip_whitespace
+      @index += 1 while WHITESPACE.include?(source.getbyte(@index))
+      nil
+    end
+
+    def word_token(start)
+      @index += 1 while identifier_part?(source.getbyte(@index))
+      Token.new(:identifier, source.byteslice(start...@index), start, @index)
+    end
+
+    def number_token(start)
+      @index += 1 if source.getbyte(@index) == 45
+      syntax!("Expected a digit", start) unless digit?(source.getbyte(@index))
+      @index += 1 while digit?(source.getbyte(@index))
+      Token.new(:number, source.byteslice(start...@index).to_i, start, @index)
+    end
+
+    def operator_token(start)
+      pair = source.byteslice(start, 2)
+      type = DOUBLE[pair]
+      length = type ? 2 : 1
+      type ||= SINGLE[source.byteslice(start, 1)]
+      syntax!("Unexpected character", start) unless type
+      @index += length
+      Token.new(type, nil, start, @index)
+    end
+
+    def quoted_token(start, quote)
+      @index += 1
+      content_start = @index
+      scan_quote(quote, start)
+      content = source.byteslice(content_start...@index).to_s
+      @index += 1
+      value = decode(content, quote)
+      Token.new(quote == 34 ? :identifier : :literal, value, start, @index)
+    rescue JSON::ParserError => e
+      syntax!("Invalid quoted value: #{e.message}", start)
+    end
+
+    def scan_quote(quote, start)
+      while @index < source.bytesize
+        return if source.getbyte(@index) == quote
+
+        @index += source.getbyte(@index) == 92 ? 2 : 1
+      end
+      syntax!("Unterminated quoted value", start)
+    end
+
+    def decode(content, quote)
+      return JSON.parse("\"#{content}\"") if quote == 34
+      return content.gsub("\\'", "'") if quote == 39
+
+      literal(content.gsub("\\#{96.chr}", 96.chr))
+    end
+
+    def literal(content)
+      JSON.parse(content, max_nesting: @max_depth)
+    rescue JSON::NestingError
+      raise
+    rescue JSON::ParserError
+      JSON.parse("\"#{content.lstrip}\"", max_nesting: @max_depth)
+    end
+
+    def identifier_start?(byte)
+      byte && (byte.between?(65, 90) || byte.between?(97, 122) || byte == 95)
+    end
+
+    def identifier_part?(byte)
+      identifier_start?(byte) || digit?(byte)
+    end
+
+    def digit?(byte)
+      byte&.between?(48, 57)
+    end
+
+    def syntax!(message, position)
+      raise Errors::SyntaxError.new(message, expression: source, position: position)
+    end
+  end
+end

data/lib/jmespath/normalizer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module JMESPath
+  # @api private
+  class Normalizer
+    def initialize
+      @pending = []
+      @active = {}
+    end
+
+    def call(value)
+      # @type var result: Array[value]
+      result = [nil]
+      enqueue(value) { |entry| result[0] = entry }
+      while (operation = @pending.pop)
+        operation.call
+      end
+      result.first
+    end
+
+    private
+
+    def enqueue(value, &assign)
+      @pending << -> { visit(value, &assign) }
+    end
+
+    def visit(value, &assign)
+      collection = DataAccess.array(value) || DataAccess.object(value)
+      return assign.call(DataAccess.string(value) || value) unless collection
+
+      id = value.object_id
+      raise Errors::InvalidValueError, "Cyclic values cannot be compared or serialized" if @active[id]
+
+      @active[id] = true
+      @pending << -> { @active.delete(id) }
+      collection.is_a?(Array) ? array(collection, &assign) : object(collection, &assign)
+    end
+
+    def array(values)
+      # @type var result: Array[value]
+      result = Array.new(values.length)
+      yield result
+      (values.length - 1).downto(0) { |index| enqueue(values[index]) { |entry| result[index] = entry } }
+    end
+
+    def object(values)
+      # @type var result: Hash[value, value]
+      result = values.transform_values { nil }
+      yield result
+      values.to_a.reverse_each { |key, value| enqueue(value) { |entry| result[key] = entry } }
+    end
+  end
+end

data/lib/jmespath/options.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module JMESPath
+  # @api private
+  class Options
+    # rubocop:disable-next Style/RedundantParentheses -- Type the empty hash before freezing it.
+    EMPTY = (
+      {} # : Hash[Symbol, value]
+    ).freeze
+    KEYS = %i[cache_expressions disable_visit_errors functions max_depth].freeze
+    attr_reader :cache_expressions, :disable_visit_errors, :functions, :max_depth
+
+    def initialize(positional = {}, keywords = {}, default_depth: 128, defaults: nil)
+      values = merge(positional, keywords)
+      @cache_expressions = boolean(values.fetch(:cache_expressions, true))
+      @disable_visit_errors = boolean(values.fetch(:disable_visit_errors) do
+        default_value(defaults, :disable_visit_errors)
+      end)
+      @max_depth = depth(values.fetch(:max_depth, default_depth))
+      @functions = registry(values.fetch(:functions) { default_value(defaults, :functions) })
+      freeze
+    end
+
+    private
+
+    def default_value(defaults, name)
+      return defaults.public_send(name) if defaults
+
+      name == :functions ? Functions.default : false
+    end
+
+    def merge(positional, keywords)
+      raise ArgumentError, "Options must be a Hash" unless positional.is_a?(Hash)
+
+      keywords.each_key do |key|
+        raise ArgumentError, "Conflicting option: #{key}" if positional.key?(key) && positional[key] != keywords[key]
+      end
+      values = positional.merge(keywords)
+      raise ArgumentError, "Unknown search options" unless (values.keys - KEYS).empty?
+
+      values
+    end
+
+    def boolean(value)
+      case value
+      when TrueClass, FalseClass then value
+      else raise ArgumentError, "Expected a boolean option"
+      end
+    end
+
+    def depth(value)
+      unless value.is_a?(Integer) && (1..128).cover?(value)
+        raise ArgumentError, "max_depth must be an integer from 1 through 128"
+      end
+
+      value
+    end
+
+    def registry(value)
+      raise ArgumentError, "functions must be a Functions registry" unless value.is_a?(Functions)
+
+      value
+    end
+  end
+
+  Options::DEFAULT = Options.new
+end

data/lib/jmespath/parser/expressions.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module JMESPath
+  # @api private
+  class Parser
+    private
+
+    def prefix_identifier(token)
+      node(:field, token.value, [], start: token.start)
+    end
+
+    def prefix_literal(token)
+      node(:literal, token.value, [], start: token.start)
+    end
+
+    def prefix_current(token)
+      node(:current, nil, [], start: token.start)
+    end
+
+    def prefix_group(token)
+      inner = expression
+      expect(:rparen)
+      node(:group, nil, [inner], start: token.start)
+    end
+
+    def prefix_not(token)
+      node(:not, nil, [expression(45)], start: token.start)
+    end
+
+    def prefix_reference(token)
+      node(:expression_reference, nil, [expression], start: token.start)
+    end
+
+    def prefix_hash(token)
+      pairs = separated(:rbrace) do
+        key = expect(:identifier)
+        expect(:colon)
+        node(:pair, key.value, [expression], start: key.start)
+      end
+      node(:multi_select_hash, nil, pairs, start: token.start)
+    end
+
+    def multi_select_list(token)
+      items = separated(:rbracket) { expression }
+      node(:multi_select_list, nil, items, start: token.start)
+    end
+
+    def infix_function(left, token)
+      unless left.kind == :field && @source.getbyte(left.start) != 34
+        syntax!("Function name must be an unquoted identifier", token)
+      end
+      arguments = separated(:rparen, empty: true) { expression }
+      node(:function, left.value, arguments, start: left.start)
+    end
+
+    def infix_dot(left, _token)
+      return node(:value_projection, nil, [left, projection_rhs(20)]) if peek.type == :star && advance
+
+      sequence(:subexpression, left, dot_rhs(40))
+    end
+
+    def dot_rhs(power)
+      return multi_select_list(advance) if peek.type == :lbracket
+
+      syntax!("Expected a field, function, or multiselect after dot") unless %i[identifier lbrace
+                                                                                star].include?(peek.type)
+      expression(power)
+    end
+  end
+end

data/lib/jmespath/parser/projections.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module JMESPath
+  # @api private
+  class Parser
+    private
+
+    def prefix_bracket(token)
+      if %i[number colon].include?(peek.type) || (peek.type == :star && @tokens.fetch(@index + 1).type == :rbracket)
+        return bracket_body(node(:current))
+      end
+
+      multi_select_list(token)
+    end
+
+    def infix_bracket(left, _token)
+      bracket_body(left)
+    end
+
+    def bracket_body(left)
+      if peek.type == :star
+        advance
+        expect(:rbracket)
+        return node(:projection, nil, [left, projection_rhs(20)])
+      end
+      index_or_slice(left)
+    end
+
+    def index_or_slice(left)
+      start = integer if peek.type == :number
+      return slice(left, start) if peek.type == :colon
+
+      syntax!("Expected an array index") unless start
+      expect(:rbracket)
+      node(:index, start, [left])
+    end
+
+    def slice(left, start)
+      advance
+      stop = integer if peek.type == :number
+      step = slice_step
+      expect(:rbracket)
+      raise Errors::InvalidValueError, "Slice step cannot be zero" if step&.zero?
+
+      base = node(:slice, [start, stop, step], [left])
+      node(:projection, nil, [base, projection_rhs(20)])
+    end
+
+    def slice_step
+      return nil unless peek.type == :colon
+
+      advance
+      integer if peek.type == :number
+    end
+
+    def integer
+      advance.value.to_s.to_i
+    end
+
+    def prefix_star(_token)
+      node(:value_projection, nil, [node(:current), projection_rhs(20)])
+    end
+
+    def prefix_flatten(token)
+      infix_flatten(node(:current), token)
+    end
+
+    def infix_flatten(left, _token)
+      base = node(:flatten, nil, [left])
+      node(:projection, nil, [base, projection_rhs(9)])
+    end
+
+    def prefix_filter(token)
+      infix_filter(node(:current), token)
+    end
+
+    def infix_filter(left, _token)
+      condition = expression
+      expect(:rbracket)
+      node(:filter_projection, nil, [left, projection_rhs(21), condition])
+    end
+
+    def projection_rhs(power)
+      return node(:current) if POWER.fetch(peek.type, 0) < 10
+      return expression(power) if %i[lbracket filter].include?(peek.type)
+      return dot_rhs(power) if peek.type == :dot && advance
+
+      syntax!("Invalid projection")
+    end
+  end
+end

data/lib/jmespath/parser.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module JMESPath
+  # @api private
+  class Parser
+    POWER = {
+      pipe: 1, or: 2, and: 3, eq: 5, ne: 5, lt: 5, lte: 5, gt: 5, gte: 5,
+      flatten: 9, filter: 21, dot: 40, lbracket: 55, lparen: 60
+    }.freeze
+    PREFIX = {
+      identifier: :prefix_identifier, literal: :prefix_literal, current: :prefix_current,
+      lparen: :prefix_group, lbracket: :prefix_bracket, lbrace: :prefix_hash,
+      not: :prefix_not, expref: :prefix_reference, star: :prefix_star,
+      flatten: :prefix_flatten, filter: :prefix_filter
+    }.freeze
+    INFIX = {
+      dot: :infix_dot, lbracket: :infix_bracket, lparen: :infix_function,
+      flatten: :infix_flatten, filter: :infix_filter
+    }.freeze
+
+    def initialize(source, max_depth: 128)
+      raise ArgumentError, "max_depth must be an integer from 1 through 128" unless (1..128).cover?(max_depth)
+
+      lexer = Lexer.new(source, max_depth: max_depth)
+      @source = lexer.source
+      @tokens = lexer.tokens
+      @index = 0
+      @level = 0
+      @max_depth = max_depth
+    end
+
+    def parse
+      result = expression
+      expect(:eof)
+      result
+    end
+
+    private
+
+    def expression(power = 0)
+      @level += 1
+      syntax!("Expression exceeds nesting limit") if @level > @max_depth + 1
+      token = advance
+      method = PREFIX[token.type]
+      syntax!("Expected an expression", token) unless method
+      left = send(method, token)
+      left = infix(left, advance) while power < POWER.fetch(peek.type, 0)
+      left
+    ensure
+      @level -= 1
+    end
+
+    def infix(left, token)
+      method = INFIX[token.type]
+      return send(method, left, token) if method
+
+      right = expression(POWER.fetch(token.type))
+      return sequence(token.type, left, right) if %i[pipe and or].include?(token.type)
+
+      node(token.type, nil, [left, right])
+    end
+
+    def sequence(kind, left, right)
+      children = left.kind == kind ? [*left.children, right] : [left, right]
+      node(kind, nil, children)
+    end
+
+    def node(kind, value = nil, children = [], start: nil)
+      result = AST::Node.new(
+        kind: kind, value: value, children: children,
+        start: start || children.first&.start || previous.start, finish: previous.finish
+      )
+      syntax!("Expression exceeds nesting limit") if result.depth > @max_depth
+      result
+    end
+
+    def peek
+      @tokens.fetch(@index)
+    end
+
+    def previous
+      @tokens.fetch([@index - 1, 0].max)
+    end
+
+    def advance
+      token = peek
+      @index += 1 unless token.type == :eof
+      token
+    end
+
+    def expect(type)
+      token = advance
+      syntax!("Expected #{type}, received #{token.type}", token) unless token.type == type
+      token
+    end
+
+    def separated(terminator, empty: false)
+      # @type var result: Array[AST::Node]
+      result = []
+      unless empty && peek.type == terminator
+        loop do
+          result << yield
+          break unless peek.type == :comma
+
+          advance
+        end
+      end
+      expect(terminator)
+      result
+    end
+
+    def syntax!(message, token = peek)
+      raise Errors::SyntaxError.new(message, expression: @source, position: token.start)
+    end
+  end
+end
+
+require_relative "parser/expressions"
+require_relative "parser/projections"