janeway-jsonpath 0.6.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33fc9254c0443121404ced6b9e60c15133111299b8f7052f012fe45d7ad4d281
-  data.tar.gz: c5a9eea01a8a332343b47328c64991a52fc50292969247433650914c8af727bd
+  metadata.gz: ff463dd64e17811dddaa23fb3fb82c9bc5cb728dd5b288574f39010174c4f705
+  data.tar.gz: 27f5f8d6c39435fb4ec97eb8a96c7e204c2f06a1e3e7dc569b606d4a52b5cf58
 SHA512:
-  metadata.gz: 0c101d0e02380fc56bd4abc83b5012965e3281aabc3bcce10e7f55c6cff61ba5b825f0d582f95c076234e01d59f07a8db19e6b8984c85e923c780d6f362adc2c
-  data.tar.gz: e2a762c773653c01415dee8f988b95be53d45da8bb3d1ed6f20817eb333fce00b3c960f9268a2212c929a27582d4c0cdb8e480e3948b2e193974f452b32e526f
+  metadata.gz: 113d48240302143e72de6249d1975d0be52074374e94abd0d2a340e54867031653d6f912e0ccb3ab25e0b9734a3d33119bea1fb100c4283bce95560f9c02ad69
+  data.tar.gz: cfdca8a82c1c38f7b3b646afcca7c54d6d996564f2f191cb9cd407fa5abcac8c258c4d4534ce7cd437739174298fda0c66b3d41602e4058a47b7f5d94e4b1208

data/README.md

@@ -29,7 +29,7 @@ Install the gem from the command-line:
 or add it to your Gemfile:
 
 ```
-    gem 'janeway-jsonpath', '~> 0.4.0'
+    gem 'janeway-jsonpath', '~> 0.6'
 ```
 
 ### Usage

data/lib/janeway/ast/array_slice_selector.rb

@@ -22,6 +22,11 @@ module Janeway
     # "explicit" arguments, since they're interpreted differently.
     #
     class ArraySliceSelector < Janeway::AST::Selector
+      # Raw start / end / step values from the query source. Any of them may
+      # be nil, meaning "use the default for the current step direction" —
+      # the interpreter resolves that.
+      attr_reader :start, :end, :step
+
       # @param start [Integer, nil]
       # @param end_ [Integer, nil]
       # @param step [Integer, nil]
@@ -40,102 +45,13 @@ module Janeway
           raise Error, "Array slice selector value too large: #{arg.inspect}" if arg > INTEGER_MAX
         end
 
-        # Nil values are kept to indicate that the "default" values is to be used.
+        # Nil values are kept to indicate that the default value should be used.
         # The interpreter selects the actual values.
         @start = start
         @end = end_
         @step = step
       end
 
