janeway-jsonpath 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 210bad818f98217873f0055d2ed46432b2b56087442e371671c22f00e51ff0f8
-  data.tar.gz: 1a2fd7d80573323fb3cb6c6b8c28ddf5182585bf05cd2540816d29faf637ed87
+  metadata.gz: 33fc9254c0443121404ced6b9e60c15133111299b8f7052f012fe45d7ad4d281
+  data.tar.gz: c5a9eea01a8a332343b47328c64991a52fc50292969247433650914c8af727bd
 SHA512:
-  metadata.gz: 35c927af0528d849acf86691fb7b2fa0ec16d69ce6819ad37f231b3918394f9459ceb7ec4340cb65cf4feb48792c251317af111072bb8e23f8cc2d8da6407cf1
-  data.tar.gz: 22337b8703744e1428632635dcfb1eb25c57042d069b37ecf0ee0b13b70554d2b5fd1c3bc59af75f4ec0d4a23876e8aeb1421bc35c82ed8b652c0ac3ff0baf4a
+  metadata.gz: 0c101d0e02380fc56bd4abc83b5012965e3281aabc3bcce10e7f55c6cff61ba5b825f0d582f95c076234e01d59f07a8db19e6b8984c85e923c780d6f362adc2c
+  data.tar.gz: e2a762c773653c01415dee8f988b95be53d45da8bb3d1ed6f20817eb333fce00b3c960f9268a2212c929a27582d4c0cdb8e480e3948b2e193974f452b32e526f

data/README.md

@@ -126,7 +126,7 @@ Returns all values that match the query.
     # Returns every book in the store cheaper than $10
 ```
 
-Alternatively, compile the query once, and share it between threads or ractors with different data sources:
+Alternatively, parse the query once, and share it between threads or ractors with different data sources:
 
 ```ruby
     # Create ractors with their own data sources
@@ -140,7 +140,7 @@ Alternatively, compile the query once, and share it between threads or ractors w
       end
 
     # Construct JSONPath query object and send it to each ractor
-    query = Janeway.compile('$..book[? @.price<10]')
+    query = Janeway.parse('$..book[? @.price<10]')
     ractors.each { |ractor| ractor.send(query).take }
 ```
 
@@ -192,7 +192,7 @@ For example, iterating over an array may yield index values 1, 2 and 3.
 Deleting the value at index 1 would change the index for the remaining values.
 Next iteration might yield index 2, but since 1 was deleted it is now really at index 1.
 
-To avoid having to deal with such problems, use the built in `#delete` method below.
+To avoid having to deal with such problems, use the `#delete` method instead.
 
 
 Lastly, the `#each` iterator's fourth yield parameter is the [normalized path](https://www.rfc-editor.org/rfc/rfc9535.html#name-normalized-paths) to the matched value.
@@ -205,8 +205,10 @@ This is a jsonpath query string that uniquely points to the matched value.
         paths << path
     end
     paths
