json_scanner 0.3.1 → 1.0.0

data/lib/json_scanner.rb

@@ -3,7 +3,92 @@
 require_relative "json_scanner/version"
 require_relative "json_scanner/json_scanner"
 
+require "json"
+
+# Extract values from JSON without full parsing. This gem uses the +yajl+ library
+#   to scan a JSON string and allows you to parse pieces of it.
 module JsonScanner
   class Error < StandardError; end
-  # Your code goes here...
+
+  ALLOWED_OPTS = %i[verbose_error allow_comments dont_validate_strings allow_multiple_values
+                    allow_trailing_garbage allow_partial_values symbolize_path_keys symbolize_names].freeze
+  private_constant :ALLOWED_OPTS
+  STUB = :stub
+  private_constant :STUB
+  SCAN_OPTS = { with_path: true, with_roots_info: true }.freeze
+  private_constant :SCAN_OPTS
+  SCAN_OPTIONS = Options.new(SCAN_OPTS)
+  private_constant :SCAN_OPTIONS
+
+  def self.parse(json_str, config_or_path_ary, **opts)
+    # with_path and with_roots_info is set here
+    unless (extra_opts = opts.keys - ALLOWED_OPTS).empty?
+      raise ArgumentError, "unknown keyword#{"s" if extra_opts.size > 1}: #{extra_opts.map(&:inspect).join(", ")}"
+    end
+
+    opts[:symbolize_path_keys] = opts.delete(:symbolize_names) if opts.key?(:symbolize_names)
+    results, roots = if opts.empty?
+                       scan(json_str, config_or_path_ary, SCAN_OPTIONS)
+                     else
+                       scan(json_str, config_or_path_ary, **opts, **SCAN_OPTS)
+                     end
+
+    res = process_results(json_str, results, roots, opts[:symbolize_path_keys])
+
+    opts[:allow_multiple_values] ? res : res.first
+  end
+
+  def self.process_results(json_str, results, roots, symbolize_names)
+    # stubs are symbols, so they can be distinguished from real values
+    res = roots.map(&:first)
+    # results for different path matchers can overlap, in that case we will simply parse more than one time,
+    # but there shouln't be any surprises in the behavior
+    results.each do |result|
+      process_result(res, result, roots, json_str, symbolize_names)
+    end
+    res
+  end
+
+  private_class_method :process_results
+
+  def self.process_result(res, result, roots, json_str, symbolize_names)
+    current_root_index = 0
+    next_root = roots[1]
+    result.each do |path, (begin_pos, end_pos, _type)|
+      while next_root && begin_pos >= next_root[1]
+        current_root_index += 1
+        next_root = roots[current_root_index + 1]
+      end
+
+      # for 'res[index]' check inside insert_value
+      res[current_root_index] = nil if res[current_root_index].is_a?(Symbol)
+      insert_value(res, parse_value(json_str, begin_pos, end_pos, symbolize_names), current_root_index, path)
+    end
+  end
+
+  private_class_method :process_result
+
+  def self.parse_value(json_str, begin_pos, end_pos, symbolize_names)
+    # TODO: opts for JSON.parse
+    JSON.parse(
+      json_str.byteslice(begin_pos...end_pos),
+      quirks_mode: true, symbolize_names: symbolize_names,
+    )
+  end
+
+  private_class_method :parse_value
+
+  def self.insert_value(res, parsed_value, index, path)
+    until path.empty?
+      new_index = path.shift
+      res[index] ||= new_index.is_a?(Integer) ? [] : {}
+      res = res[index]
+      index = new_index
+    end
+
+    (index - res.size).times { res.push(STUB) } if res.is_a?(Array) && res.size < index
+    res[index] = parsed_value
+  end
+
+  private_class_method :insert_value
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: json_scanner
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 1.0.0
 platform: ruby
 authors:
 - uvlad7
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-08-14 00:00:00.000000000 Z
-dependencies: []
+date: 2025-10-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.8.3.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.8.3.1
 description: This gem uses the yajl lib to scan a JSON string and allows you to parse
   pieces of it
 email:
@@ -19,17 +33,12 @@ extensions:
 - ext/json_scanner/extconf.rb
 extra_rdoc_files: []
 files:
-- README.md
 - ext/json_scanner/extconf.rb
 - ext/json_scanner/json_scanner.c
 - ext/json_scanner/json_scanner.h
 - lib/json_scanner.rb
 - lib/json_scanner/version.rb
 - sig/json_scanner.rbs