-      # Return the step size to use for stepping through the array.
-      # Defaults to 1 if it was not given to the constructor.
-      #
-      # @return [Integer]
-      def step
-        # The iteration behavior of jsonpath does not match that of ruby Integer#step.
-        # Support the behavior of Integer#step, which needs this:
-        #   1. for stepping forward between positive numbers, use a positive number
-        #   2. for stepping backward between positive numbers, use a negative number
-        #   3. for stepping backward from positive to negative, use a negative number
-        #   4. for stepping backward from negative to negative, use a positive number
-        # Case #4 has to be detected and the sign of step inverted
-        @step || 1
-      end
-
-      # Return the start index to use for stepping through the array, based on a specified array size
-      #
-      # @param input_size [Integer]
-      # @return [Integer]
-      def upper_index(input_size)
-        calculate_index_values(input_size).last
-      end
-
-      # Return the end index to use for stepping through the array, based on a specified array size
-      # End index is calculated to omit the final index value, as per the RFC.
-      #
-      # @param input_size [Integer]
-      # @return [Integer]
-      def lower_index(input_size)
-        calculate_index_values(input_size).first
-      end
-
-      # Assign lower and upper bounds to instance variables, based on the input array size.
-      # @see https://www.rfc-editor.org/rfc/rfc9535.html#section-2.3.4.2.2-3
-      #
-      # @param input_size [Integer]
-      def calculate_index_values(input_size)
-        if step >= 0
-          start = @start || 0
-          end_ = @end || input_size
-        else
-          start = @start || (input_size - 1)
-          end_ = @end || ((-1 * input_size) - 1)
-        end
-
-        bounds(start, end_, step, input_size)
-      end
-
-      # NOTE: Conversion of start:end:step to array indexes is defined as pseudocode
-      # in the IETF spec.
-      # The methods #normalize and #bounds are ruby implementations of that code.
-      # Don't make changes here without referring to the original code in the spec.
-      # @see https://www.rfc-editor.org/rfc/rfc9535.html#section-2.3.4.2.2-6
-
-      # IETF: Slice expression parameters start and end are not directly usable
-      # as slice bounds and must first be normalized.
-      #
-      # @param index [Integer]
-      # @param len [Integer]
-      def normalize(index, len)
-        return index if index >= 0
-
-        len + index
-      end
-
-      # IETF: Slice expression parameters start and end are used to derive
-      # slice bounds lower and upper. The direction of the iteration, defined
-      # by the sign of step, determines which of the parameters is the lower
-      # bound and which is the upper bound:¶
-      # @see https://www.rfc-editor.org/rfc/rfc9535.html#section-2.3.4.2.2-9
-      # @param start [Integer] start index, normalized
-      # @param end_ [Integer] end index, normalized
-      # @param step [Integer] step value
-      # @param len [Integer] length of input array
-      def bounds(start, end_, step, len)
-        n_start = normalize(start, len)
-        n_end = normalize(end_, len)
-
-        if step >= 0
-          lower = n_start.clamp(0, len)
-          upper = n_end.clamp(0, len)
-        else
-          upper = n_start.clamp(-1, len - 1)
-          lower = n_end.clamp(-1, len - 1)
-        end
-
-        [lower, upper]
-      end
-
       # @param brackets [Boolean] add surrounding brackets if true
       # @return [String]
       def to_s(brackets: true, **_ignored)

data/lib/janeway/ast/binary_operator.rb

@@ -5,48 +5,31 @@ module Janeway
     # AST node for binary operators:
     #   == != <= >= < > || &&
     class BinaryOperator < Janeway::AST::Expression
-      attr_reader :name, :left, :right
+      attr_reader :name
+      attr_accessor :left, :right
 
       def initialize(operator, left = nil, right = nil)
         super(nil)
         raise ArgumentError, "expect symbol, got #{operator.inspect}" unless operator.is_a?(Symbol)
 
         @name = operator # eg. :equal
-        self.left = left if left
-        self.right = right if right
+        @left = left
+        @right = right
       end
 
-      # Set the left-hand-side expression
-      # @param expr [AST::Expression]
-      def left=(expr)
-        if comparison_operator? && !(expr.literal? || expr.singular_query?)
-          raise Error, "Expression #{expr} does not produce a singular value for #{operator_to_s} comparison"
-        elsif comparison_operator? && expr.is_a?(AST::Function) && !expr.literal?
-          msg = "Function #{expr} returns a non-comparable value which is not usable for #{operator_to_s} comparison"
-          raise Error, msg
-        end
-
-        # Compliance test suite requires error for this, but don't have go so far as to bar every literal
-        if expr.is_a?(Boolean) && right.is_a?(Boolean)
-          raise Error, "Literal \"#{expr}\" must be compared to an expression, not another literal (\"#{left}\")"
-        end
-
-        @left = expr
-      end
-
-      # Set the left-hand-side expression
-      # @param expr [AST::Expression]
-      def right=(expr)
-        if comparison_operator? && !(expr.literal? || expr.singular_query?)
-          raise Error, "Expression #{expr} does not produce a singular value for #{operator_to_s} comparison"
-        end
-
-        # Compliance test suite requires error for this, but don't have go so far as to bar every literal
-        if expr.is_a?(Boolean) && left.is_a?(Boolean)
-          raise Error, "Literal \"#{expr}\" must be compared to an expression, not another literal (\"#{left}\")"
-        end
-
-        @right = expr
+      # Validate the currently-set left and right operands as a well-formed
+      # binary expression. Called by the parser once both sides are assigned —
+      # the previous per-setter validation was order-dependent (left=
+      # couldn't see right and vice-versa) and missed the both-literal case
+      # when the parser assigned left first.
+      #
+      # @raise [Janeway::Error] on any semantic error
+      def validate!
+        raise Error, 'BinaryOperator requires both left and right' unless @left && @right
+
+        validate_side(@left)
+        validate_side(@right)
+        validate_pair
       end
 
       def to_s
