janeway-jsonpath 0.1.0

data/lib/janeway/ast/filter_selector.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative 'selector'
+
+# https://datatracker.ietf.org/doc/rfc9535/
+
+module Janeway
+  module AST
+    # Filter selectors are used to iterate over the elements or members of
+    # structured values, i.e., JSON arrays and objects.  The structured
+    # values are identified in the nodelist offered by the child or
+    # descendant segment using the filter selector.
+
+    # For each iteration (element/member), a logical expression (the
+    # _filter expression_) is evaluated, which decides whether the node of
+    # the element/member is selected.  (While a logical expression
+    # evaluates to what mathematically is a Boolean value, this
+    # specification uses the term _logical_ to maintain a distinction from
+    # the Boolean values that JSON can represent.)
+
+    # During the iteration process, the filter expression receives the node
+    # of each array element or object member value of the structured value
+    # being filtered; this element or member value is then known as the
+    # _current node_.
+
+    # The current node can be used as the start of one or more JSONPath
+    # queries in subexpressions of the filter expression, notated via the
+    # current-node-identifier @. Each JSONPath query can be used either for
+    # testing existence of a result of the query, for obtaining a specific
+    # JSON value resulting from that query that can then be used in a
+    # comparison, or as a _function argument_.
+
+    # Filter selectors may use function extensions, which are covered in
+    # Section 2.4.  Within the logical expression for a filter selector,
+    # function expressions can be used to operate on nodelists and values.
+    # The set of available functions is extensible, with a number of
+    # functions predefined (see Section 2.4) and the ability to register
+    # further functions provided by the "Function Extensions" subregistry
+    # (Section 3.2).  When a function is defined, it is given a unique
+    # name, and its return value and each of its parameters are given a
+    # _declared type_. The type system is limited in scope; its purpose is
+    # to express restrictions that, without functions, are implicit in the
+    # grammar of filter expressions.  The type system also guides
+    # conversions (Section 2.4.2) that mimic the way different kinds of
+    # expressions are handled in the grammar when function expressions are
+    # not in use.
+    #
+    # @example: $.store[@.price < 10]
+    class FilterSelector < Janeway::AST::Selector
+      def to_s(brackets: true)
+        brackets ? "[?#{value}]" : "?#{value}"
+      end
+
+      # @param level [Integer]
+      # @return [Array]
+      def tree(level)
+        [indented(level, to_s)]
+      end
+    end
+  end
+end

data/lib/janeway/ast/function.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Janeway
+  module AST
+    # Represents a JSONPath built-in function.
+    class Function < Janeway::AST::Expression
+      alias name value
+
+      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)
+
+        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
+        "#{name}(#{@parameters.join(',')})"
+      end
+
+      # @param level [Integer]
+      # @return [Array]
+      def tree(level)
+        [indented(level, to_s)]
+      end
+
+      # True if this is the root of a singular-query.
+      # @see https://www.rfc-editor.org/rfc/rfc9535.html#name-well-typedness-of-function-
+      #
+      # @return [Boolean]
+      def singular_query?
+        true
+      end
+    end
+  end
+end

data/lib/janeway/ast/helpers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Janeway
+  module AST
+    module Helpers
+      # @param str [String] ascii string, CamelCase
+      # @return [String] lowercase, with underscores
+      def self.camelcase_to_underscore(str)
+        found_uppercase = false
+        chars = []
+        str.each_char do |char|
+          if char.ord.between?(65, 90) # ascii 'A'..'Z' inclusive
+            chars << '_'
+            chars << (char.ord + 32).chr
+            found_uppercase = true
+          else
+            chars << char
+          end
+        end
+        return str unless found_uppercase
+
+        chars.shift if chars.first == '_'
+        chars.join
+      end
+    end
+  end
+end

data/lib/janeway/ast/identifier.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Janeway
+  module AST
+    class Identifier < Janeway::AST::Expression
+      alias name value
+
+      # TODO: This list is incomplete. Complete after some aspects of the parser become clearer.
+      EXPECTED_NEXT_TOKENS = %I[
+        \n
+        +
+        -
+        *
+        /
+        ==
+        !=
+        >
+        <
+        >=
+        <=
+        &&
+        ||
+      ].freeze
+
+      # @return [String]
+      def to_s
+        @value
+      end
+
+      def expects?(next_token)
+        EXPECTED_NEXT_TOKENS.include?(next_token)
+      end
+    end
+  end
+end