-- spec/extensiontesttask.rb
-- spec/json_scanner_spec.c
-- spec/json_scanner_spec.rb
-- spec/spec_helper.rb
 homepage: https://github.com/uvlad7/json_scanner
 licenses:
 - MIT

data/README.md

@@ -1,166 +0,0 @@
-[![Tests](https://github.com/uvlad7/json_scanner/actions/workflows/main.yml/badge.svg)](https://github.com/uvlad7/json_scanner/actions/workflows/main.yml)
-
-# JsonScanner
-
-Extract values from JSON without full parsing. This gem uses the `yajl` library to scan a JSON string and allows you to parse pieces of it.
-
-## Installation
-
-Install the gem and add to the application's Gemfile by executing:
-
-    $ bundle add json_scanner
-
-If bundler is not being used to manage dependencies, install the gem by executing:
-
-    $ gem install json_scanner
-
-## Usage
-
-Basic usage
-
-```ruby
-require "json"
-require "json_scanner"
-
-large_json = "[#{"4," * 100_000}42#{",2" * 100_000}]"
-where_is_42 = JsonScanner.scan(large_json, [[100_000]], false).first
-# => [[200001, 200003, :number]]
-where_is_42.map do |begin_pos, end_pos, _type|
-  JSON.parse(large_json.byteslice(begin_pos...end_pos), quirks_mode: true)
-end
-# => [42]
-
-emoji_json = '{"grin": "😁", "heart": "😍", "rofl": "🤣"}'
-begin_pos, end_pos, = JsonScanner.scan(emoji_json, [["heart"]], false).first.first
-emoji_json.byteslice(begin_pos...end_pos)
-# => "\"😍\""
-# Note: You most likely don't need the `quirks_mode` option unless you are using an older version
-# of Ruby with the stdlib - or just also old - version of the json gem. In newer versions, `quirks_mode` is enabled by default.
-JSON.parse(emoji_json.byteslice(begin_pos...end_pos), quirks_mode: true)
-# => "😍"
-# You can also do this
-# emoji_json.force_encoding(Encoding::BINARY)[begin_pos...end_pos].force_encoding(Encoding::UTF_8)
-# => "\"😍\""
-
-# Ranges are supported as matchers for indexes with the following restrictions:
-# - the start of a range must be positive
-# - the end of a range must be positive or -1
-# - a range with -1 end must be closed, e.g. (0..-1) works, but (0...-1) is forbidden
-JsonScanner.scan('[0, 42, 0]', [[(1..-1)]])
-# => [[[4, 6, :number], [8, 9, :number]]]
-JsonScanner.scan('[0, 42, 0]', [[JsonScanner::ANY_INDEX]])
-# => [[[1, 2, :number], [4, 6, :number], [8, 9, :number]]]
-
-# Special matcher JsonScanner::ANY_KEY is supported for object keys
-JsonScanner.scan('{"a": 1, "b": 2}', [[JsonScanner::ANY_KEY]], with_path: true)
-# => [[[["a"], [6, 7, :number]], [["b"], [14, 15, :number]]]]
-# Regex mathers aren't supported yet, but you can simulate it using `with_path` option
-JsonScanner.scan(
-  '{"question1": 1, "answer": 42, "question2": 2}',
-  [[JsonScanner::ANY_KEY]], with_path: true,
-).map do |res|
-  res.map do |path, (begin_pos, end_pos, type)|
-    [begin_pos, end_pos, type] if path[0] =~ /\Aquestion/
-  end.compact
-end
-# => [[[14, 15, :number], [44, 45, :number]]]
-```
-
-## Options
-
-`JsonScanner` supports multiple options
-
-```ruby
-JsonScanner.scan('[0, 42, 0]', [[(1..-1)]], with_path: true)
-# => [[[[1], [4, 6, :number]], [[2], [8, 9, :number]]]]
-JsonScanner.scan('[0, 42],', [[(1..-1)]], verbose_error: true)
-# JsonScanner::ParseError (parse error: trailing garbage)
-#                                 [0, 42],
-#                      (right here) ------^
-# Note: the 'right here' pointer is wrong in case of a premature EOF error, it's a bug of the libyajl
-JsonScanner.scan('[0, 42,', [[(1..-1)]], verbose_error: true)
-# JsonScanner::ParseError (parse error: premature EOF)
-#                                        [0, 42,
-#                      (right here) ------^
-JsonScanner.scan('[0, /* answer */ 42, 0]', [[(1..-1)]], allow_comments: true)
-# => [[[17, 19, :number], [21, 22, :number]]]
-JsonScanner.scan("\"\x81\x83\"", [[]], dont_validate_strings: true)
-# => [[[0, 4, :string]]]
-JsonScanner.scan("{\"\x81\x83\": 42}", [[JsonScanner::ANY_KEY]], dont_validate_strings: true, with_path: true)
-# => [[[["\x81\x83"], [7, 9, :number]]]]
-JsonScanner.scan('[0, 42, 0]garbage', [[(1..-1)]], allow_trailing_garbage: true)
-# => [[[4, 6, :number], [8, 9, :number]]]
-JsonScanner.scan('[0, 42, 0]  [0, 34]', [[(1..-1)]], allow_multiple_values: true)
-# => [[[4, 6, :number], [8, 9, :number], [16, 18, :number]]]
-JsonScanner.scan('[0, 42, 0', [[(1..-1)]], allow_partial_values: true)
-# => [[[4, 6, :number], [8, 9, :number]]]
-JsonScanner.scan('{"a": 1}', [[JsonScanner::ANY_KEY]], with_path: true, symbolize_path_keys: true)
-# => [[[[:a], [6, 7, :number]]]]
-```
-
-### Comments in the JSON
-
-Note that the standard `JSON` library supports comments, so you may want to enable it in the `JsonScanner` as well
-```ruby
-json_str = '{"answer": {"value": 42 /* the Ultimate Question of Life, the Universe, and Everything */ }}'
-JsonScanner.scan(json_str, [["answer"]], allow_comments: true).first.map do |begin_pos, end_pos, _type|
-  JSON.parse(json_str.byteslice(begin_pos...end_pos), quirks_mode: true)
-end
-# => [{"value"=>42}]
-```
-
-### Find the end of a JSON string
-
-`allow_trailing_garbage` option may come in handy if you want to extract a JSON string from a JS text
-```ruby
-script_text = <<~'JS'
-      <script>window.__APOLLO_STATE__={"ContentItem:0":{"__typename":"ContentItem","id":0, "configurationType":"NO_CONFIGURATION","replacementPartsUrl":null,"relatedCategories":[{"__ref":"Category:109450"},{"__ref":"Category:82044355"},{"__ref":"Category:109441"},{"__ref":"Category:109442"},{"__ref":"Category:109449"},{"__ref":"Category:109444"},{"__ref":"Category:82043730"}],"recommendedOptions":[]}};window.__APPVERSION__=7018;window.__CONFIG_ENV__={value: 'PRODUCTION'};</script>
-JS
-json_with_trailing_garbage = script_text[/__APOLLO_STATE__\s*=\s*({.+)/, 1]
-json_end_pos = JsonScanner.scan(json_with_trailing_garbage, [[]], allow_trailing_garbage: true).first.first[1]
-apollo_state = JSON.parse(json_with_trailing_garbage[0...json_end_pos])
-```
-
-## Reuse configuration
-
-You can create a `JsonScanner::Config` instance and reuse it between `JsonScanner.scan` calls
-
-```ruby
-require "json_scanner"
-
-config = JsonScanner::Config.new([[], ["key"], [(0..-1)]])
-# => #<JsonScanner::Config [[], ['key'], [(0..9223372036854775807)]]>
-JsonScanner.scan('{"key": "42"}', config)
-# => [[[0, 13, :object]], [[8, 12, :string]], []]
-JsonScanner.scan('{"key": "42"}', config, with_path: true)
-# => [[[[], [0, 13, :object]]], [[["key"], [8, 12, :string]]], []]
-JsonScanner.scan('[0, 42]', config)
-# => [[[0, 7, :array]], [], [[1, 2, :number], [4, 6, :number]]]
-JsonScanner.scan('[0, 42]', config, with_path: true)
-# => [[[[], [0, 7, :array]]], [], [[[0], [1, 2, :number]], [[1], [4, 6, :number]]]]
-```
-
-Options can be passed as a hash, even on Ruby 3
-```ruby
-options = { allow_trailing_garbage: true, allow_partial_values: true }
-JsonScanner.scan('[0, 42', [[1]], options) == JsonScanner.scan('[0, 42]_', [[1]], options)
-# => true
-```
-
-## Streaming mode
-
-Streaming mode isn't supported yet, as it's harder to implement and to use. I plan to add it in the future, its API is a subject to discussion. If you have suggestions, use cases, or preferences for how it should behave, I’d love to hear from you!
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at [github](https://github.com/uvlad7/json_scanner).
-
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/spec/extensiontesttask.rb

@@ -1,128 +0,0 @@
-# frozen_string_literal: true
-
-require "rake/clean"
-require "rake/extensiontask"
-
-module Rake
-  class ExtensionTestTask < ExtensionTask
-    #
-    # The C files to compile.
-    #
-    attr_accessor :c_spec_files
-
-    #
-    # The folders where includes for the test files are.
-    #
-    # Default: %w{/usr/include /usr/include/google}
-    #
-    attr_accessor :test_includes
-
-    #
-    # The libraries to link against.
-    #
-    # Default: %w{cmockery}
-    #
-    attr_accessor :test_libraries
-
-    #
-    # The folders where the libraries are
-    #
-    # Default: %w{/usr/lib}
-    #
-    attr_accessor :test_lib_folders
-
-    def initialize(*args, &block)
-      super
-      @c_spec_files = []
-      @test_includes = %w[/usr/include /usr/include/google]
-      @test_libraries = %w[cmockery]
-      @test_lib_folders = %w[/usr/lib]
-      init_test_tasks(
-        "#{@tmp_dir}/test", "compile:#{@name}:test",
-        "spec:c:#{@name}", "spec:valgrind:#{@name}", "spec:gdb:#{@name}",
-      )
-    end
-
-    private
-
-    def includes
-      @includes ||= (@test_includes + [
-        ".",
-        "../../#{@ext_dir}",
-        "/usr/include/ruby-#{RUBY_VERSION}",
-        "/usr/include/ruby-#{RUBY_VERSION}/#{RUBY_PLATFORM}",
-      ]).map { |l| "-I#{l}" }.join(" ")
-    end
-
-    def libraries
-      @libraries ||= (@test_libraries + %w[ruby pthread crypto]).map { |l| "-l#{l}" }.join(" ")
-    end
-
-    def lib_folders
-      @lib_folders ||= (@test_lib_folders + %w[/usr/lib .]).map { |l| "-L#{l}" }.join(" ")
-    end
-
-    def compile_tests
-      # compile the test sources
-      FileList["*.c"].each do |cfile|
-        sh "gcc -g #{includes} -c #{cfile}"
-      end
-
-      source_objects = FileList["../#{RUBY_PLATFORM}/#{@name}/#{RUBY_VERSION}/*.o"]
-      # link the executables
-      FileList["*.o"].each do |ofile|
-        sh "gcc -g #{lib_folders} #{libraries} #{source_objects} #{ofile} -o #{ofile.ext}"
-      end
-    end
-
-    def init_compile_task(compile_dir, compile_task)
-      directory compile_dir
-      desc "Compile #{@name} tests"
-      task compile_task => ["compile:#{@name}", compile_dir] do
-        # copy the test files into the compilation folder
-        @c_spec_files.each { |file| cp file, compile_dir }
-
-        # start compilation
-        chdir(compile_dir) { compile_tests }
-      end
-    end
-
-    def init_valgrind_task(compile_dir, compile_task, valgrind_task)
-      desc "Execute valgrind for a #{@name} test"
-      task valgrind_task => [compile_task] do |_t, args|
-        sh "valgrind --num-callers=50 --error-limit=no --partial-loads-ok=yes --undef-value-errors=no " \
-           "--leak-check=full #{compile_dir}/#{args.test}"
-      end
-    end
-
-    def init_gdb_task(compile_dir, compile_task, gdb_task)
-      desc "Execute gdb for a #{@name} test"
-      task gdb_task => [compile_task] do |_t, args|
-        sh "gdb #{compile_dir}/#{args.test}"
-      end
-    end
-
-    def init_test_task(compile_dir, compile_task, test_task)
-      desc "Test #{@name}"
-      task test_task => [compile_task] do |_t, args|
-        if args.test
-          sh "#{compile_dir}/#{args.test}"
-        else
-          FileList["#{compile_dir}/*.o"].each do |ofile|
-            sh ofile.ext.to_s
-          end
-        end
-      end
-    end
-
-    def init_test_tasks(compile_dir, compile_task, test_task, valgrind_task, gdb_task)
-      init_compile_task(compile_dir, compile_task)
-      init_valgrind_task(compile_dir, compile_task, valgrind_task)
-      init_gdb_task(compile_dir, compile_task, gdb_task)
-      init_test_task(compile_dir, compile_task, test_task)
-
-      desc "Test all C extensions"
-      task "spec:c" => [test_task]
-    end
-  end
-end