jmespath-ruby 0.1.1 → 0.1.2

data/lib/jmespath/errors.rb

@@ -10,6 +10,8 @@ module JMESPath
 
     # A malformed expression with a byte position and readable coordinates.
     class SyntaxError < Error
+      # @return [String] the reason parsing failed, without coordinates
+      attr_reader :reason
       # @return [String] the expression text
       attr_reader :expression
       # @return [Integer] zero-based byte offset
@@ -18,10 +20,17 @@ module JMESPath
       # @param message [String] the reason parsing failed
       # @param expression [String] expression text
       # @param position [Integer] zero-based byte offset
-      def initialize(message, expression: "", position: 0)
+      def initialize(message, expression: "", position: nil)
+        @reason = message.dup.freeze
         @expression = expression.dup.freeze
-        @position = position
-        super("#{message} at byte #{position}")
+        @location_known = !position.nil?
+        @position = position || 0
+        super("#{message} at byte #{@position}")
+      end
+
+      # @return [Boolean] whether the caller supplied a source position
+      def location_known?
+        @location_known
       end
 
       # @return [Integer] one-based line number
@@ -41,13 +50,116 @@ module JMESPath
       end
     end
 
+    # @api private
+    module FunctionFailure
+      # @return [String, nil] function identifier
+      attr_reader :function_name
+      # @return [Array<Array<Symbol>>, nil] complete declared signature
+      attr_reader :signature
+      # @return [Range<Integer>, nil] exclusive byte range of the function call
+      attr_reader :source_range
+
+      # @api private
+      def initialize(message = nil, function_name: nil, signature: nil, variadic: nil, source_range: nil)
+        @function_name = function_name.dup.freeze
+        @signature = signature&.map { |types| types.dup.freeze }&.freeze
+        @variadic = variadic
+        @source_range = source_range.dup.freeze
+        super(message)
+      end
+
+      # @return [Boolean, nil] whether the last declared argument repeats
+      def variadic?
+        @variadic
+      end
+    end
+
     # A function received an unsupported value type.
-    class InvalidTypeError < RuntimeError; end
+    # @example Inspect a validation failure
+    #   error = begin
+    #     JMESPath.search("length(@)", 4)
+    #   rescue JMESPath::Errors::InvalidTypeError => failure
+    #     failure
+    #   end
+    #   error.expected_types #=> [:string, :array, :object]
+    #   error.argument_position #=> 1
+    class InvalidTypeError < RuntimeError
+      include FunctionFailure
+
+      # @!attribute [r] function_name
+      #   @return [String, nil] function identifier
+      # @!attribute [r] signature
+      #   @return [Array<Array<Symbol>>, nil] complete declared signature
+      # @!attribute [r] source_range
+      #   @return [Range<Integer>, nil] exclusive byte range of the function call
+      # @!method variadic?
+      #   @return [Boolean, nil] whether the last declared argument repeats
+
+      # @return [Integer, nil] one-based actual argument position
+      attr_reader :argument_position
+      # @return [Array<Symbol>, nil] types accepted by the failing check
+      attr_reader :expected_types
+      # @return [Symbol, nil] rejected type, including :unknown
+      attr_reader :actual_type
+      # @return [Symbol, nil] :argument or :expression_result
+      attr_reader :validation_stage
+
+      # @api private
+      def initialize(message = nil, argument_position: nil, expected_types: nil, actual_type: nil, # rubocop:disable Metrics/ParameterLists
+                     validation_stage: nil, **context)
+        @argument_position = argument_position
+        @expected_types = expected_types&.dup&.freeze
+        @actual_type = actual_type
+        @validation_stage = validation_stage
+        super(message, **context)
+      end
+    end
+
     # A value is invalid for the requested operation.
     class InvalidValueError < RuntimeError; end
+
     # A function received an incorrect number of arguments.
-    class InvalidArityError < RuntimeError; end
+    class InvalidArityError < RuntimeError
+      include FunctionFailure
+
+      # @!attribute [r] function_name
+      #   @return [String, nil] function identifier
+      # @!attribute [r] signature
+      #   @return [Array<Array<Symbol>>, nil] complete declared signature
+      # @!attribute [r] source_range
+      #   @return [Range<Integer>, nil] exclusive byte range of the function call
+      # @!method variadic?
+      #   @return [Boolean, nil] whether the last declared argument repeats
+
+      # @return [Integer, nil] exact argument count, or minimum when variadic
+      attr_reader :expected_arity
+      # @return [Integer, nil] actual argument count
+      attr_reader :actual_arity
+
+      # @api private
+      def initialize(message = nil, expected_arity: nil, actual_arity: nil, **context)
+        @expected_arity = expected_arity
+        @actual_arity = actual_arity
+        super(message, **context)
+      end
+    end
+
     # A function name is not registered.