-    # [ #  "$['birds']", "$['dogs']", "$['birds'][0]", "$['birds'][1]", "$['birds'][2]",
-    #  "$['dogs'][0]", "$['dogs'][1]", "$['dogs'][2]"]
+    #  [
+    #    "$['birds']", "$['dogs']", "$['birds'][0]", "$['birds'][1]",
+    #    "$['birds'][2]", "$['dogs'][0]", "$['dogs'][1]", "$['dogs'][2]"
+    #  ]
 ```
 
 ##### #delete
@@ -222,6 +224,82 @@ The `#delete` method deletes matched values from the input.
     # dog list is now []
 ```
 
+##### #delete_if
+
+The `#delete_if` method yields matched values to a block, and deletes them if the block returns a truthy result.
+This allows values to be deleted based on conditions that can't be tested by a JSONPath query:
+```ruby
+    # delete any book from the store json data that is not in the database
+    Janeway.enum_for('$.store.book.*', data).delete_if do |book|
+        results = db.query('SELECT * FROM books WHERE author=? AND title=?', book['author'], book['title'])
+        results.size == 0
+    end
+```
+
+##### #replace
+
+Replaces every value matched by the query with the given value.
+The replacement does not need to be the same type (eg. you can replace a string value with Hash or nil.)
+
+Alternatively, provide a block which receives the value and returns a replacement value.
+
+```ruby
+    # Set every price to nil
+    Janeway.enum_for('$..price', data).replace(nil)
+
+    # Suppose the prices were serialized as strings, eg. "price" => "9.99"
+    # Convert them to floating point values:
+    Janeway.enum_for('$..price', data).replace { |price| price.to_f }
+
+    # Same thing, but using more terse ruby:
+    Janeway.enum_for('$..price', data).replace(&:to_f)
+
+    # Convert price to hash:
+    Janeway.enum_for('$..price', data).replace do |price|
+        {
+          'price' => price.to_f,
+          'currency' => 'CAD',
+        }
+    end
+```
+
+##### #insert
+
+Adds the given value to the input data, at the place specified by the JSONPath query.
+
+The query must be a singular query, meaning it can only be made of of name selectors (hash keys) and index selectors (array indexes.)
+The normalized paths which are yielded to `#each` are usable here.
+Examples of singular queries:
+```
+    $.store.book.0.price
+    $['store']['book'][0]
+```
+Examples of queries that are valid JSONPath but are not useable here:
+```
+    $.store.book.*
+    $.store.book[1:2]
+    $.store.book[? @.price >= 8.99]
+```
+
+Additionally, some other restrictions apply:
+   * The "parent" node must exist, eg. for `$.a[1].name`, the path `$.a[1]` must exist and be a Hash
+   * Cannot create array index `n` unless the array contains exactly `n-1` elements
+   * If query path already exists, the block is called if provided. Otherwise an exception is raised.
+
+Here is an example of adding a new book to the store:
+```ruby
+    # Add a new book to the store
+    book_count = data['store']['book'].size
+    Janeway.enum_for("$.store.book[#{book_count}]", data).insert do
+      { "category": "fiction",
+        "author": "Kameron Hurley",
+        "title": "The Light Brigade",
+        "price": 33.11
+      }
+    end
+```
+
+#### Ruby Enumerable module methods
 
 The `Janeway.enum_for` and `Janeway::Query#enum_for` methods return an enumerator, so you can use the usual ruby enumerator methods, such as:
 

data/bin/janeway

@@ -15,25 +15,30 @@ HELP = <<~HELP_TEXT.freeze
     #{SCRIPT_NAME} [QUERY] [FILENAME]
 
   Purpose:
-    Print the result of applying a JSONPath query to a JSON input.
+    Print values from the input data that match the given JSONPath query.
+
+    Alternatively, use one of the action flags to modify values from the input JSON specified by the query.
 
     QUERY is a JSONPath query. Quote it with single quotes to avoid shell errors.
 
-    FILENAME is the path to a JSON file to use as input.
-    Alternately, input JSON can be provided on STDIN.
-    If input is not provided then the query is just checked for correctness.
+    FILENAME is the path to a JSON file to use as input data.
+    Alternately, JSON can be provided on STDIN.
+    If data is not provided then the query is just checked for correctness.
 
     For an introduction to JSONPath, see https://goessner.net/articles/JsonPath/
     For the complete reference, see https://www.rfc-editor.org/info/rfc9535
 
   Examples:
-    #{SCRIPT_NAME} '$.store.book[*].author' input.json
-    cat input.json | #{SCRIPT_NAME} '$.store.book[*].author'
+    #{SCRIPT_NAME} '$.store.book[*].author' data.json
+    cat data.json | #{SCRIPT_NAME} '$.store.book[*].author'
 
 HELP_TEXT
 
 # Command-line options
-Options = Struct.new(:query, :query_file, :input, :compact_output, :delete, :verbose)
+Options = Struct.new(
+  :query, :query_file, :action, :value, :value_given, :data,
+  :compact_output, :verbose, keyword_init: true
+)
 
 # Parse the command-line arguments.
 # This includes both bare words and hyphenated options.
@@ -44,9 +49,12 @@ def parse_args(argv)
   argv << '--help' if argv.empty?
   options = parse_options(argv)
 
-  # Next get jsonpath query and input jsonn
+  # Get jsonpath query and input json
   options.query = read_query(options.query_file, argv)
-  options.input = read_input(argv.first)
+  options.data = read_input(argv.first)
+  if %i[insert replace].include?(options.action) && !options.value_given
+    abort("Need value for #{options.action}, use -v or -V")
+  end
   options
 end
 
@@ -54,14 +62,29 @@ end
 #
 # @param argv [Array<String>]
 def parse_options(argv)
-  options = Options.new
+  options = Options.new(action: :search)
   op = OptionParser.new do |opts|
     opts.banner = HELP
     opts.separator('Options:')
 
     opts.on('-q', '--query FILE', 'Read jsonpath query from file') { |o| options.query_file = o }