@@ -76,31 +59,54 @@ module Janeway
         operator_type == :logical
       end
 
+      # Single source of truth for what binary operators exist and how they
+      # render / classify. Adding a new operator here fills both call sites.
+      OPERATOR_META = {
+        and: { str: '&&', type: :logical },
+        or: { str: '||', type: :logical },
+        equal: { str: '==', type: :comparison },
+        not_equal: { str: '!=', type: :comparison },
+        less_than: { str: '<', type: :comparison },
+        less_than_or_equal: { str: '<=', type: :comparison },
+        greater_than: { str: '>', type: :comparison },
+        greater_than_or_equal: { str: '>=', type: :comparison },
+      }.freeze
+
       private
 
+      def operator_meta
+        OPERATOR_META.fetch(name) { raise "unknown binary operator #{name}" }
+      end
+
       def operator_to_s
-        case name
-        when :and then '&&'
-        when :equal then '=='
-        when :greater_than then '>'
-        when :greater_than_or_equal then '>='
-        when :less_than then '<'
-        when :less_than_or_equal then '<='
-        when :not_equal then '!='
-        when :or then '||'
-        else
-          raise "unknown binary operator #{name}"
-        end
+        operator_meta[:str]
       end
 
       def operator_type
-        case name
-        when :and, :or then :logical
-        when :equal, :not_equal, :greater_than, :greater_than_or_equal, :less_than, :less_than_or_equal then :comparison
-        else
-          raise "unknown binary operator #{name}"
+        operator_meta[:type]
+      end
+
+      # Per-side checks that apply to either operand of a comparison.
+      def validate_side(expr)
+        return unless comparison_operator?
+
+        unless expr.literal? || expr.singular_query?
+          raise Error, "Expression #{expr} does not produce a singular value for #{operator_to_s} comparison"
+        end
+        if expr.is_a?(AST::Function) && !expr.literal?
+          raise Error,
+                "Function #{expr} returns a non-comparable value which is not usable for #{operator_to_s} comparison"
         end
       end
+
+      # Checks that need both sides in scope.
+      def validate_pair
+        return unless @left.is_a?(Boolean) && @right.is_a?(Boolean)
+
+        # Compliance test suite requires error for this, but don't go so far as to bar every literal.
+        raise Error,
+              "Literal \"#{@right}\" must be compared to an expression, not another literal (\"#{@left}\")"
+      end
     end
   end
 end

data/lib/janeway/ast/child_segment.rb

@@ -15,10 +15,8 @@ module Janeway
     #    $[name1, [1:10]]
     class ChildSegment < Janeway::AST::Expression
       extend Forwardable
-      def_delegators :@value, :size, :first, :last, :each, :map, :empty?
 
-      # Subsequent expression that modifies the result of this selector list.
-      attr_accessor :next
+      def_delegators :@value, :size, :first, :last, :each, :map, :empty?
 
       def initialize
         super([]) # @value holds the expressions in the selector
@@ -31,8 +29,8 @@ module Janeway
         @value << selector
       end
 
-      def to_s(with_child: true)
-        str = @value.map { |selector| selector.to_s(brackets: false, dot_prefix: false) }.join(', ')
+      def to_s(with_child: true, **)
+        str = @value.map { |selector| selector.to_s(brackets: false, dot_prefix: false, bracketed: true) }.join(', ')
         with_child ? "[#{str}]#{@next}" : "[#{str}]"
       end
 

data/lib/janeway/ast/current_node.rb

@@ -29,9 +29,6 @@ module Janeway
     #
     # Construct accepts an optional Selector which will be applied to the "current" node
     class CurrentNode < Janeway::AST::Expression
-      # Subsequent expression that modifies the output of this expression
-      attr_accessor :next
-
       def to_s
         "@#{@next}"
       end