-    class UnknownFunctionError < RuntimeError; end
+    class UnknownFunctionError < RuntimeError
+      # @return [String, nil] unregistered function identifier
+      attr_reader :function_name
+      # @return [Array<String>] up to three similar names from the active registry
+      attr_reader :suggestions
+
+      # @param message [String, nil] failure message
+      # @param function_name [String, nil] unregistered function identifier
+      # @param suggestions [Array<String>] ranked registered names
+      def initialize(message = nil, function_name: nil, suggestions: [])
+        @function_name = function_name&.dup&.freeze
+        @suggestions = suggestions.map { |name| name.dup.freeze }.freeze
+        message = "#{message}. Did you mean #{@suggestions.join(', ')}?" unless @suggestions.empty?
+        super(message)
+      end
+    end
   end
 end

data/lib/jmespath/evaluation/scalars.rb

@@ -43,7 +43,8 @@ module JMESPath
 
     def function(node, data)
       arguments = node.children.map { |child| evaluate(child, data) }
-      @functions.call(node.value.to_s, arguments, disable_visit_errors: @disable_visit_errors)
+      @functions.call_with_context(node.value.to_s, arguments, source_range: node.start...node.finish,
+                                                               disable_visit_errors: @disable_visit_errors)
     end
   end
 end

data/lib/jmespath/functions/coercions.rb

@@ -6,33 +6,49 @@ module JMESPath
     module Coercions
       extend self
 
-      def number(value)
+      NATIVE_TYPES = { String => :string, NilClass => :null, TrueClass => :boolean, FalseClass => :boolean,
+                       Array => :array, Hash => :object, ExpressionReference => :expref }.freeze
+
+      def number(value, context: nil, position: nil, stage: :argument)
         return value if value.is_a?(Integer)
         return value if value.is_a?(Float) && value.finite?
 
-        raise Signature::TypeMismatch.new("Expected a finite number", origin: validation_origin)
+        raise type_failure(value, "Expected a finite number", [:number], context, position, stage)
       end
 
-      def string(value)
-        DataAccess.string(value) || raise(Signature::TypeMismatch.new("Expected a string", origin: validation_origin))
+      def string(value, context: nil, position: nil)
+        DataAccess.string(value) || raise(type_failure(value, "Expected a string", [:string], context, position))
       end
 
-      def array(value)
-        DataAccess.array(value) || raise(Signature::TypeMismatch.new("Expected an array", origin: validation_origin))
+      def array(value, context: nil, position: nil)
+        DataAccess.array(value) || raise(type_failure(value, "Expected an array", [:array], context, position))
       end
 
-      def reference(value)
+      def reference(value, context: nil, position: nil)
         return value if value.is_a?(ExpressionReference)
 
-        raise Signature::TypeMismatch.new("Expected an expression reference", origin: validation_origin)
+        raise type_failure(value, "Expected an expression reference", [:expref], context, position)
       end
 
-      def object(value)
-        DataAccess.object(value) || raise(Signature::TypeMismatch.new("Expected an object", origin: validation_origin))
+      def object(value, context: nil, position: nil)
+        DataAccess.object(value) || raise(type_failure(value, "Expected an object", [:object], context, position))
       end
 
       private
 
+      def type_failure(value, message, types, context, position, stage = :argument) # rubocop:disable Metrics/ParameterLists
+        return Signature::TypeMismatch.new(message, origin: validation_origin) unless context
+
+        context.type_error(message, position: position, expected_types: types, actual_type: native_type(value),
+                                    origin: validation_origin, stage: stage)
+      end
+
+      def native_type(value)
+        return :number if Types.number?(value)
+
+        NATIVE_TYPES.find { |klass, _type| value.is_a?(klass) }&.last || :unknown
+      end
+
       def validation_origin
         nil
       end

data/lib/jmespath/functions/collections.rb

@@ -14,60 +14,84 @@ module JMESPath
         "min_by" => [[:array], [:expref]], "max_by" => [[:array], [:expref]]
       }.freeze
 
