json_p3 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 61e9c2e2224055046c93b4aff7c4f12cfaed22805507d0678e23e322a7d2ee60
+  data.tar.gz: b3460ee7b36ab677af85540b5962701c16313723a98bfba7a722c9ebf7aa0d52
+SHA512:
+  metadata.gz: 5aba27e4070700def8c89ff758a244ebba2fc3f31fbeb882492b0bf9260c61b1f55be0bb655dc5885bc226b7a29f3640ddf78c3801eaabfa291b3937d8723496
+  data.tar.gz: 96df0d295a541d98e17100a72f10584780a023baef88e9141c108c0137456bc8f1524a5a3e627dc7c14db4368c107d69d7476c47271914a137e98bf26e8210c9

data/.rubocop.yml

@@ -0,0 +1,14 @@
+require:
+  - rubocop-minitest
+  - rubocop-rake
+  - rubocop-performance
+
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/.yardopts

@@ -0,0 +1,3 @@
+--no-private
+--markup markdown
+lib/**/*.rb

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## [0.2.1] - 2024-10-24
+
+- Rename project and gem
+
+## [0.2.0] - 2024-10-24
+
+- Initial release

data/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 James Prior
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,353 @@
+<h1 align="center">JSONPath, JSON Patch and JSON Pointer for Ruby</h1>
+
+<p align="center">
+We follow <a href="https://datatracker.ietf.org/doc/html/rfc9535">RFC 9535</a> strictly and test against the <a href="https://github.com/jsonpath-standard/jsonpath-compliance-test-suite">JSONPath Compliance Test Suite</a>.
+</p>
+
+<p align="center">
+  <a href="https://github.com/jg-rp/ruby-json-p3/blob/main/LICENSE.txt">
+    <img src="https://img.shields.io/pypi/l/jsonpath-rfc9535.svg?style=flat-square" alt="License">
+  </a>
+  <a href="https://github.com/jg-rp/ruby-json-p3/actions">
+    <img src="https://img.shields.io/github/actions/workflow/status/jg-rp/ruby-json-p3/main.yml?branch=main&label=tests&style=flat-square" alt="Tests">
+  </a>
+</p>
+
+---
+
+**Table of Contents**
+
+- [Install](#install)
+- [Example](#example)
+- [Links](#links)
+- [Related projects](#related-projects)
+- [API](#api)
+- [Contributing](#contributing)
+
+## Install
+
+TODO: once published to RubyGems.org
+
+## Example
+
+```ruby
+require "json_p3"
+require "json"
+
+data = JSON.parse <<~JSON
+  {
+    "users": [
+      {
+        "name": "Sue",
+        "score": 100
+      },
+      {
+        "name": "Sally",
+        "score": 84,
+        "admin": false
+      },
+      {
+        "name": "John",
+        "score": 86,
+        "admin": true
+      },
+      {
+        "name": "Jane",
+        "score": 55
+      }
+    ],
+    "moderator": "John"
+  }
+JSON
+
+JSONP3.find("$.users[?@.score > 85]", data).each do |node|
+  puts node.value
+end
+
+# {"name"=>"Sue", "score"=>100}
+# {"name"=>"John", "score"=>86, "admin"=>true}
+```
+
+Or, reading JSON data from a file:
+
+```ruby
+require "json_p3"
+require "json"
+
+data = JSON.load_file("/path/to/some.json")
+
+JSONP3.find("$.some.query", data).each do |node|
+  puts node.value
+end
+```
+
+You could read data from a YAML formatted file too, or any data format that can be loaded into hashes and arrays.
+
+```ruby
+require "json_p3"
+require "yaml"
+
+data = YAML.load_file("/tmp/some.yaml")
+
+JSONP3.find("$.users[?@.score > 85]", data).each do |node|
+  puts node.value
+end
+```
+
+## Links
+
+- Change log: https://github.com/jg-rp/ruby-json-p3/blob/main/CHANGELOG.md
+- TODO: RubyGems
+- Source code: https://github.com/jg-rp/ruby-json-p3
+- Issue tracker: https://github.com/jg-rp/ruby-json-p3/issues
+
+## Related projects
+
+- [Python JSONPath RFC 9535](https://github.com/jg-rp/python-jsonpath-rfc9535) - A Python implementation of JSONPath that follows RFC 9535 strictly.
+- [Python JSONPath](https://github.com/jg-rp/python-jsonpath) - Another Python package implementing JSONPath, but with additional features and customization options.
+- [JSON P3](https://github.com/jg-rp/json-p3) - RFC 9535 implemented in TypeScript.
+
+## API
+
+### find
+
+`find(query, value) -> Array[JSONPathNode]`
+
+Apply JSONPath expression _query_ to JSON-like data _value_. An array of JSONPathNode instance is returned, one node for each value matched by _query_. The returned array will be empty if there were no matches.
+
+Each `JSONPathNode` has:
+
+- a `value` attribute, which is the JSON-like value associated with the node.
+- a `location` attribute, which is a nested array of hash/object names and array indices that were required to reach the node's value in the target JSON document.
+- a `path()` method, which returns the normalized path to the node in the target JSON document.
+
+```ruby
+require "json_p3"
+require "json"
+
+data = JSON.parse <<~JSON
+  {
+    "users": [
+      {
+        "name": "Sue",
+        "score": 100
+      },
+      {
+        "name": "Sally",
+        "score": 84,
+        "admin": false
+      },
+      {
+        "name": "John",
+        "score": 86,
+        "admin": true
+      },
+      {
+        "name": "Jane",
+        "score": 55
+      }
+    ],
+    "moderator": "John"
+  }
+JSON
+
+JSONP3.find("$.users[?@.score > 85]", data).each do |node|
+  puts "#{node.value} at #{node.path}"
+end
+
+# {"name"=>"Sue", "score"=>100} at $['users'][0]
+# {"name"=>"John", "score"=>86, "admin"=>true} at $['users'][2]
+```
+
+### compile
+
+`compile(query) -> JSONPath`
+
+Prepare a JSONPath expression for repeated application to different JSON-like data. An instance of `JSONPath` has a `find(data)` method, which behaves similarly to the module-level `find(query, data)` method.
+
+```ruby
+require "json_p3"
+require "json"
+
+data = JSON.parse <<~JSON
+  {
+    "users": [
+      {
+        "name": "Sue",
+        "score": 100
+      },
+      {
+        "name": "Sally",
+        "score": 84,
+        "admin": false
+      },
+      {
+        "name": "John",
+        "score": 86,
+        "admin": true
+      },
+      {
+        "name": "Jane",
+        "score": 55
+      }
+    ],
+    "moderator": "John"
+  }
+JSON
+
+path = JSONP3.compile("$.users[?@.score > 85]")
+
+path.find(data).each do |node|
+  puts "#{node.value} at #{node.path}"
+end
+
+# {"name"=>"Sue", "score"=>100} at $['users'][0]
+# {"name"=>"John", "score"=>86, "admin"=>true} at $['users'][2]
+```
+
+### JSONPathEnvironment
+
+The `find` and `compile` methods described above are convenience methods equivalent to
+
+```
+JSONP3::DEFAULT_ENVIRONMENT.find(query, data)
+```
+
+and
+
+```
+JSONP3::DEFAULT_ENVIRONMENT.compile(query)
+```
+
+You could create your own environment like this:
+
+```ruby
+require "json_p3"
+
+jsonpath = JSONP3::JSONPathEnvironment.new
+nodes = jsonpath.find("$.*", { "a" => "b", "c" => "d" })
+pp nodes.map(&:value) # ["b", "d"]
+```
+
+To configure an environment with custom filter functions or non-standard selectors, inherit from `JSONPathEnvironment` and override some of its constants or `#setup_function_extensions` method.
+
+```ruby
+class MyJSONPathEnvironment < JSONP3::JSONPathEnvironment
+  # The maximum integer allowed when selecting array items by index.
+  MAX_INT_INDEX = (2**53) - 1
+
+  # The minimum integer allowed when selecting array items by index.
+  MIN_INT_INDEX = -(2**53) + 1
+
+  # The maximum number of arrays and hashes the recursive descent segment will
+  # traverse before raising a {JSONPathRecursionError}.
+  MAX_RECURSION_DEPTH = 100
+
+  # One of the available implementations of the _name selector_.
+  #
+  # - {NameSelector} (the default) will select values from hashes using string keys.
+  # - {SymbolNameSelector} will select values from hashes using string or symbol keys.
+  #
+  # Implement your own name selector by inheriting from {NameSelector} and overriding
+  # `#resolve`.
+  NAME_SELECTOR = NameSelector
+
+  # An implementation of the _index selector_. The default implementation will
+  # select value from arrays only. Implement your own by inheriting from
+  # {IndexSelector} and overriding `#resolve`.
+  INDEX_SELECTOR = IndexSelector
+
+  # Override this function to configure JSONPath function extensions.
+  # By default, only the standard functions described in RFC 9535 are enabled.
+  def setup_function_extensions
+    @function_extensions["length"] = Length.new
+    @function_extensions["count"] = Count.new
+    @function_extensions["value"] = Value.new
+    @function_extensions["match"] = Match.new
+    @function_extensions["search"] = Search.new
+  end
+```
+
+### JSONPathError
+
+`JSONPathError` is the base class for all JSONPath exceptions. The following classes inherit from `JSONPathError` and will only occur when parsing a JSONPath expression, not when applying a path to some data.
+
+- `JSONPathSyntaxError`
+- `JSONPathTypeError`
+- `JSONPathNameError`
+
+`JSONPathError` implements `#detailed_message`. With recent versions of Ruby you should get useful error messages.
+
+```
+JSONP3::JSONPathSyntaxError: unexpected trailing whitespace
+  -> '$.foo ' 1:5
+  |
+1 | $.foo
+  |      ^ unexpected trailing whitespace
+```
+
+## Contributing
+
+Your contributions and questions are always welcome. Feel free to ask questions, report bugs or request features on the [issue tracker](https://github.com/jg-rp/ruby-json-p3/issues) or on [Github Discussions](https://github.com/jg-rp/ruby-json-p3/discussions). Pull requests are welcome too.
+
+### Development
+
+The [JSONPath Compliance Test Suite](https://github.com/jsonpath-standard/jsonpath-compliance-test-suite) is included as a git [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules). Clone the Ruby JSONPath RFC 9535 git repository and initialize the CTS submodule.
+
+```shell
+$ git clone git@github.com:jg-rp/ruby-json-p3.git
+$ cd ruby-json-p3.git
+$ git submodule update --init
+```
+
+We use [Bundler](https://bundler.io/) and [Rake](https://ruby.github.io/rake/). Install development dependencies with
+
+```
+bundle install
+```
+
+Run tests with
+
+```
+bundle exec rake test
+```
+
+Lint with
+
+```
+bundle exec rubocop
+```
+
+And type check with
+
+```
+bundle exec steep
+```
+
+Run one of the benchmarks with
+
+```
+bundle exec ruby performance/benchmark_ips.rb
+```
+
+### Profiling
+
+#### CPU profile
+
+Dump profile data with `bundle exec ruby performance/profile.rb`, then generate an HTML flame graph with
+
+```
+bundle exec stackprof --d3-flamegraph .stackprof-cpu-just-compile.dump > flamegraph-cpu-just-compile.html
+```
+
+#### Memory profile
+
+Print memory usage to the terminal.
+
+```
+bundle exec ruby performance/memory_profile.rb
+```
+
+### TruffleRuby
+
+On macOS Sonoma using MacPorts and `rbenv`, `LIBYAML_PREFIX=/opt/local/lib` is needed to install TruffleRuby and when executing any `bundle` command.

data/Rakefile

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new do |task|
+  task.requires << "rubocop-minitest"
+  task.requires << "rubocop-rake"
+  task.requires << "rubocop-performance"
+end
+
+require "steep/rake_task"
+
+Steep::RakeTask.new do |t|
+  t.check.severity_level = :error
+  t.watch.verbose
+end
+
+task default: %i[test rubocop steep]

data/Steepfile

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+D = Steep::Diagnostic
+
+target :lib do
+  signature "sig"
+
+  check "lib" # Directory name
+  #   check "Gemfile"                   # File name
+  #   check "app/models/**/*.rb"        # Glob
+  # ignore "lib/templates/*.rb"
+
+  # library "pathname"              # Standard libraries
+  #   library "minitest"
+  #   library "minitest/autorun"
+
+  library "json"
+  library "strscan"
+
+  # configure_code_diagnostics(D::Ruby.default)      # `default` diagnostics setting (applies by default)
+  # configure_code_diagnostics(D::Ruby.strict)       # `strict` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.lenient)      # `lenient` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.silent)       # `silent` diagnostics setting
+  # configure_code_diagnostics do |hash|             # You can setup everything yourself
+  #   hash[D::Ruby::NoMethod] = :information
+  # end
+end

data/lib/json_p3/cache.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module JSONP3
+  # A least recently used cache relying on Ruby hash insertion order.
+  class LRUCache
+    attr_reader :max_size
+
+    def initialize(max_size = 128)
+      @data = {}
+      @max_size = max_size
+    end
+
+    # Return the cached value or nil if _key_ does not exist.
+    def [](key)
+      val = @data[key]
+      return nil if val.nil?
+
+      @data.delete(key)
+      @data[key] = val
+      val
+    end
+
+    def []=(key, value)
+      if @data.key?(key)
+        @data.delete(key)
+      elsif @data.length >= @max_size
+        @data.delete(@data.first[0])
+      end
+      @data[key] = value
+    end
+
+    def length
+      @data.length
+    end
+
+    def keys
+      @data.keys
+    end
+  end
+end

data/lib/json_p3/environment.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "lexer"
+require_relative "parser"
+require_relative "path"
+require_relative "function_extensions/length"
+require_relative "function_extensions/value"
+require_relative "function_extensions/count"
+require_relative "function_extensions/match"
+require_relative "function_extensions/search"
+
+module JSONP3
+  # JSONPath configuration
+  #
+  # Configure an environment by inheriting from `JSONPathEnvironment` and setting one
+  # or more constants and/or overriding {setup_function_extensions}.
+  class JSONPathEnvironment
+    # The maximum integer allowed when selecting array items by index.
+    MAX_INT_INDEX = (2**53) - 1
+
+    # The minimum integer allowed when selecting array items by index.
+    MIN_INT_INDEX = -(2**53) + 1
+
+    # The maximum number of arrays and hashes the recursive descent segment will
+    # traverse before raising a {JSONPathRecursionError}.
+    MAX_RECURSION_DEPTH = 100
+
+    # One of the available implementations of the _name selector_.
+    #
+    # - {NameSelector} (the default) will select values from hashes using string keys.
+    # - {SymbolNameSelector} will select values from hashes using string or symbol keys.
+    #
+    # Implement your own name selector by inheriting from {NameSelector} and overriding
+    # `#resolve`.
+    NAME_SELECTOR = NameSelector
+
+    # An implementation of the _index selector_. The default implementation will
+    # select value from arrays only. Implement your own by inheriting from
+    # {IndexSelector} and overriding `#resolve`.
+    INDEX_SELECTOR = IndexSelector
+
+    attr_accessor :function_extensions
+
+    def initialize
+      @parser = Parser.new(self)
+      @function_extensions = {}
+      setup_function_extensions
+    end
+
+    # Prepare JSONPath expression _query_ for repeated application.
+    # @param query [String]
+    # @return [JSONPath]
+    def compile(query)
+      tokens = JSONP3.tokenize(query)
+      JSONPath.new(self, @parser.parse(tokens))
+    end
+
+    # Apply JSONPath expression _query_ to _value_.
+    # @param query [String] the JSONPath expression
+    # @param value [JSON-like data] the target JSON "document"
+    # @return [Array<JSONPath>]
+    def find(query, value)
+      compile(query).find(value)
+    end
+
+    # Override this function to configure JSONPath function extensions.
+    # By default, only the standard functions described in RFC 9535 are enabled.
+    def setup_function_extensions
+      @function_extensions["length"] = Length.new
+      @function_extensions["count"] = Count.new
+      @function_extensions["value"] = Value.new
+      @function_extensions["match"] = Match.new
+      @function_extensions["search"] = Search.new
+    end
+  end
+end

data/lib/json_p3/errors.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module JSONP3
+  # An exception raised when a JSONPathEnvironment is misconfigured.
+  class JSONPathEnvironmentError < StandardError; end
+
+  # Base class for JSONPath exceptions that happen when parsing or evaluating a query.
+  class JSONPathError < StandardError
+    FULL_MESSAGE = ((RUBY_VERSION.split(".")&.map(&:to_i) <=> [3, 2, 0]) || -1) < 1
+
+    def initialize(msg, token)
+      super(msg)
+      @token = token
+    end
+
+    def detailed_message(highlight: true, **_kwargs) # rubocop:disable Metrics/AbcSize
+      if @token.query.strip.empty?
+        "empty query"
+      else
+        lines = @token.query[...@token.start]&.lines or [""] # pleasing the type checker
+        lineno = lines.length
+        col = lines[-1].length
+        pad = " " * lineno.to_s.length
+        pointer = (" " * col) + ("^" * [@token.value.length, 1].max)
+        <<~ENDOFMESSAGE.strip
+          #{self.class}: #{message}
+          #{pad} -> '#{@token.query}' #{lineno}:#{col}
+          #{pad} |
+          #{lineno} | #{@token.query}
+          #{pad} | #{pointer} #{highlight ? "\e[1m#{message}\e[0m" : message}
+        ENDOFMESSAGE
+      end
+    end
+
+    def full_message(highlight: true, order: :top)
+      if FULL_MESSAGE
+        # For Ruby < 3.2.0
+        "#{super}\n#{detailed_message(highlight: highlight, order: order)}"
+      else
+        super
+      end
+    end
+  end
+
+  class JSONPathSyntaxError < JSONPathError; end
+  class JSONPathTypeError < JSONPathError; end
+  class JSONPathNameError < JSONPathError; end
+  class JSONPathRecursionError < JSONPathError; end
+end