@@ -41,17 +38,7 @@ module Janeway
       #
       # @return [Boolean]
       def singular_query?
-        return true unless @next # there are no following selectors
-
-        selector_types = []
-        selector = @next
-        loop do
-          selector_types << selector.class
-          selector = selector.next
-          break unless selector
-        end
-        allowed = [AST::IndexSelector, AST::NameSelector]
-        selector_types.uniq.all? { allowed.include?(_1) }
+        chain_of?(AST::IndexSelector, AST::NameSelector)
       end
 
       # True if this is a bare current node operator, without a following expression
@@ -63,7 +50,7 @@ module Janeway
       # @param level [Integer]
       # @return [Array]
       def tree(level)
-        [indented(level, '@'), @next.tree(indent + 1)]
+        [indented(level, '@'), @next&.tree(level + 1)]
       end
     end
   end

data/lib/janeway/ast/descendant_segment.rb

@@ -16,9 +16,6 @@ module Janeway
     #   $..[*, *] All values, twice non-deterministic order
     #   $..[0, 1] Multiple segments
     class DescendantSegment < Janeway::AST::Selector
-      # Subsequent expression that modifies the result of this selector list.
-      attr_accessor :next
-
       def to_s
         "..#{@next&.to_s(dot_prefix: false)}"
       end

data/lib/janeway/ast/expression.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
+
 require_relative 'helpers'
 require_relative 'error'
 
 module Janeway
   module AST
     INDENT = '  '
+    # Precomputed indent prefixes so #indented does not do `INDENT * level`
+    # (a fresh String allocation) on every line printed.
+    INDENTS = Array.new(16) { |i| (INDENT * i).freeze }.freeze
 
     # Base class for jsonpath expressions.
     #
@@ -16,8 +20,10 @@ module Janeway
       # Value provided by subclass constructor.
       attr_accessor :value
 
-      # Next expression in the AST, if any
-      attr_reader :next
+      # Next expression in the AST, if any. Writable so the parser can link
+      # nodes as it constructs the chain, and so Query#dup / #pop can rewire
+      # the top-level chain.
+      attr_accessor :next
 
       def initialize(val = nil)
         # don't set the instance variable if unused, because it makes the
@@ -27,8 +33,16 @@ module Janeway
 
       # @return [String]
       def type
-        name = self.class.to_s.split('::').last # eg. Janeway::AST::FunctionCall => "FunctionCall"
-        Helpers.camelcase_to_underscore(name) # eg. "FunctionCall" => "function_call"
+        self.class.type_name
+      end
+
+      # Cached camelcase→underscore transform of the class name.
+      # Same value on every instance of the class — compute once per class.
+      #
+      # @return [String]
+      def self.type_name
+        @type_name ||=
+          Helpers.camelcase_to_underscore(name.split('::').last).freeze
       end
 
       # Return the given message, indented
@@ -37,7 +51,7 @@ module Janeway
       # @param msg [String]
       # @return [String]
       def indented(level, msg)
-        format('%s%s', (INDENT * level), msg)
+        (INDENTS[level] || (INDENT * level)) + msg
       end
 
       # @param level [Integer]
@@ -59,6 +73,22 @@ module Janeway
       def singular_query?
         false
       end
+
+      # True if every selector in the @next chain is one of the allowed classes.
+      # An empty chain (no @next) returns true. Extracted from the identical
+      # implementations that used to live in CurrentNode and RootNode.
+      #
+      # @param allowed_classes [Array<Class>]
+      # @return [Boolean]
+      def chain_of?(*allowed_classes)
+        selector = @next
+        while selector
+          return false unless allowed_classes.include?(selector.class)
+
+          selector = selector.next
+        end
+        true
+      end
     end
   end
 end

data/lib/janeway/ast/function.rb

@@ -5,18 +5,28 @@ require_relative 'expression'
 module Janeway
   module AST
     # Represents a JSONPath built-in function.
+    #
+    # This is pure structure: name + parameters. The body / literal_return
+    # metadata lives in Functions::REGISTRY (looked up by name), so AST nodes
+    # don't drag closures over the parser's binding.
     class Function < Janeway::AST::Expression
       alias name value
 