-    opts.on('-c', '--compact', 'Express result in compact json format') { options.compact_output = true }
-    opts.on('-d', '--delete', 'Print the input, with matching values deleted') { options.delete = true }
+    opts.on('-c', '--compact', 'Print result in compact json format') { options.compact_output = true }
+    opts.on('-v', '--value STRING', 'VALUE for insert or replace (str/number/null/true/false)') do |o|
+      options.value = read_value(o)
+      options.value_given = true # must track this separately since value may be false / nil
+    end
+    desc =
+      'JSON file containing VALUE for insert or replace ' \
+      '(bare literals are valid JSON, eg. 9, "string", null)'
+    opts.on('-V', '--value-file FILENAME', desc) do |o|
+      options.value = read_value_file(o)
+      options.value_given = true
+    end
+    opts.separator('Actions:')
+    opts.on('-d', '--delete', 'Print data, with matches deleted') { options.action = :delete }
+    opts.on('-r', '--replace', 'Print data, with matches replaced by VALUE') { options.action = :replace }
+    opts.on('-i', '--insert', 'Print data, with VALUE inserted at query location') { options.action = :insert }
+    opts.on('-p', '--paths', 'List normalized path for each match') { options.action = :paths }
     opts.on('--version', 'Show version number') { abort(Janeway::VERSION) }
     opts.on('-h', '--help', 'Show this help message') { abort(opts.to_s) }
   end
@@ -99,43 +122,69 @@ def read_input(path)
   parse_json(json)
 end
 
+# Read insert/replacement value from file
+# @return [Array,Hash,String,Numeric,nil]
+def read_value_file(path)
+  abort("File not readable: #{path}") unless File.exist?(path)
+
+  parse_json File.read(path)
+end
+
+# Read insert/replacement value from command-line argument
+# @return [Integer, Float, String]
+def read_value(value_str)
+  case value_str
+  when 'null' then nil
+  when 'true' then true
+  when 'false' then false
+  when /^\d+$/ then value_str.to_i # integer
+  when /^\d+\.\d+$/ then value_str.to_f # float
+  else value_str # string
+  end
+end
+
 # Parse JSON, and abort if it is invalid
 # @param json [String]
 # @return [Hash, Array] un-serialized json, as ruby objects
 def parse_json(json)
   JSON.parse(json)
 rescue JSON::JSONError => e
-  # JSON error messages may include the entire input, so limit how much is printed.
+  # JSON error messages may include the entire data, so limit how much is printed.
   msg = e.message[0..256]
   msg += "\n..." if e.message.length > 256
-  abort "Input is not valid JSON: #{msg}"
+  abort "Input data is not valid JSON: #{msg}"
 end
 
 # Just pares the query ane then exit.
 # Useful for testing whether a query is valid.
 # @param query [String] jsonpath
 def parse_query_and_exit(query)
-  Janeway.compile(query)
+  Janeway.parse(query)
   puts 'Query is valid. Provide input json to run the query.'
   exit(0)
 end
 
 # @param options [Options]
 def main(options)
-  parse_query_and_exit(options.query) unless options.input
-
-  enum = Janeway.enum_for(options.query, options.input)
-  if options.delete
-    results = enum.delete
-    if options.compact_output
-      puts JSON.generate(options.input)
+  parse_query_and_exit(options.query) unless options.data
+
+  enum = Janeway.enum_for(options.query, options.data)
+  results =
+    case options.action
+    when :search then enum.search
+    when :paths then enum.map { |_, _, _, path| path }
+    when :replace
+      enum.replace(options.value)
+      options.data
+    when :insert
+      enum.insert(options.value)
+      options.data
+    when :delete
+      enum.delete
+      options.data
     else
-      puts JSON.pretty_generate(options.input)
+      raise "Unknown action: #{options.action}"
     end
-    exit(0)
-  else
-    results = enum.search
-  end
 
   if options.compact_output
     puts JSON.generate(results)
@@ -149,7 +198,7 @@ begin
   main(options)
 rescue Janeway::Error => e
   warn "Error: #{e.message}\nQuery: #{e.query}\n"
-  warn "       #{' ' * e.location.col}^" if e.location
+  warn "       #{' ' * e.location.col}^" if e.location # point to the character at the location index
   exit(1)
 rescue Interrupt, Errno::EPIPE
   abort("\n")

data/lib/janeway/ast/child_segment.rb

@@ -2,16 +2,17 @@
 
 require 'forwardable'
 
-# A set of selectors within brackets, as a comma-separated list.
-# https://www.rfc-editor.org/rfc/rfc9535.html#child-segment
-#
-# @example
-#    $[*, *]
-#    $[1, 2, 3]
-#    $[name1, [1:10]]
 module Janeway
   module AST
     # Represent a union of 2 or more selectors.
