janeway-jsonpath 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee00e4f5c1c77042409d76e6de5a287dfe0d5bcdaa2c150db2d11fa7e4037228
-  data.tar.gz: 7b95f568aa555bb5b9959a2ced3677d7ab7b0e877c69e34db29abbdff5211e50
+  metadata.gz: 210bad818f98217873f0055d2ed46432b2b56087442e371671c22f00e51ff0f8
+  data.tar.gz: 1a2fd7d80573323fb3cb6c6b8c28ddf5182585bf05cd2540816d29faf637ed87
 SHA512:
-  metadata.gz: 57a64e5946f8375ef13bc634dd9e860588fd7ff7d2c6b2f3b6c14de640ba1ba26e4a4fcc12ba71958853728626d846ed067392ca876efd94f02f0a41c2d2ac5b
-  data.tar.gz: 238e8cdb81ddab8674c22eb2150c5b7522e7012eac965f264486017c7e51328a0eea23d3d352698c72eeb0275a1924a1b89575104eaf64d3796a52cdb76499dd
+  metadata.gz: 35c927af0528d849acf86691fb7b2fa0ec16d69ce6819ad37f231b3918394f9459ceb7ec4340cb65cf4feb48792c251317af111072bb8e23f8cc2d8da6407cf1
+  data.tar.gz: 22337b8703744e1428632635dcfb1eb25c57042d069b37ecf0ee0b13b70554d2b5fd1c3bc59af75f4ec0d4a23876e8aeb1421bc35c82ed8b652c0ac3ff0baf4a

data/README.md

@@ -77,7 +77,7 @@ Example:
 
 
     ### Find and return matching values