+      DESCRIPTIONS = {
+        "avg" => "Mean, or null for an empty array.",
+        "sum" => "Sum, including zero for an empty array.",
+        "min" => "Minimum, or null for an empty array.",
+        "max" => "Maximum, or null for an empty array.",
+        "sort" => "Stable sorted array of numbers or strings.",
+        "join" => "Join strings with a separator.",
+        "keys" => "Object keys as strings.",
+        "values" => "Object values.",
+        "merge" => "Merge objects, with later values winning.",
+        "map" => "Map an expression over an array, including null results.",
+        "sort_by" => "Stable array sorted by homogeneous expression results.",
+        "min_by" => "Input element with minimum expression result, or null for an empty array.",
+        "max_by" => "Input element with maximum expression result, or null for an empty array."
+      }.freeze
+
       def self.register(registry)
         SIGNATURES.reduce(registry) do |result, (name, signature)|
-          result.with_builtin(name, signature: signature, handler: name.to_sym, variadic: name == "merge")
+          result.with_builtin(name, signature: signature, handler: name.to_sym,
+                                    description: DESCRIPTIONS.fetch(name), variadic: name == "merge")
         end
       end
 
       private
 
-      def sum(value)
-        array(value).sum { |item| number(item) }
+      def sum(value, context:)
+        element_context = context.array_element(1)
+        array(value, context: context, position: 1).sum { |item| number(item, context: element_context, position: 1) }
       end
 
-      def avg(value)
-        values = array(value)
-        number(sum(value)).fdiv(values.length) unless values.empty?
+      def avg(value, context:)
+        values = array(value, context: context, position: 1)
+        return if values.empty?
+
+        number(sum(value, context: context), context: context.array_element(1), position: 1).fdiv(values.length)
       end
 
-      def min(value)
-        array(value).min_by { |item| sort_key(item) }
+      def min(value, context:)
+        element_context = context.array_element(1)
+        array(value, context: context, position: 1).min_by { |item| sort_key(item, context: element_context) }
       end
 
-      def max(value)
-        array(value).max_by { |item| sort_key(item) }
+      def max(value, context:)
+        element_context = context.array_element(1)
+        array(value, context: context, position: 1).max_by { |item| sort_key(item, context: element_context) }
       end
 
-      def sort(value)
-        array(value).each_with_index.sort_by do |item, index|
-          [sort_key(item), index]
+      def sort(value, context:)
+        element_context = context.array_element(1)
+        array(value, context: context, position: 1).each_with_index.sort_by do |item, index|
+          [sort_key(item, context: element_context), index]
         end.map(&:first)
       end
 
-      def join(separator, value)
-        array(value).map do |item|
-          string(item)
-        end.join(string(separator))
+      def join(separator, value, context:)
+        element_context = context.array_element(2)
+        array(value, context: context, position: 2).map do |item|
+          string(item, context: element_context, position: 2)
+        end.join(string(separator, context: context, position: 1))
       end
 
-      def keys(value)
-        object(value).keys.map(&:to_s)
+      def keys(value, context:)
+        object(value, context: context, position: 1).keys.map(&:to_s)
       end
 
-      def values(value)
-        object(value).values
+      def values(value, context:)
+        object(value, context: context, position: 1).values
       end
 
-      def merge(*values)
+      def merge(*values, context:)
         # @type var result: Hash[value, value]
         result = {}
-        values.each { |value| result.merge!(object(value)) }
+        values.each_with_index { |value, index| result.merge!(object(value, context: context, position: index + 1)) }
         result
       end
 
-      def sort_key(value)
-        DataAccess.string(value) || number(value)
+      def sort_key(value, context:, position: 1, stage: :argument)
+        DataAccess.string(value) || number(value, context: context, position: position, stage: stage)
       end
     end
 

data/lib/jmespath/functions/conversion.rb

@@ -8,17 +8,17 @@ module JMESPath
 
       private
 
-      def to_array(value)
+      def to_array(value, **)
         DataAccess.array(value) || [value]
       end
 
-      def to_string(value)
+      def to_string(value, **)
         DataAccess.string(value) || JSON.generate(Types.normalize(value))
       rescue JSON::NestingError
         raise Errors::InvalidValueError, "Value is too deeply nested to serialize"
       end
 
-      def to_number(value)
+      def to_number(value, **)
         return value if Types.number?(value)
 
         text = DataAccess.string(value)&.strip

data/lib/jmespath/functions/function_call.rb

@@ -10,10 +10,15 @@ module JMESPath
 
       private :number, :string, :array, :reference, :object
 