-      attr_reader :parameters, :body
+      attr_reader :parameters
 
-      def initialize(name, parameters, &body)
+      def initialize(name, parameters)
         raise ArgumentError, "expect string, got #{name.inspect}" unless name.is_a?(String)
 
+        spec = Functions::REGISTRY[name]
+        raise ArgumentError, "unknown function #{name.inspect}" unless spec
+        unless spec[:arity] == parameters.size
+          raise ArgumentError,
+                "function #{name.inspect}: declared arity #{spec[:arity]} does not " \
+                "match parameter count #{parameters.size}"
+        end
+
         super(name)
         @parameters = parameters
-        @body = body
-        raise "expect body to be a Proc, got #{body.class}" unless body.is_a?(Proc)
       end
 
       def to_s
@@ -39,12 +49,7 @@ module Janeway
 
       # True if the function's return value is a literal
       def literal?
-        case name
-        when 'length', 'count', 'value' then true
-        when 'search', 'match' then false
-        else
-          raise "Unknown jsonpath function #{name}"
-        end
+        Functions::REGISTRY.fetch(name)[:literal_return]
       end
     end
   end

data/lib/janeway/ast/name_selector.rb

@@ -17,16 +17,21 @@ module Janeway
         raise "Invalid name: #{value.inspect}:#{value.class}" unless value.is_a?(String)
       end
 
+      # Chars that force bracket notation (they are not permitted in the
+      # dotted shorthand).
+      SPECIAL_CHARS = /[ .]/
+
       # @param brackets [Boolean] request for bracket syntax
       # @param dot_prefix [Boolean] include . prefix, if shorthand notation is used
-      def to_s(brackets: false, dot_prefix: true)
+      # @param bracketed [Boolean] caller already provided brackets (e.g. within a union);
+      #   emit the quoted name only, without adding brackets
+      def to_s(brackets: false, dot_prefix: true, bracketed: false)
         # Add quotes and surrounding brackets if the name includes chars that require quoting.
-        # These chars are not allowed in dotted notation, only bracket notation.
-        special_chars = [' ', '.']
-        brackets ||= special_chars.any? { |char| @value.include?(char) }
-        if brackets
-          name_str = quote(@value)
-          "[#{name_str}]#{@next}"
+        brackets ||= @value.match?(SPECIAL_CHARS)
+        if bracketed
+          "#{quote(@value)}#{@next}"
+        elsif brackets
+          "[#{quote(@value)}]#{@next}"
         elsif dot_prefix
           ".#{@value}#{@next}"
         else # omit dot prefix after a descendant segment

data/lib/janeway/ast/root_node.rb

@@ -14,9 +14,6 @@ module Janeway
     #   $(? $.key1 == $.key2 )
     #
     class RootNode < Janeway::AST::Expression
-      # Subsequent expression that modifies the output of this expression
-      attr_accessor :next
-
       def to_s
         "$#{@next}"
       end
@@ -26,23 +23,13 @@ module Janeway
       #
       # @return [Boolean]
       def singular_query?
-        return true unless @next # there are no following selectors
-
-        selector_types = []
-        selector = @next
-        loop do
-          selector_types << selector.class
-          selector = selector&.next
-          break unless selector
-        end
-        allowed = [AST::IndexSelector, AST::NameSelector]
-        selector_types.uniq.all? { allowed.include?(_1) }
+        chain_of?(AST::IndexSelector, AST::NameSelector)
       end
 
       # @param level [Integer]
       # @return [Array]
       def tree(level = 0)
-        [indented(level, '$'), @next.tree(level + 1)]
+        [indented(level, '$'), @next&.tree(level + 1)]
       end
     end
   end

data/lib/janeway/ast/selector.rb

@@ -23,12 +23,11 @@ module Janeway
     # Filter expressions ?<logical-expr> select certain children of an object or array, as in:
     #     $.store.book[?@.price < 10].title
     class Selector < Janeway::AST::Expression