-    $ janeway '$..book[?(@["price"] == 8.95 || @["price"] == 8.99)].title' store.json
+    $ janeway '$..book[? @.price==8.95 || @.price==8.99].title' store.json
     [
       "Sayings of the Century",
       "Moby Dick"
@@ -97,7 +97,7 @@ Example:
 
 You can also pipe JSON into it:
 ```
-    $ cat store.json | janeway '$..book[?(@.price<10)]'
+    $ cat store.json | janeway '$..book[? @.price<10]'
 ```
 
 See the help message for more capabilities: `janeway --help`
@@ -122,7 +122,7 @@ Following are examples showing how to work with the Enumerator methods.
 Returns all values that match the query.
 
 ```ruby
-    results = Janeway.enum_for('$..book[?(@.price<10)]', data).search
+    results = Janeway.enum_for('$..book[? @.price<10]', data).search
     # Returns every book in the store cheaper than $10
 ```
 
@@ -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.compile('$..book[? @.price<10]')
     ractors.each { |ractor| ractor.send(query).take }
 ```
 
@@ -159,7 +159,7 @@ The matched value is yielded:
     end
 ```
 
-This allows the matched value to be modified in place:
+Strings values can be modified in place:
 ```ruby
     Janeway.enum_for('$.birds[? @=="storck"]', data).each do |bird|
       bird.gsub!('ck', 'k') # Fix a typo: "storck" => "stork"
@@ -167,7 +167,8 @@ This allows the matched value to be modified in place:
     # input list is now ['eagle', 'stork', 'cormorant']
 ```
 
-However, this is not enough to replace the matched value:
+However, this doesn't work with numeric values because they can't be modified in place.
+Here's an example illustrating the same problem but using strings:
 ```ruby
     Janeway.enum_for('$.birds', data).each do |bird|
       bird = "bald eagle" if bird == 'eagle'
@@ -176,7 +177,8 @@ However, this is not enough to replace the matched value:
     # input list is still ['eagle', 'stork', 'cormorant']
 ```
 
-The second and third yield parameters are the object that contains the value, and the array index or hash key of the value.
+To replace list values, you need access to the parent object (a Hash or Array) and the array index / hash key.
+These are available as the second and third yield parameters.
 This allows the list or hash to be modified:
 ```ruby
     Janeway.enum_for('$.birds[? @=="eagle"]', data).each do |_bird, parent, index|
@@ -185,7 +187,15 @@ This allows the list or hash to be modified:
     # input list is now ['golden eagle', 'stork', 'cormorant']
 ```
 
-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.
+The parent / index parameters can also be used to delete values, but this requires caution to avoid index errors.
+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.
+
+
+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.
 This is a jsonpath query string that uniquely points to the matched value.
 
 ```ruby
@@ -195,15 +205,16 @@ 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
 
-The '#delete' method deletes matched values from the input.
+The `#delete` method deletes matched values from the input.
 ```ruby
-    # delete any bird whose name is "eagle" or starts with "s"
-    Janeway.enum_for('$.birds[? @=="eagle" || search(@, "^s")]', data).delete
+    # delete any bird whose name starts with "s" or is "eagle"
+    Janeway.enum_for('$.birds[? search(@, "^s") || @=="eagle"]', data).delete
     # input bird list is now ['cormorant']
 
     # delete all dog names
@@ -212,13 +223,13 @@ The '#delete' method deletes matched values from the input.
 ```
 
 
-The `Janeway.enum_for` and `Janeway::Query#on` methods return an enumerator, so you can use the usual ruby enumerator methods, such as:
+The `Janeway.enum_for` and `Janeway::Query#enum_for` methods return an enumerator, so you can use the usual ruby enumerator methods, such as:
 
 #####  #map
 Return the matched elements, as modified by the block.
 
 ```ruby
-    # take a dollar off every price in the store
+    # return all store prices, but take a dollar off each one
     sale_prices = Janeway.enum_for('$.store..price', data).map { |price| price - 1 }
     # [7.95, 11.99, 7.99, 21.99, 398]
 ```
@@ -256,15 +267,27 @@ Return only values that match the JSONPath query and also return false from the
 
 #####  #filter_map
 
-Combines #select and #map.
 Return values that match the jsonpath query and return truthy values from the block.
-Instead of returning the value from the data, return the result of the block.
+Instead of returning the value from the data, return the result of the block:
 
-#####  #find 
+```ruby
+    # Return titles of books by certain authors which cost more than the minimum price
+    APPROVED_AUTHORS = ['Evelyn Waugh', 'Herman Melville']
+    Janeway.enum_for('$.store.book[? @.price >= 8.99]', data).filter_map do |book|
+      book['title'] if APPROVED_AUTHORS.include?(book['author'])
+    end
+    # [ "Moby Dick", "Sword of Honour" ]
+```
+
+Combines functionality of `#select` and `#map`.
 
-Return the first value that matches the jsonpath query and also returns a truthy value from the block
+#####  #find
+
+Return the first value that matches the jsonpath query and also returns a truthy value from the block:
 ```ruby
-    Janeway.enum_for('$.store.book[? @.price >= 10.99]', data).find { |book| book['title'].start_with?('T') }
+    Janeway.enum_for('$.store.book[? @.price >= 10.99]', data).find do |book|
+      book['title'].start_with?('T')
+    end
     # [ "The Lord of the Rings" ]
 ```
 

data/lib/janeway/ast/function.rb

@@ -44,17 +44,6 @@ module Janeway
           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/error.rb

@@ -8,13 +8,15 @@ module Janeway
   # Lexer errors may also include the index into the query string that
   # points at which token was being lexed at the time of the error.
   class Error < StandardError
+    # JSONPath query
     # @return [String]
     attr_reader :query
 
+    # For lexer errors, this is the index on the query string where the error was encountered
     # @return [Location, nil]
     attr_reader :location
 
-    # @param message [String] error message
+    # @param msg [String] error message
     # @param query [String] entire query string
     # @param location [Location] location of error
     def initialize(msg, query = nil, location = nil)

data/lib/janeway/interpreters/array_slice_selector_deleter.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'base'
+require_relative 'array_slice_selector_interpreter'
 
 module Janeway
   module Interpreters

data/lib/janeway/interpreters/filter_selector_deleter.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'base'
+require_relative 'filter_selector_interpreter'
 
 module Janeway
   module Interpreters

data/lib/janeway/interpreters/index_selector_deleter.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'name_selector_interpreter'
+require_relative 'index_selector_interpreter'
 
 module Janeway
   module Interpreters

data/lib/janeway/interpreters/root_node_deleter.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'wildcard_selector_interpreter'
+require_relative 'root_node_interpreter'
 
 module Janeway
   module Interpreters

data/lib/janeway/query.rb

@@ -26,7 +26,7 @@ module Janeway
     # This can be used to iterate over results with #each, #map, etc.
     #
     # @return [Janeway::Enumerator]
-    def on(input)
+    def enum_for(input)
       Janeway::Enumerator.new(self, input)
     end
 

data/lib/janeway/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Janeway
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/janeway.rb

@@ -25,11 +25,11 @@ module Janeway
 
   # Compile a JSONPath query into an Abstract Syntax Tree.
   #
-  # This can be combined with inputs (using #on) to create Enumerators.
+  # This can be combined with inputs (using #enum_for) to create Enumerators.
   # @example
   #     query = Janeway.compile('$.store.books[? length(@.title) > 20]')
-  #     long_title_books = query.on(local_json).search
-  #     query.on(remote_json).each do |book|
+  #     long_title_books = query.enum_for(some_data).search
+  #     query.enum_for(other_data).each do |book|
   #       long_title_books << book
   #     end
   #

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: janeway-jsonpath
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Fraser Hanson
 bindir: bin
 cert_chain: []
-date: 2025-01-29 00:00:00.000000000 Z
+date: 2025-01-30 00:00:00.000000000 Z
 dependencies: []
 description: |+
   JSONPath is a query language for selecting and extracting values from a JSON text.