+    #
+    # A set of selectors within brackets, as a comma-separated list.
+    # https://www.rfc-editor.org/rfc/rfc9535.html#child-segment
+    #
+    # @example
+    #    $[*, *]
+    #    $[1, 2, 3]
+    #    $[name1, [1:10]]
     class ChildSegment < Janeway::AST::Expression
       extend Forwardable
       def_delegators :@value, :size, :first, :last, :each, :map, :empty?

data/lib/janeway/ast/filter_selector.rb

@@ -2,8 +2,6 @@
 
 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

data/lib/janeway/ast/function.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'expression'
+
 module Janeway
   module AST
     # Represents a JSONPath built-in function.

data/lib/janeway/ast/selector.rb

@@ -2,27 +2,26 @@
 
 require_relative 'expression'
 
-# 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.
+    #
+    # https://www.rfc-editor.org/rfc/rfc9535.html#name-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 * 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 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
     class Selector < Janeway::AST::Expression
       # Subsequent expression that modifies the result of this selector list.
       attr_accessor :next

data/lib/janeway/ast.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Janeway
+  # Abstract Syntax Tree
+  module AST
+    # These are the limits of what javascript's Number type can represent
+    INTEGER_MIN = -9_007_199_254_740_991
+    INTEGER_MAX = 9_007_199_254_740_991
+  end
+end
+
+require_relative 'ast/array_slice_selector'
+require_relative 'ast/binary_operator'
+require_relative 'ast/boolean'
+require_relative 'ast/child_segment'
+require_relative 'ast/current_node'
+require_relative 'ast/descendant_segment'
+require_relative 'ast/error'
+require_relative 'ast/expression'
+require_relative 'ast/filter_selector'
+require_relative 'ast/function'
+require_relative 'ast/helpers'
+require_relative 'ast/index_selector'
+require_relative 'ast/name_selector'
+require_relative 'ast/null'
+require_relative 'ast/number'
+require_relative 'ast/root_node'
+require_relative 'ast/selector'
+require_relative 'ast/string_type'
+require_relative 'ast/unary_operator'
+require_relative 'ast/wildcard_selector'

data/lib/janeway/enumerator.rb

@@ -1,12 +1,18 @@
 # frozen_string_literal: true
 
+require_relative 'interpreter'
+
 module Janeway
-  # Enumerator combines a parsed JSONpath query with input.
-  # It provides enumerator methods.
+  # Enumerator combines a JSONPath query with input.
+  # It provides methods for running queries on the input and enumerating over the results.
   class Enumerator
     include Enumerable
 
-    # @param query [Janeway::Query] @param input [Array, Hash]
+    # @return [Janeway::Query]
+    attr_reader :query
+
+    # @param query [Janeway::Query]
+    # @param input [Array, Hash]
     def initialize(query, input)
       @query = query
       @input = input
@@ -34,10 +40,151 @@ module Janeway
       Janeway::Interpreter.new(@query, as: :iterator, &block).interpret(@input)
     end
 
-    # Delete each value matched by the JSONPath query.
-    # @return [Array, Hash]
+    # Delete values from the input that are matched by the JSONPath query.
+    # @return [Array] deleted values
     def delete
       Janeway::Interpreter.new(@query, as: :deleter).interpret(@input)
     end