-      def call(definition, name, arguments, disable_visit_errors: false)
-        definition.signature.validate!(arguments, name, origin: self)
+      def call(definition, name, arguments, disable_visit_errors: false, context: nil)
+        context ||= ValidationContext.new(name, definition.signature)
+        definition.signature.validate!(arguments, name, origin: self, context: context)
         implementation = definition.implementation
-        implementation.is_a?(Symbol) ? send(implementation, *arguments) : implementation.call(*arguments)
+        if implementation.is_a?(Symbol)
+          send(implementation, *arguments, context: context)
+        else
+          implementation.call(*arguments)
+        end
       rescue Signature::TypeMismatch, Signature::ArityMismatch => e
         raise unless disable_visit_errors && e.origin.equal?(self)
 

data/lib/jmespath/functions/references.rb

@@ -8,51 +8,68 @@ module JMESPath
 
       private
 
-      def map(expression, value)
-        reference = reference(expression)
-        array(value).map { |item| reference.call(item) }
+      def map(expression, value, context:)
+        reference = reference(expression, context: context, position: 1)
+        array(value, context: context, position: 2).map { |item| reference.call(item) }
       end
 
-      def sort_by(value, expression)
-        reference = reference(expression)
+      def sort_by(value, expression, context:)
+        reference = reference(expression, context: context, position: 2)
         # @type var expected: Symbol?
         expected = nil
+        # @type var result_context: ValidationContext?
+        result_context = nil
         index = 0
-        array(value).sort_by do |item|
+        array(value, context: context, position: 1).sort_by do |item|
           key = reference.call(item)
-          expected = checked_type(key, expected)
+          type = checked_type(key, expected, context: context)
+          expected = type
+          key_context = result_context || context.with_types([type])
+          result_context = key_context
           index += 1
-          [sort_key(key), index]
+          [sort_key(key, context: key_context, position: 2, stage: :expression_result), index]
         end
       end
 
-      def min_by(value, expression)
-        keyed(value, expression).min_by(&:first)&.last
+      def min_by(value, expression, context:)
+        keyed(value, expression, context: context).min_by(&:first)&.last
       end
 
-      def max_by(value, expression)
-        keyed(value, expression).max_by(&:first)&.last
+      def max_by(value, expression, context:)
+        keyed(value, expression, context: context).max_by(&:first)&.last
       end
 
-      def keyed(value, expression)
-        reference = reference(expression)
+      def keyed(value, expression, context:)
+        reference = reference(expression, context: context, position: 2)
         # @type var expected: Symbol?
         expected = nil
-        array(value).map do |item|
+        # @type var result_context: ValidationContext?
+        result_context = nil
+        array(value, context: context, position: 1).map do |item|
           key = reference.call(item)
-          expected = checked_type(key, expected)
-          [sort_key(key), item]
+          type = checked_type(key, expected, context: context)
+          expected = type
+          key_context = result_context || context.with_types([type])
+          result_context = key_context
+          [sort_key(key, context: key_context, position: 2, stage: :expression_result), item]
         end
       end
 
-      def checked_type(value, expected)
+      def checked_type(value, expected, context:)
         type = Types.name(value)
         unless SORTABLE_TYPES.include?(type)
-          raise Signature::TypeMismatch.new("Expression keys must be numbers or strings", origin: validation_origin)
+          raise context.type_error(
+            "Expression keys must be numbers or strings",
+            position: 2, expected_types: expected ? [expected] : SORTABLE_TYPES, actual_type: type,
+            origin: validation_origin, stage: :expression_result
+          )
         end
         if expected && expected != type
-          raise Signature::TypeMismatch.new("Expression keys must have one type",
-                                            origin: validation_origin)
+          raise context.type_error(
+            "Expression keys must have one type",
+            position: 2, expected_types: [expected], actual_type: type,
+            origin: validation_origin, stage: :expression_result
+          )
         end
 
         type

data/lib/jmespath/functions/scalar.rb

@@ -13,57 +13,74 @@ module JMESPath
         "to_number" => [[:any]], "not_null" => [[:any]]
       }.freeze
 