-      # Subsequent expression that modifies the result of this selector list.
-      attr_accessor :next
-
-      def ==(other)
-        value == other&.value
-      end
+      # Intentionally NO #== override. The previous implementation compared
+      # only `value`, ignoring class and @next, which made two selector chains
+      # with identical heads but different tails compare equal (and matched
+      # across selector types by coincidence of value). Query#== is the
+      # correct equality entry point for query comparisons.
     end
   end
 end

data/lib/janeway/ast/unary_operator.rb

@@ -13,13 +13,23 @@ module Janeway
       end
 
       def to_s
-        "#{@operator} #{operand}"
+        "#{operator_to_s}#{operand}"
       end
 
       # @param level [Integer]
       # @return [Array]
       def tree(level)
-        indented(level, "#{operator}#{operand}")
+        indented(level, "#{operator_to_s}#{operand}")
+      end
+
+      private
+
+      def operator_to_s
+        case @name
+        when :not then '!'
+        else
+          raise "unknown unary operator #{@name}"
+        end
       end
     end
   end

data/lib/janeway/ast/wildcard_selector.rb

@@ -23,7 +23,7 @@ module Janeway
       end
 
       # @return [String]
-      def to_s(brackets: false, dot_prefix: true)
+      def to_s(brackets: false, dot_prefix: true, **)
         if brackets
           "[*]#{@next&.to_s(brackets: true)}"
         elsif dot_prefix
@@ -36,7 +36,7 @@ module Janeway
       # @param level [Integer]
       # @return [Array]
       def tree(level)
-        [indented(level, '*'), @next.tree(level + 1)]
+        [indented(level, '*'), @next&.tree(level + 1)]
       end
     end
   end

data/lib/janeway/enumerator.rb

@@ -56,7 +56,7 @@ module Janeway
     # Assign the given value at every query match.
     # @param replacement [Object]
     # @return [void]
-    def replace(replacement = :no_replacement_value_was_given, &block)
+    def replace(replacement = :no_replacement_value_was_given, &_)
       if replacement != :no_replacement_value_was_given && block_given?
         raise Janeway::Error.new('#replace needs either replacement value or block, not both', @query)
       end
@@ -118,6 +118,15 @@ module Janeway
       end
     end
 
+    # Return the normalized path of every query match.
+    #
+    # @see https://www.rfc-editor.org/rfc/rfc9535.html#name-normalized-paths
+    #
+    # @return [Array<String>] normalized paths, eg. [ "$['key'][0]"] ]
+    def find_paths
+      map { |_, _, _, path| path }
+    end
+
     private
 
     # Find the 'parent' of the object pointed to by the query. For singular query only.
@@ -125,9 +134,7 @@ module Janeway
     # @!visibility private
     # @return [Object, Object, String] parent object (Hash / Array), key/index (String / Integer), path to parent
     def find_parent
-      # Make a Query that points to the target's parent
-      parent_query = @query.dup
-      selector = parent_query.pop # returns a name or index selector
+      parent_query, leaf = @query.parent_query
 
       # Find parent element, give up if parent does not exist
       results = Interpreter.new(parent_query).interpret(@input)
@@ -137,7 +144,7 @@ module Janeway
       else raise "query #{parent_query} matched multiple elements!" # not possible for singular query
       end
 
-      [parent, selector.value, parent_query.to_s]
+      [parent, leaf.value, parent_query.to_s]
     end
 
     # Insert value into hash at the given key
@@ -149,7 +156,7 @@ module Janeway
     # @param path [String] jsonpath singular query to parent
     # @yieldparam [Hash] parent object
     # @yieldparam [String] hash key
-    def insert_into_hash(hash, key, value, path, &block)
+    def insert_into_hash(hash, key, value, path, &_)
       unless key.is_a?(String) || key.is_a?(Symbol)
         raise Error.new("cannot use #{key.inspect} as hash key", @query.to_s)
       end
@@ -172,7 +179,7 @@ module Janeway
     # @param path [String] jsonpath singular query to parent
     # @yieldparam [Array] parent object
     # @yieldparam [Integer] array index
-    def insert_into_array(array, index, value, path, &block)
+    def insert_into_array(array, index, value, path)
       raise Error.new("cannot use #{index.inspect} as array index", @query.to_s) unless index.is_a?(Integer)
 
       if index < array.size