+
+    # Delete values from the input that are matched by the JSONPath query and also return a truthy value
+    # from the block.
+    # @return [Array] deleted values
+    def delete_if(&block)
+      Janeway::Interpreter.new(@query, as: :delete_if, &block).interpret(@input)
+    end
+
+    # Assign the given value at every query match.
+    # @param replacement [Object]
+    # @return [void]
+    def replace(replacement = :no_replacement_value_was_given, &block)
+      if replacement != :no_replacement_value_was_given && block_given?
+        raise Janeway::Error.new('#replace needs either replacement value or block, not both', @query)
+      end
+
+      # Avoid infinite loop when the replacement data would also be matched by the query
+      previous = []
+      each do |_, parent, key|
+        # Update the previous match
+        unless previous.empty?
+          prev_parent, prev_key = *previous
+          prev_parent[prev_key] = block_given? ? yield(prev_parent[prev_key]) : replacement
+        end
+
+        # Record this match to be updated later
+        previous = [parent, key]
+      end
+      return if previous.empty?
+
+      # Update the final match
+      prev_parent, prev_key = *previous
+      prev_parent[prev_key] = block_given? ? yield(prev_parent[prev_key]) : replacement
+      nil
+    end
+
+    # Insert `value` into the input at a location specified by a singular query.
+    #
+    # This has restrictions:
+    #   * Only for singular queries
+    #     (no wildcards, filter expressions, child segments, etc.)
+    #   * The "parent" node must exist
+    #     eg. for $.a[1].name, the path $.a[1] must exist and be a Hash
+    #   * Cannot create array index N unless the array
+    #     already has exactly N-1 elements
+    #   * If query path already exists, the block is called if provided.
+    #     Otherwise an exception is raised.
+    #
+    # Optionally, pass in a block to be called when there is already a value at the
+    # specified array index / hash key. The parent object and the array index
+    # or hash key will be yielded to the block.
+    #
+    # @yieldparam [Array, Hash] parent object
+    # @yieldparam [Intgeer, String] array index or hash key
+    def insert(value, &block)
+      # Query must point to a single target object
+      unless @query.singular_query?
+        msg = 'Janeway::Query#insert may only be used with a singular query'
+        raise Janeway::Error.new(msg, @query)
+      end
+
+      # Find parent of new value
+      parent, key, parent_path = find_parent
+
+      # Insert new value into parent
+      case parent
+      when Hash then insert_into_hash(parent, key, value, parent_path, &block)
+      when Array then insert_into_array(parent, key, value, parent_path, &block)
+      else
+        raise Error.new("cannot insert into basic type: #{parent.inspect}", @query.to_s)
+      end
+    end
+
+    private
+
+    # Find the 'parent' of the object pointed to by the query. For singular query only.
+    #
+    # @!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
+
+      # Find parent element, give up if parent does not exist
+      results = Interpreter.new(parent_query).interpret(@input)
+      case results.size
+      when 0 then raise "no parent found for #{@query}, cannot insert value"
+      when 1 then parent = results.first
+      else raise "query #{parent_query} matched multiple elements!" # not possible for singular query
+      end
+
+      [parent, selector.value, parent_query.to_s]
+    end
+
+    # Insert value into hash at the given key
+    #
+    # @!visibility private
+    # @param hash [Hash]
+    # @param key [String]
+    # @param value [Object]
+    # @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)
+      unless key.is_a?(String) || key.is_a?(Symbol)
+        raise Error.new("cannot use #{key.inspect} as hash key", @query.to_s)
+      end
+
+      if hash.key?(key)
+        raise Error.new("hash at #{path} already has key #{key.inspect}", @query.to_s) unless block_given?
+
+        yield hash, key
+      end
+
+      hash[key] = value
+    end
+
+    # Insert value into array at the given index
+    #
+    # @!visibility private
+    # @param array [Array]
+    # @param index [Integer]
+    # @param value [Object]
+    # @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)
+      raise Error.new("cannot use #{index.inspect} as array index", @query.to_s) unless index.is_a?(Integer)
+
+      if index < array.size
+        raise Error.new("array at #{path} already has index #{index}", @query.to_s) unless block_given?
+
+        yield array, index
+      end
+      if index > array.size
+        raise Error.new("cannot add index #{index} because array at #{path} is too small", @query.to_s)
+      end
+
+      array << value
+    end
   end
 end

data/lib/janeway/interpreter.rb

@@ -11,6 +11,7 @@ module Janeway
   # It should be created for a single query and then discarded.
   class Interpreter
     attr_reader :jsonpath, :output
+
     include Interpreters
 
     # Interpret a query on the given input, return result
@@ -25,7 +26,7 @@ module Janeway
     # @param query [Query] abstract syntax tree of the jsonpath query
     def initialize(query, as: :finder, &block)
       raise ArgumentError, "expect Query, got #{query.inspect}" unless query.is_a?(Query)
-      unless %i[finder iterator deleter].include?(as)
+      unless %i[finder iterator deleter delete_if].include?(as)
         raise ArgumentError, "invalid interpreter type: #{as.inspect}"
       end
 
@@ -80,6 +81,7 @@ module Janeway
       case @type
       when :iterator then interpreters.push(Yielder.new(&block))
       when :deleter then interpreters.push make_deleter(interpreters.pop)
+      when :delete_if then interpreters.push make_delete_if(interpreters.pop, &block)
       end
 
       # Link interpreters together
@@ -114,6 +116,14 @@ module Janeway
       TreeConstructor.ast_node_to_deleter(interpreter.node)
     end
 
+    # Make a DeleteIf that will delete the results matched by a Selector,
+    # after yielding to a block for approval.
+    #
+    # @param interpreter [Interpreters::Base] interpeter subclass
+    def make_delete_if(interpreter, &block)
+      TreeConstructor.ast_node_to_delete_if(interpreter.node, &block)
+    end
+
     # Return an Interpreter::Error with the specified message, include the query.
     #
     # @param msg [String] error message