data/lib/janeway/ast/index_selector.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'selector'
+
+module Janeway
+  module AST
+    # 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
+
+        super
+      end
+
+      def to_s(brackets: true)
+        brackets ? "[#{@value}]" : @value.to_s
+      end
+    end
+  end
+end

data/lib/janeway/ast/name_selector.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative 'selector'
+
+module Janeway
+  module AST
+    # A name selector, e.g. 'name', selects a named child of an object.
+    # @example
+    #   $.store
+    #   $[store]
+    # The dot or bracket part is not captured here, only the name
+    class NameSelector < Janeway::AST::Selector
+      alias name value
+
+      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)
+        # 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}"
+      end
+
+      # put surrounding quotes on a string
+      # @return [String]
+      def quote(str)
+        if str.include?("'")
+          format('"%s"', str)
+        else
+          "'#{str}'"
+        end
+      end
+
+      # @param level [Integer]
+      # @return [Array]
+      def tree(level)
+        [indented(level, "NameSelector:\"#{@value}\""), @child.tree(level + 1)]
+      end
+    end
+  end
+end

data/lib/janeway/ast/null.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Janeway
+  module AST
+    class Null < Janeway::AST::Expression
+      def to_s
+        'null'
+      end
+
+      # @param level [Integer]
+      # @return [Array]
+      def tree(level = 0)
+        indented(level, 'null')
+      end
+
+      # Return true if this is a literal expression
+      # @return [Boolean]
+      def literal?
+        true
+      end
+    end
+  end
+end

data/lib/janeway/ast/number.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Janeway
+  module AST
+    # Represent a number.  From the BNF grammer:
+    # number              = (int / "-0") [ frac ] [ exp ] ; decimal number
+    # frac                = "." 1*DIGIT                  ; decimal fraction
+    # exp                 = "e" [ "-" / "+" ] 1*DIGIT    ; decimal exponent
+    class Number < Janeway::AST::Expression
+      def to_s
+        @value.to_s
+      end
+
+      # Return true if this is a literal expression
+      # @return [Boolean]
+      def literal?
+        true
+      end
+    end
+  end
+end

data/lib/janeway/ast/query.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+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.
+    class Query
+      attr_accessor :root
+
+      # 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)
+      end
+
+      def to_s
+        @root.to_s
+      end
+
+      # Queries are considered equal if their ASTs evaluate to the same JSONPath string.
+      #
+      # The string output is generated by the AST and should be considered a "normalized"
+      # form of the query. It may have different whitespace and parentheses than the original
+      # input but will be semantically equivalent.
+      def ==(other)
+        to_s == other.to_s
+      end
+
+      # Print AST in tree format
+      # Every AST class prints a 1-line representation of self, with children on separate lines
+      def tree
+        result = @root.tree(0)
+
+        result.flatten.join("\n")
+      end
+    end
+  end
+end

data/lib/janeway/ast/root_node.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Janeway
+  module AST
+    # Every JSONPath query (except those inside filter expressions; see Section
+    # 2.3.5) MUST begin with the root identifier $.
+    #
+    # The root identifier $ represents the root node of the query argument and produces
+    # a nodelist consisting of that root node.
+    #
+    # The root identifier may also be used in the filter selectors.
+    #
+    # @example:
+    #   $(? $.key1 == $.key2 )
+    #
+    class RootNode < Janeway::AST::Expression
+      def to_s
+        if @value.is_a?(NameSelector) || @value.is_a?(WildcardSelector)
+          "$.#{@value}"
+        else
+          "$#{@value}"
+        end
+      end
+
+      # True if this is the root of a singular-query.
+      # @see https://www.rfc-editor.org/rfc/rfc9535.html#name-well-typedness-of-function-
+      #
+      # @return [Boolean]
+      def singular_query?
+        return true unless @value # there are no following selectors
+
+        selector_types = []
+        selector = @value
+        loop do
+          selector_types << selector.class
+          selector = selector.child
+          break unless selector
+        end
+        allowed = [AST::IndexSelector, AST::NameSelector]
+        selector_types.uniq.all? { allowed.include?(_1) }
+      end
+
+      # @param level [Integer]
+      # @return [Array]
+      def tree(level = 0)
+        [indented(level, '$'), @value.tree(level + 1)]
+      end
+    end
+  end
+end

