janeway-jsonpath 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07de626741809ed0f0c9d62f626a45a1eb91513cfda3b536160060428e23cda0
-  data.tar.gz: 70953f9cee1de853145ff4eb56a80ed535a93d6126211982b7adaada9438c9a0
+  metadata.gz: 10f6ca7766f713b6272f971fd9f6b119895a59385dcebf0cfdb6e0b7d7b27de8
+  data.tar.gz: b33f60624ea2fc41740c888ce00c818c8a873ca56c3d8f85f49b00abee7ea466
 SHA512:
-  metadata.gz: 003fbc4fe8e79e174f8e06147f4790554ca2577ed0b29503f1ef61619a33ef082a7e2f2ee3a39a2eb412e0b28778ed90b7ad3c9b6205d67888b2121f9f32e488
-  data.tar.gz: ee42a2d1601aa765d748a5a806f79653622a7cfc83c1fdbe87a04cd0c3f7effb67b5a8c3a88fa6733bfb0c50fb138fa0b152aed58c5a28b646032a6951309b84
+  metadata.gz: 2cf900d4b424ba23d436a6a8d3714e274ad5b6198c3062ec73760d489634105effed9350c665c29673032f899a855ea7d946b85b583b83e3b0d0730ec1e2244f
+  data.tar.gz: 5b28155e3e56346e95f512688cde87310329626d8deb50af76f7ff2d59529f3bb8816b1c62d2bc402266feda338b29bd7197835543c96ea2930d572199cdb293

data/README.md

@@ -24,7 +24,7 @@ This project includes:
 
 ### Non-goals
 