+      DESCRIPTIONS = {
+        "abs" => "Absolute value.",
+        "ceil" => "Integer rounded upward.",
+        "floor" => "Integer rounded downward.",
+        "contains" => "Test string or array membership.",
+        "ends_with" => "Test whether a string ends with a suffix.",
+        "starts_with" => "Test whether a string starts with a prefix.",
+        "length" => "Character or element count.",
+        "reverse" => "Reverse a string or array.",
+        "type" => "JMESPath type name.",
+        "to_array" => "Wrap a value in an array, preserving arrays.",
+        "to_string" => "String or compact JSON representation.",
+        "to_number" => "Number when convertible, otherwise null.",
+        "not_null" => "First non-null value."
+      }.freeze
+
       def self.register(registry)
         SIGNATURES.reduce(registry) do |result, (name, signature)|
           handler = %w[contains ends_with starts_with].include?(name) ? "#{name}?" : name
-          result.with_builtin(name, signature: signature, handler: handler.to_sym, variadic: name == "not_null")
+          result.with_builtin(name, signature: signature, handler: handler.to_sym,
+                                    description: DESCRIPTIONS.fetch(name), variadic: name == "not_null")
         end
       end
 
       private
 
-      def abs(value)
-        number(value).abs
+      def abs(value, context:)
+        number(value, context: context, position: 1).abs
       end
 
-      def ceil(value)
-        number(value).ceil
+      def ceil(value, context:)
+        number(value, context: context, position: 1).ceil
       end
 
-      def floor(value)
-        number(value).floor
+      def floor(value, context:)
+        number(value, context: context, position: 1).floor
       end
 
-      def contains?(subject, search)
+      def contains?(subject, search, context:)
         text = DataAccess.string(subject)
-        return text.include?(string(search)) if text
+        return text.include?(string(search, context: context, position: 2)) if text
 
-        array(subject).any? { |item| Types.equal?(item, search) }
+        array(subject, context: context, position: 1).any? { |item| Types.equal?(item, search) }
       end
 
-      def ends_with?(text, suffix)
-        string(text).end_with?(string(suffix))
+      def ends_with?(text, suffix, context:)
+        string(text, context: context, position: 1).end_with?(string(suffix, context: context, position: 2))
       end
 
-      def starts_with?(text, prefix)
-        string(text).start_with?(string(prefix))
+      def starts_with?(text, prefix, context:)
+        string(text, context: context, position: 1).start_with?(string(prefix, context: context, position: 2))
       end
 
-      def length(value)
-        collection = DataAccess.string(value) || DataAccess.array(value) || object(value)
+      def length(value, context:)
+        collection = DataAccess.string(value) || DataAccess.array(value) || object(value, context: context, position: 1)
         collection.length
       end
 
-      def reverse(value)
-        (DataAccess.string(value) || array(value)).reverse
+      def reverse(value, context:)
+        (DataAccess.string(value) || array(value, context: context, position: 1)).reverse
       end
 
-      def type(value)
+      def type(value, **)
         name = Types.name(value)
         name.to_s unless name == :unknown
       end
 
-      def not_null(*values)
+      def not_null(*values, **)
         values.find { |value| !value.nil? }
       end
     end

data/lib/jmespath/functions/signature.rb

@@ -10,9 +10,9 @@ module JMESPath
       module FailureOrigin
         attr_reader :origin
 
-        def initialize(message = nil, origin: nil)
+        def initialize(message = nil, origin: nil, **metadata)
           @origin = origin
-          super(message)
+          super(message, **metadata)
         end
       end
 
@@ -26,6 +26,12 @@ module JMESPath
         include FailureOrigin
       end
 
+      attr_reader :arguments
+
+      def variadic?
+        @variadic
+      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?
@@ -35,21 +41,29 @@ module JMESPath
         freeze
       end
 
-      def validate!(values, name, origin: nil)
+      def validate!(values, name, origin: nil, context: nil)
+        context ||= ValidationContext.new(name, self)
         unless valid_arity?(values.length)
-          raise ArityMismatch.new("Invalid number of arguments for #{name}", origin: origin)
+          raise context.arity_error("Invalid number of arguments for #{name}", actual_arity: values.length,
+                                                                               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)
+          reject_type!(value, index, types, name, origin, context)
         end
       end
 
       private
 
+      def reject_type!(value, index, types, name, origin, context) # rubocop:disable Metrics/ParameterLists
+        actual_type = Types.name(value)
+        raise context.type_error("Invalid argument #{index + 1} for #{name}: #{actual_type}",
+                                 position: index + 1, expected_types: types, actual_type: actual_type, origin: origin)
+      end
+
       def valid_definition?(arguments)
         arguments.is_a?(Array) && arguments.all? do |types|
           types.is_a?(Array) && !types.empty? && (types - TYPES).empty?