data/lib/janeway/ast/selector.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-base/blob/main/draft-ietf-jsonpath-base.md#selectors
+# Selectors:
+#
+# A name selector, e.g. 'name', selects a named child of an object.
+#
+# An index selector, e.g. 3, selects an indexed child of an array.
+#
+# A wildcard * ({{wildcard-selector}}) in the expression [*] selects all
+# children of a node and in the expression ..[*] selects all descendants of a
+# node.
+#
+# An array slice start:end:step ({{slice}}) selects a series of elements from
+# an array, giving a start position, an end position, and an optional step
+# value that moves the position from the start to the end.
+#
+# Filter expressions ?<logical-expr> select certain children of an object or array, as in:
+#
+# $.store.book[?@.price < 10].title
+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
+
+      def ==(other)
+        value == other&.value
+      end
+    end
+  end
+end

data/lib/janeway/ast/string_type.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Janeway
+  module AST
+    class StringType < Janeway::AST::Expression
+      def to_s
+        if @value.include?("'")
+          %("#{@value}"')
+        else
+          "'#{@value}'"
+        end
+      end
+
+      # Return true if this is a literal expression
+      # @return [Boolean]
+      def literal?
+        true
+      end
+    end
+  end
+end

data/lib/janeway/ast/unary_operator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Janeway
+  module AST
+    # Represent unary operators "!", "-"
+    class UnaryOperator < Janeway::AST::Expression
+      attr_accessor :operator, :operand
+
+      def initialize(operator, operand = nil)
+        super()
+        @operator = operator
+        @operand = operand
+      end
+
+      def to_s
+        "#{@operator} #{operand}"
+      end
+
+      # @param level [Integer]
+      # @return [Array]
+      def tree(level)
+        indented(level, "#{operator}#{operand}")
+      end
+    end
+  end
+end

data/lib/janeway/ast/wildcard_selector.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'selector'
+
+module Janeway
+  module AST
+    # A wildcard selector selects the nodes of all children of an object
+    # or array. The order in which the children of an object appear in
+    # the resultant nodelist is not stipulated, since JSON objects are
+    # unordered. Children of an array appear in array order in the
+    # resultant nodelist.
+    #
+    # Note that the children of an object are its member values, not its member names/keys.
+    #
+    # The wildcard selector selects nothing from a primitive JSON value (ie. a number, a string, true, false, or null).
+    #
+    # It has only one possible value: '*'
+    # @example: $.store.book[*]
+    class WildcardSelector < Janeway::AST::Selector
+      attr_accessor :child
+
+      def initialize
+        super
+        @child = 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
+        else
+          "*#{@child}"
+        end
+      end
+
+      # @param level [Integer]
+      # @return [Array]
+      def tree(level)
+        [indented(level, '*'), @child.tree(level + 1)]
+      end
+    end
+  end
+end

data/lib/janeway/error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'location'
+
+module Janeway
+  # Base class for JSONPath query errors
+  class Error < StandardError
+    # @return [String]
+    attr_reader :query
+
+    # @return [Location, nil]
+    attr_reader :location
+
+    # @param message [String] error message
+    # @param query [String] entire query string
+    # @param location [Location] location of error
+    def initialize(message, query = nil, location = nil)
+      super(message)
+      @query = query
+      @location = location
+    end
+  end
+end

data/lib/janeway/functions/count.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Janeway
+  # Mixin to provide JSONPath function handlers for Parser
+  module Functions
+    # The count() function extension provides a way to obtain the number of
+    # nodes in a nodelist and make that available for further processing in
+    # the filter expression:
+    #
+    # Its only argument is a nodelist. The result is a value (an unsigned
+    # integer) that gives the number of nodes in the nodelist.
+    #
+    # Notes:
+    #   * There is no deduplication of the nodelist.
+    #   * The number of nodes in the nodelist is counted independent of
+    #     their values or any children they may have, e.g., the count of a
+    #     non-empty singular nodelist such as count(@) is always 1.
+    #
+    # @example $[?count(@.*.author) >= 5]
+    def parse_function_count
+      consume # function
+      raise "expect group_start token, found #{current}" unless current.type == :group_start
+
+      consume # (
+
+      # Read parameter
+      parameters = [parse_function_parameter]
+      raise "expect group_end token, found #{current}" unless current.type == :group_end
+
+      AST::Function.new('count', parameters) do |node_list|
+        if node_list.is_a?(Array)
+          node_list.size
+        else
+          1
+        end
+      end
+    end
+  end
+end

data/lib/janeway/functions/length.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Janeway
+  module Functions
+    # The length() function extension provides a way to compute the length of a value
+    # and make that available for further processing in the filter expression:
+    #
+    # JSONPath return type: ValueType
+    def parse_function_length
+      consume # function
+      raise "expect group_start token, found #{current}" unless current.type == :group_start
+
+      consume # (
+
+      # Read parameter
+      parameters = [parse_function_parameter]
+      raise "expect group_end token, found #{current}" unless current.type == :group_end
+
+      # Meaning of return value depends on the JSON type:
+      #   * string - number of Unicode scalar values in the string.
+      #   * array -  number of elements in the array.
+      #   * object - number of members in the object.
+      # For any other argument value, the result is the special result Nothing.
+      AST::Function.new('length', parameters) do |value|
+        if [Array, Hash, String].include?(value.class)
+          value.size
+        else
+          :nothing
+        end
+      end
+    end
+  end
+end

data/lib/janeway/functions/match.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Janeway
+  # Mixin to provide JSONPath function handlers for Parser
+  module Functions
+    # The match() function extension provides a way to check whether (the
+    # entirety of; see Section 2.4.7) a given string matches a given regular
+    # expression, which is in the form described in [RFC9485].
+    #
+    # @example  $[?match(@.date, "1974-05-..")]
+    #
+    # Its arguments are instances of ValueType (possibly taken from a
+    # singular query, as for the first argument in the example above). If the
+    # first argument is not a string or the second argument is not a string
+    # conforming to [RFC9485], the result is LogicalFalse. Otherwise, the
+    # string that is the first argument is matched against the I-Regexp
+    # contained in the string that is the second argument; the result is
+    # LogicalTrue if the string matches the I-Regexp and is LogicalFalse
+    # otherwise.
+    #
+    #
+    # The regexp dialect is called "I-Regexp" and is defined in RFC9485.
+    #
+    # Fortunately a shortcut is availalble, that RFC contains instructions
+    # for converting an I-Regexp to ruby's regexp format.
+    # @see https://www.rfc-editor.org/rfc/rfc9485.html#name-pcre-re2-and-ruby-regexps
+    #
+    # The instructions are:
+    #   * For any unescaped dots (.) outside character classes (first
+    #     alternative of charClass production), replace the dot with [^\n\r].
+    #   * Enclose the regexp in \A(?: and )\z.
+    #
+    # tl;dr: How is this different from the search function?
+    # "match" must match the entire string, "search" matches a substring.
+    def parse_function_match
+      consume # function
+      raise "expect group_start token, found #{current}" unless current.type == :group_start
+
+      consume # (
+
+      # Read first parameter
+      parameters = []
+      parameters << parse_function_parameter
+
+      # Consume comma
+      if current.type == :union
+        consume # ,
+      else
+        raise "expect comma token, found #{current}" 
+      end
+
+      # Read second parameter (the regexp)
+      # This could be a string, in which case it is available now.
+      # 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
+
+      AST::Function.new('match', parameters) do |str, str_iregexp|
+        if str.is_a?(String) && str_iregexp.is_a?(String)
+          regexp = translate_iregex_to_ruby_regex(str_iregexp)
+          regexp.match?(str)
+        else
+          false # result defined by RFC9535
+        end
+      end
+    end
+  end
+end