-* Changing behavior to follow [other implementations] (https://cburgmer.github.io/json-path-comparison/)
+* Changing behavior to follow [other implementations](https://cburgmer.github.io/json-path-comparison/)
 
 The JSONPath RFC was in draft status for a long time and has seen many changes.
 There are many implementations based on older drafts, or which add features that were never in the RFC at all.
@@ -35,9 +35,30 @@ The RFC was finalized in 2024, and it has a rigorous [suite of compliance tests.
 
 With these tools it is possible to have JSONPath implementations in many languages with identical behavior.
 
+### Differences from joshbuddy/jsonpath
+
+The only other serious ruby implementation of jsonpath is joshbuddy/jsonpath.
+This implementation has been around for a long time.
+I personally have used it in a software project for several years.
+Here are differences I've found in porting this application from joshbuddy/jsonpath to janeway.
+
+* joshbuddy/jsonpath allows unquoted strings in filter comparisons.
+Examples:
+$ jsonpath '$.store.book[?(@.category==reference)]' example.json
+$ janeway '$.store.book[?(@.category=="reference")]' example.json
+
+* joshbuddy/jsonpath allows root selector to be omitted
+grid.first('gid').to_i
+
+$ jsonpath 'store' example.json
+$ janeway '$.store' example.json
+
+*
+$ jsonpath '$.nodes..services..id' spec/resources/grid-full.json
+
 ### Implementation
 
 Functionality is based on [IETF RFC 9535, "JSONPath: Query Expressions for JSON"](https://www.rfc-editor.org/rfc/rfc9535.html#filter-selector)
 The examples in the RFC have been implemented as unit tests.
 
-For details not covered in the RFC, it does the most reasonable thing based on [what other JSONPath parsers do.](https://cburgmer.github.io/json-path-comparison/). However, this is always secondary to following the RFC. Many of the recommended behaviors there contradict the RFC, so it is one or the other.
+For details not covered in the RFC, it does the most reasonable thing based on [what other JSONPath parsers do](https://cburgmer.github.io/json-path-comparison/). However, this is always secondary to following the RFC. Many of the popular behaviors there contradict the RFC, so it has to be one or the other.

data/bin/janeway

@@ -123,8 +123,7 @@ begin
   options = parse_args(ARGV.dup)
   main(options)
 rescue Janeway::Error => e
-  puts
-  abort("Error: #{e}")
+  abort e.detailed_message
 rescue Interrupt, Errno::EPIPE
   abort("\n")
 end

data/lib/janeway/ast/array_slice_selector.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'janeway'
 require_relative 'selector'
 
 module Janeway
@@ -25,12 +26,19 @@ module Janeway
       # @param end_ [Integer, nil]
       # @param step [Integer, nil]
       def initialize(start = nil, end_ = nil, step = nil)
+        super(nil)
+
+        # Check arguments
         [start, end_, step].each do |arg|
-          next if arg.nil? || arg.is_a?(Integer)
+          unless [NilClass, Integer].include?(arg.class)
+            raise Error, "Array slice selector index must be integer or nothing, got #{arg.inspect}"
+          end
+          next unless arg
 
-          raise ArgumentError, "Expect Integer or nil, got #{arg.inspect}"
+          # Check integer size limits
+          raise Error, "Array slice selector value too small: #{arg.inspect}" if arg < INTEGER_MIN
+          raise Error, "Array slice selector value too large: #{arg.inspect}" if arg > INTEGER_MAX
         end
-        super(nil)
 
         # Nil values are kept to indicate that the "default" values is to be used.
         # The interpreter selects the actual values.
@@ -58,14 +66,8 @@ module Janeway
       #
       # @param input_size [Integer]
       # @return [Integer]
-      def start_index(input_size)
-        if @start
-          @start.clamp(0, input_size)
-        elsif step.positive?
-          0
-        else # negative step
-          input_size - 1 # last index of input
-        end
+      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
@@ -73,15 +75,65 @@ module Janeway
       #
       # @param input_size [Integer]
       # @return [Integer]
-      def end_index(input_size)
-        if @end
-          value = @end.clamp(0, input_size)
-          step.positive? ? value - 1 : value + 1 # +/- to exclude the final element
-        elsif step.positive?
-          input_size - 1 # last index of input
+      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
-          0
+          upper = n_start.clamp(-1, len - 1)
+          lower = n_end.clamp(-1, len - 1)
         end
+
+        [lower, upper]
       end
 
       # ignores the brackets: argument, this always needs surrounding brackets

data/lib/janeway/ast/binary_operator.rb

@@ -19,6 +19,9 @@ module Janeway
       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

data/lib/janeway/ast/child_segment.rb

@@ -17,12 +17,10 @@ module Janeway
       def_delegators :@value, :size, :first, :last, :each, :map, :empty?
 
       # Subsequent expression that modifies the result of this selector list.
-      # This one is not in the selector list, it comes afterward.
-      attr_accessor :child
+      attr_accessor :next
 
       def initialize
         super([]) # @value holds the expressions in the selector
-        @child = nil # @child is the next expression, which modifies the output of this one
       end
 
       # Add a selector to the list
@@ -33,15 +31,15 @@ module Janeway
       end
 
       def to_s(with_child: true)
-        str = @value.map { |selector| selector.to_s(brackets: false) }.join(', ')
-        with_child ? "[#{str}]#{@child}" : "[#{str}]"
+        str = @value.map { |selector| selector.to_s(brackets: false, dot_prefix: false) }.join(', ')
+        with_child ? "[#{str}]#{@next}" : "[#{str}]"
       end
 
       # @param level [Integer]
       # @return [Array]
       def tree(level)
         msg = format('[%s]', @value.map(&:to_s).join(', '))
-        [indented(level, msg), @child&.tree(level + 1)]
+        [indented(level, msg), @next&.tree(level + 1)]
       end
     end
   end

data/lib/janeway/ast/current_node.rb

@@ -30,11 +30,7 @@ module Janeway
     # Construct accepts an optional Selector which will be applied to the "current" node
     class CurrentNode < Janeway::AST::Expression
       def to_s
-        if @value.is_a?(NameSelector) || @value.is_a?(WildcardSelector)
-          "@.#{@value.to_s(brackets: false)}"
-        else
-          "@#{@value}"
-        end
+        "@#{@value}"
       end
 
       # True if this is the root of a singular-query.
@@ -48,7 +44,7 @@ module Janeway
         selector = @value
         loop do
           selector_types << selector.class
-          selector = selector.child
+          selector = selector.next
           break unless selector
         end
         allowed = [AST::IndexSelector, AST::NameSelector]

data/lib/janeway/ast/descendant_segment.rb

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

data/lib/janeway/ast/filter_selector.rb

@@ -47,14 +47,20 @@ module Janeway
     #
     # @example: $.store[@.price < 10]
     class FilterSelector < Janeway::AST::Selector
-      def to_s(brackets: true)
-        brackets ? "[?#{value}]" : "?#{value}"
+      # @param brackets [Boolean] include brackets around selector
+      # ** ignores keyword arguments that don't apply to this selector
+      def to_s(brackets: true, **)
+        brackets ? "[?#{value}]#{@next}" : "?#{value}#{@next}"
       end
 
       # @param level [Integer]
       # @return [Array]
       def tree(level)
-        [indented(level, to_s)]
+        if @next
+          [indented(level, to_s), indented(level + 1, @next&.tree)]
+        else
+          [indented(level, to_s)]
+        end
       end
     end
   end

data/lib/janeway/ast/function.rb

@@ -8,7 +8,6 @@ module Janeway
 
       attr_reader :parameters, :body
 
-      # FIXME: provide function body too as a proc?
       def initialize(name, parameters, &body)
         raise ArgumentError, "expect string, got #{name.inspect}" unless name.is_a?(String)
 
@@ -35,6 +34,27 @@ module Janeway
       def singular_query?
         true
       end
+
+      # 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
+      end
+
+      # True if the function's return value is a boolean
+      # @return [Boolean]
+      def logical?
+        case name
+        when 'length', 'count', 'value' then false
+        when 'search', 'match' then true
+        else
+          raise "Unknown jsonpath function #{name}"
+        end
+      end
     end
   end
 end

data/lib/janeway/ast/identifier.rb

@@ -5,7 +5,7 @@ module Janeway
     class Identifier < Janeway::AST::Expression
       alias name value
 
-      # TODO: This list is incomplete. Complete after some aspects of the parser become clearer.
+      # Tokens which may follow an identifier string
       EXPECTED_NEXT_TOKENS = %I[
         \n
         +

data/lib/janeway/ast/index_selector.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'janeway'
 require_relative 'selector'
 
 module Janeway
@@ -7,19 +8,17 @@ module Janeway
     # An index selector, e.g. 3, selects an indexed child of an array
     # @example: $.store.book[2].title
     class IndexSelector < Janeway::AST::Selector
-      # These are the limits of what javascript's Number type can represent
-      MIN = -9_007_199_254_740_991
-      MAX = 9_007_199_254_740_991
-
       def initialize(index)
         raise Error, "Invalid value for index selector: #{index.inspect}" unless index.is_a?(Integer)
-        raise Error, "Index selector value too small: #{index.inspect}" if index < MIN
-        raise Error, "Index selector value too large: #{index.inspect}" if index > MAX
+        raise Error, "Index selector value too small: #{index.inspect}" if index < INTEGER_MIN
+        raise Error, "Index selector value too large: #{index.inspect}" if index > INTEGER_MAX
 
         super
       end
 
-      def to_s(brackets: true)
+      # @param brackets [Boolean] include brackets around selector
+      # ** ignores keyword arguments that don't apply to this selector
+      def to_s(brackets: true, **)
         brackets ? "[#{@value}]" : @value.to_s
       end
     end

data/lib/janeway/ast/name_selector.rb

@@ -14,22 +14,24 @@ module Janeway
 
       def initialize(value)
         super
-        # FIXME: implement name matching requirements here
         raise "Invalid name: #{value.inspect}:#{value.class}" unless value.is_a?(String)
       end
 
-      def to_s(brackets: false)
+      # @param bracket [Boolean] request for bracket syntax
+      # @param bracket [Boolean] include . prefix, if shorthand notation is used
+      def to_s(brackets: false, dot_prefix: true)
         # 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) }
-        name_str =
-          if brackets
-            quote(@value)
-          else
-            @value
-          end
-        brackets ? "[#{name_str}]#{@child}" : "#{name_str}#{@child}"
+        if brackets
+          name_str = quote(@value)
+          "[#{name_str}]#{@next}"
+        elsif dot_prefix
+          ".#{@value}#{@next}"
+        else # omit dot prefix after a descendant segment
+          "#{@value}#{@next}"
+        end
       end
 
       # put surrounding quotes on a string
@@ -45,7 +47,7 @@ module Janeway
       # @param level [Integer]
       # @return [Array]
       def tree(level)
-        [indented(level, "NameSelector:\"#{@value}\""), @child.tree(level + 1)]
+        [indented(level, "NameSelector:\"#{@value}\""), @next&.tree(level + 1)]
       end
     end
   end

data/lib/janeway/ast/number.rb

@@ -2,7 +2,7 @@
 
 module Janeway
   module AST
-    # Represent a number.  From the BNF grammer:
+    # Represent a number.  From the ABNF grammar:
     # number              = (int / "-0") [ frac ] [ exp ] ; decimal number
     # frac                = "." 1*DIGIT                  ; decimal fraction
     # exp                 = "e" [ "-" / "+" ] 1*DIGIT    ; decimal exponent

data/lib/janeway/ast/query.rb

@@ -2,18 +2,34 @@
 
 module Janeway
   module AST
-    # Syntactically, a JSONPath query consists of a root identifier ($),
-    # which stands for a nodelist that contains the root node of the
-    # query argument, followed by a possibly empty sequence of segments.
+    # AST::Query holds the complete abstract syntax tree created by parsing the query.
+    #
+    # This can be frozen and passed to multiple threads or ractors for simultaneous use.
+    # No instance members are modified during the interpretation stage.
     class Query
-      attr_accessor :root
+      # @return [AST::RootNode]
+      attr_reader :root
+
+      # The original jsonpath query, for use in error messages
+      # @return [String]
+      attr_reader :jsonpath
+
+      # @param root_node [AST::Root]
+      # @param jsonpath [String]
+      def initialize(root_node, jsonpath)
+        raise ArgumentError, "expect root identifier, got #{root_node.inspect}" unless root_node.is_a?(RootNode)
+        raise ArgumentError, "expect query string, got #{jsonpath.inspect}" unless jsonpath.is_a?(String)
+
+        @root = root_node
+        @jsonpath = jsonpath
+      end
 
       # Use this Query to search the input, and return the results.
       #
       # @param input [Object] ruby object to be searched
       # @return [Array] all matched objects
-      def find_all(object)
-        Janeway::Interpreter.new(input).interpret(self)
+      def find_all(input)
+        Janeway::Interpreter.new(self).interpret(input)
       end
 
       def to_s

data/lib/janeway/ast/root_node.rb

@@ -15,11 +15,7 @@ module Janeway
     #
     class RootNode < Janeway::AST::Expression
       def to_s
-        if @value.is_a?(NameSelector) || @value.is_a?(WildcardSelector)
-          "$.#{@value}"
-        else
-          "$#{@value}"
-        end
+        "$#{@value}"
       end
 
       # True if this is the root of a singular-query.
@@ -33,7 +29,7 @@ module Janeway
         selector = @value
         loop do
           selector_types << selector.class
-          selector = selector.child
+          selector = selector.next
           break unless selector
         end
         allowed = [AST::IndexSelector, AST::NameSelector]

data/lib/janeway/ast/selector.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'expression'
+
 # https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-base/blob/main/draft-ietf-jsonpath-base.md#selectors
 # Selectors:
 #
@@ -22,7 +24,8 @@ module Janeway
   module AST
     # Represent a selector, which is an expression that filters nodes from a list based on a predicate.
     class Selector < Janeway::AST::Expression
-      attr_accessor :child
+      # Subsequent expression that modifies the result of this selector list.
+      attr_accessor :next
 
       def ==(other)
         value == other&.value

data/lib/janeway/ast/wildcard_selector.rb

@@ -17,29 +17,25 @@ module Janeway
     # It has only one possible value: '*'
     # @example: $.store.book[*]
     class WildcardSelector < Janeway::AST::Selector
-      attr_accessor :child
-
       def initialize
         super
-        @child = nil
+        @next = nil
       end
 
-      def to_s(brackets: true)
-        if @child.is_a?(NameSelector) || @child.is_a?(WildcardSelector)
-          if brackets
-            "[*]#{@child.to_s(brackets: true)}"
-          else
-            "*.#{@child}"
-          end
+      def to_s(brackets: false, dot_prefix: true)
+        if brackets
+          "[*]#{@next&.to_s(brackets: true)}"
+        elsif dot_prefix
+          ".*#{@next}"
         else
-          "*#{@child}"
+          "*#{@next}"
         end
       end
 
       # @param level [Integer]
       # @return [Array]
       def tree(level)
-        [indented(level, '*'), @child.tree(level + 1)]
+        [indented(level, '*'), @next.tree(level + 1)]
       end
     end
   end

data/lib/janeway/error.rb

@@ -15,9 +15,15 @@ module Janeway
     # @param query [String] entire query string
     # @param location [Location] location of error
     def initialize(message, query = nil, location = nil)
-      super(message)
+      super("Jsonpath query #{query} - #{message}")
       @query = query
       @location = location
     end
+
+    def detailed_message
+      msg = "Error: #{message}\nQuery: #{query}\n"
+      msg += (' ' * location.col) + '^' if @location
+      msg
+    end
   end
 end

data/lib/janeway/functions/count.rb

@@ -24,14 +24,19 @@ module Janeway
       consume # (
 
       # Read parameter
-      parameters = [parse_function_parameter]
-      raise "expect group_end token, found #{current}" unless current.type == :group_end
+      arg = parse_function_parameter
+      parameters = [arg]
+      raise Error, "Invalid parameter - count() expects node list, got #{arg.value.inspect}" if arg.literal?
+      unless current.type == :group_end
+        raise Error, 'Too many parameters for count() function call'
+      end
 
+      # Define function body
       AST::Function.new('count', parameters) do |node_list|
         if node_list.is_a?(Array)
           node_list.size
         else
-          1
+          1 # The count of a non-empty singulare noselist such as count(@) is always 1
         end
       end
     end

data/lib/janeway/functions/length.rb

@@ -13,8 +13,14 @@ module Janeway
       consume # (
 
       # Read parameter
-      parameters = [parse_function_parameter]
-      raise "expect group_end token, found #{current}" unless current.type == :group_end
+      arg = parse_function_parameter
+      parameters = [arg]
+      unless arg.singular_query? || arg.literal?
+        raise Error, "Invalid parameter - length() expects literal value or singular query, got #{arg.value.inspect}"
+      end
+      unless current.type == :group_end
+        raise Error, 'Too many parameters for length() function call'
+      end
 
       # Meaning of return value depends on the JSON type:
       #   * string - number of Unicode scalar values in the string.

data/lib/janeway/functions/match.rb

@@ -46,7 +46,7 @@ module Janeway
       if current.type == :union
         consume # ,
       else
-        raise "expect comma token, found #{current}" 
+        raise Error, 'Not enough parameters for match() function call'
       end
 
       # Read second parameter (the regexp)
@@ -54,7 +54,9 @@ module Janeway
       # Otherwise it is an expression that takes the regexp from the input document,
       # and the iregexp will not be available until interpretation.
       parameters << parse_function_parameter
-      raise "expect group_end token, found #{current}" unless current.type == :group_end
+      unless current.type == :group_end
+        raise Error, 'Too many parameters for match() function call'
+      end
 
       AST::Function.new('match', parameters) do |str, str_iregexp|
         if str.is_a?(String) && str_iregexp.is_a?(String)

data/lib/janeway/functions/search.rb

@@ -40,7 +40,7 @@ module Janeway
       if current.type == :union
         consume # ,
       else
-        raise "expect comma token, found #{current}" 
+        raise Error, 'Insufficient parameters for search() function call'
       end
 
       # Read second parameter (the regexp)
@@ -48,7 +48,9 @@ module Janeway
       # Otherwise it is an expression that takes the regexp from the input document,
       # and the iregexp will not be available until interpretation.
       parameters << parse_function_parameter
-      raise "expect group_end token, found #{current}" unless current.type == :group_end
+      unless current.type == :group_end
+        raise Error, 'Too many parameters for match() function call'
+      end
 
       AST::Function.new('search', parameters) do |str, str_iregexp|
         if str.is_a?(String) && str_iregexp.is_a?(String)