nosj 0.4.0 → 0.5.0

data/ext/nosj/src/state.rs

@@ -10,33 +10,78 @@ use ahash::AHashMap;
 use magnus::typed_data::Obj;
 use magnus::{DataTypeFunctions, TypedData};
 use nosj::Buffers;
-use std::cell::RefCell;
+use std::cell::Cell;
+use std::thread::LocalKey;
 
-/// Everything a parse touches, allocated once per thread and reused:
-/// nosj's scratch buffers, the interned-key caches, and the GC-marked
-/// stacks.
+use crate::sink::DupScratch;
+
+/// Run `f` on a pooled thread-local value, taken OUT of its cell for the
+/// call and stored back afterwards. Pooled state is never borrowed
+/// across a call that can reach Ruby: any allocation can raise
+/// NoMemoryError, whose longjmp skips these frames, and a RefCell borrow
+/// held across it would stay borrowed for good (under panic=abort, the
+/// next borrow kills the process). A value lost that way is only leaked;
+/// the next call, like a nested one finding the cell empty, starts from
+/// `T::default()`. The outermost call's value is the one stored back.
+pub(crate) fn with_taken<T: Default, R>(
+    key: &'static LocalKey<Cell<T>>,
+    f: impl FnOnce(&mut T) -> R,
+) -> R {
+    let mut value = key.take();
+    let result = f(&mut value);
+    key.set(value);
+    result
+}
+
+/// Everything a parse touches, reused across calls: nosj's scratch
+/// buffers, the interned-key caches, and the GC-marked stacks.
 pub(crate) struct PullState {
     pub(crate) bufs: Buffers,
     pub(crate) keys: AHashMap<Box<str>, rb_sys::VALUE>,
     /// Separate cache for symbolize_names mode: symbol and string VALUEs
     /// must never share a map.
     pub(crate) sym_keys: AHashMap<Box<str>, rb_sys::VALUE>,
-    /// Leaked once per thread; kept alive + GC-marked via the wrapped
+    /// Leaked once per state; kept alive + GC-marked via the wrapped
     /// handle.
     pub(crate) vstack: Option<&'static mut VStackShadow>,
     /// Marked shadow holding the cached key VALUEs; keys are kept alive by
     /// this (collectable on epoch clear), NOT by per-key eternal GC pins.
     pub(crate) key_shadow: Option<&'static mut VStackShadow>,
+    /// Duplicate-key detection buffers for hash-less sinks.
+    pub(crate) dup: DupScratch,
+}
+
+impl PullState {
+    #[cold]
+    fn fresh() -> Box<Self> {
+        Box::new(PullState {
+            bufs: Buffers::new(),
+            keys: AHashMap::with_capacity(256),
+            sym_keys: AHashMap::new(),
+            vstack: None,
+            key_shadow: None,
+            dup: DupScratch::default(),
+        })
+    }
 }
 
 thread_local! {
-    pub(crate) static PULL_STATE: RefCell<PullState> = RefCell::new(PullState {
-        bufs: Buffers::new(),
-        keys: AHashMap::with_capacity(256),
-        sym_keys: AHashMap::new(),
-        vstack: None,
-        key_shadow: None,
-    });
+    static PULL_STATE: Cell<Option<Box<PullState>>> = const { Cell::new(None) };
+}
+
+/// Run `f` on this thread's parse state, taken out like [`with_taken`]
+/// (a state lost to a longjmp leaks its shadows' last VALUEs; a nested
+/// call would start a fresh one). Unlike the generate scratch, parse
+/// bodies never run Ruby code, so the thread cannot hop native threads
+/// mid-call and one thread-local access serves both the take and the
+/// put-back: measured ~5ns per call on tiny documents against two.
+pub(crate) fn with_pull_state<R>(f: impl FnOnce(&mut PullState) -> R) -> R {
+    PULL_STATE.with(|cell| {
+        let mut state = cell.take().unwrap_or_else(PullState::fresh);
+        let result = f(&mut state);
+        cell.set(Some(state));
+        result
+    })
 }
 
 /// GC-marked holder for pending VALUEs.
@@ -48,6 +93,12 @@ pub(crate) struct VStackShadow {
 /// through [`DataTypeFunctions::mark`] (its trampoline, not ours),
 /// pinning every pending VALUE with `rb_gc_mark` semantics. The class
 /// is defined (and made a private constant) at init.
+///
+/// Deliberately NOT `wb_protected`: parses push VALUEs into the shadow
+/// with plain stores, no write barriers, so an old protected handle
+/// would let the GC miss young values it holds (a use-after-free).
+/// Staying write-barrier-unprotected makes every GC rescan the handle,
+/// which costs nothing measurable: there are one to three per thread.
 #[derive(TypedData)]
 #[magnus(class = "NOSJ::ValueStackShadow", mark)]
 pub(crate) struct ShadowHandle(*const VStackShadow);
@@ -74,7 +125,7 @@ impl DataTypeFunctions for ShadowHandle {
     }
 }
 
-/// Create (once per thread) a leaked, GC-marked VStackShadow.
+/// Create (once per owning state) a leaked, GC-marked VStackShadow.
 pub(crate) fn ensure_marked_shadow(slot: &mut Option<&'static mut VStackShadow>) {
     if slot.is_none() {
         let ruby = magnus::Ruby::get().expect("called on a Ruby thread");
@@ -83,7 +134,7 @@ pub(crate) fn ensure_marked_shadow(slot: &mut Option<&'static mut VStackShadow>)
         }));
         let ptr = std::ptr::from_mut::<VStackShadow>(shadow).cast_const();
         let handle: Obj<ShadowHandle> = ruby.obj_wrap(ShadowHandle(ptr));
-        magnus::gc::register_mark_object(handle);
+        ruby.gc_register_mark_object(handle);
         *slot = Some(shadow);
     }
 }

data/ext/nosj/src/stats.rs

@@ -8,11 +8,11 @@ use ahash::AHashMap;
 use magnus::value::ReprValue;
 use magnus::{Error, RHash, RString, Ruby, Value};
 
-use crate::errors::{nesting_error, parser_error, parser_error_at};
 use crate::files::with_mapped_file;
-use crate::parse::{parse_native_opts, utf8_input};
+use crate::opt_reader::{Opt, OptReader};
+use crate::parse::{drive_error, max_nesting_of, options_hash, utf8_input, ParseNativeOpts};
 use crate::sink::SinkAbort;
-use crate::state::PULL_STATE;
+use crate::state::with_pull_state;
 
 /// What the document's root value was; reported as a Symbol. The
 /// Default is never observable (a successful pass always saw a root
@@ -239,41 +239,41 @@ fn stats_to_hash(ruby: &Ruby, s: &StatsSink, byte_size: usize) -> Result<Value,
     Ok(out.as_value())
 }
 
-/// Run the counting pass over already-UTF-8-vouched bytes and build
-/// the result. `max_nesting` here defaults to UNLIMITED (a deep blob
-/// is exactly what a diagnostic should describe, not refuse), unless
-/// the caller passes the option explicitly.
-fn stats_over(ruby: &Ruby, input: &[u8], opts: Value) -> Result<Value, Error> {
-    let o = parse_native_opts(ruby, opts)?;
-    let nesting_given =
-        RHash::from_value(opts).is_some_and(|h| h.get(ruby.to_symbol("max_nesting")).is_some());
+/// Stats' options: `max_nesting`, which here defaults to UNLIMITED (a
+/// deep blob is exactly what a diagnostic should describe, not refuse),
+/// and the grammar extensions. Decoded before the source is borrowed:
+/// a hash lookup can run a key's own `hash`/`eql?`.
+fn stats_opts(ruby: &Ruby, opts: Value) -> Result<ParseNativeOpts, Error> {
+    let mut o = ParseNativeOpts {
+        max_nesting: usize::MAX,
+        ..ParseNativeOpts::default()
+    };
+    let Some(h) = options_hash(ruby, opts)? else {
+        return Ok(o);
+    };
+    let mut r = OptReader::new(ruby, h);
+    if let Some(v) = r.get(Opt::MaxNesting) {
+        o.max_nesting = max_nesting_of(v);
+    }
+    o.popts.allow_nan = r.truthy(Opt::AllowNan);
+    o.popts.allow_trailing_comma = r.truthy(Opt::AllowTrailingComma);
+    r.finish()?;
+    Ok(o)
+}
 
+/// Run the counting pass over already-UTF-8-vouched bytes and build
+/// the result.
+fn stats_over(ruby: &Ruby, input: &[u8], o: &ParseNativeOpts) -> Result<Value, Error> {
     let mut sink = StatsSink {
-        max_nesting: if nesting_given {
-            o.max_nesting
-        } else {
-            usize::MAX
-        },
+        max_nesting: o.max_nesting,
         ..StatsSink::default()
     };
-    let result = PULL_STATE.with(|cell| {
-        let mut state = cell.borrow_mut();
+    let result = with_pull_state(|state| {
         // Safety: callers verified UTF-8 (coderange or a full scan).
         unsafe { nosj::parse_utf8_unchecked_with(input, &mut state.bufs, &mut sink, o.popts) }
     });
-    match result {
-        Ok(()) => stats_to_hash(ruby, &sink, input.len()),
-        Err(nosj::DriveError::Sink(SinkAbort::TooDeep)) => Err(nesting_error(
-            ruby,
-            format!("nesting of {} is too deep", o.max_nesting.saturating_add(1)),
-        )),
-        // The other aborts cannot happen (this sink never raises them),
-        // but the match must be total.
-        Err(nosj::DriveError::Sink(_)) => Err(parser_error(ruby, "stats pass aborted".into())),
-        Err(nosj::DriveError::Parse(e)) => {
-            Err(parser_error_at(ruby, input, e.offset, e.to_string()))
-        }
-    }
+    result.map_err(|failure| drive_error(ruby, failure, o, input, (0, input.len())))?;
+    stats_to_hash(ruby, &sink, input.len())
 }
 
 /// `NOSJ.stats(source, opts)`: document statistics from one null-sink
@@ -284,8 +284,9 @@ pub fn stats_native(
     data: RString,
     opts: Value,
 ) -> Result<Value, Error> {
+    let o = stats_opts(ruby, opts)?;
     let input = utf8_input(ruby, &data)?;
-    stats_over(ruby, input, opts)
+    stats_over(ruby, input, &o)
 }
 
 /// `NOSJ.stats_file(path, opts)`: `NOSJ.stats` against a memory-mapped
@@ -296,6 +297,7 @@ pub fn stats_file_native(
     path: RString,
     opts: Value,
 ) -> Result<Value, Error> {
+    let o = stats_opts(ruby, opts)?;
     let p = path.to_string()?;
-    with_mapped_file(ruby, &p, |map| stats_over(ruby, &map, opts))
+    with_mapped_file(ruby, &p, |map| stats_over(ruby, &map, &o))
 }

data/lib/nosj/json.rb

@@ -12,12 +12,18 @@
 # Entry points built on JSON.parse (JSON.load, JSON.parse!,
 # JSON.load_file, JSON.unsafe_load) pick up the fast path automatically
 # and keep their exact legacy behavior when they need unsupported options
-# (JSON.load's create_additions default always takes the fallback).
+# (json 2's JSON.load passes create_additions, so it always takes the
+# fallback).
 #
-# Exceptions from the fast path are re-raised as the JSON classes
-# (JSON::ParserError, JSON::GeneratorError, JSON::NestingError), so
-# existing rescue clauses keep working. Parse error MESSAGES are
-# NOSJ's (byte offsets rather than the gem's phrasing).
+# The drop-in follows whichever json is installed, 2.x or 3.x: its
+# calling conventions (json 3's keyword-only parse, its dump defaults)
+# and its semantics. NOSJ implements json 3's (duplicate keys and lone
+# surrogates are errors), so whenever the fast path refuses a call, the
+# original gem runs it again and has the last word: json 2 accepts what
+# it always accepted, and every exception is the gem's own, message,
+# json_path and invalid_object included. That second pass happens on
+# failures only; a generate run twice this way calls to_json on the
+# objects visited before the refusal twice.
 #
 # Not rerouted: obj.to_json (core extensions drive the gem's generator
 # directly), and objects with a custom to_json inside a rerouted
@@ -30,15 +36,26 @@ module NOSJ
   # Implementation detail of `require "nosj/json"`.
   # @private
   module JSONDropIn
-    # quirks_mode rides the fast path because NOSJ.parse is always
-    # quirks-mode (top-level scalars parse) and ignores the key; Rails
-    # 7.x passes it from ActiveSupport::JSON.decode.
+    # json 3 made parse's options keyword-only, fixed dump's defaults and
+    # raises for options json 2 ignored or aliased.
+    JSON3 = ::JSON::VERSION.to_i >= 3
+
     PARSE_OPTS = %i[symbolize_names freeze max_nesting allow_nan
-      allow_trailing_comma quirks_mode].freeze
+      allow_trailing_comma allow_duplicate_key].freeze
+    # json 2 ignores quirks_mode, which Rails 7.x passes from
+    # ActiveSupport::JSON.decode, so its fast path takes the key and
+    # drops it (NOSJ.parse always parses top-level scalars, and refuses
+    # unknown keys). json 3 raises for it, so there it reaches the gem
+    # like any other unknown option.
+    QUIRKS_MODE = :quirks_mode
+    JSON2_PARSE_OPTS = (PARSE_OPTS + [QUIRKS_MODE]).freeze
     GENERATE_OPTS = %i[indent space space_before object_nl array_nl
-      max_nesting allow_nan ascii_only script_safe
-      escape_slash strict depth
-      buffer_initial_length].freeze
+      max_nesting allow_nan ascii_only script_safe strict depth
+      buffer_initial_length allow_duplicate_key].freeze
+    JSON3_DUMP_DEFAULTS = {allow_nan: true}.freeze
+    # json 2.10 and older accept only strict: in dump's options hash,
+    # through this private helper; later versions merge any option.
+    DUMP_MERGES_OPTIONS = !::JSON.respond_to?(:merge_dump_options, true)
 
     module_function
 
@@ -52,6 +69,13 @@ module NOSJ
       true
     end
 
+    # Generate options the fast path handles: supported keys, minus the
+    # one combination NOSJ refuses (ascii_only with script_safe, which
+    # json supports).
+    def generate_supported?(opts)
+      supported?(opts, GENERATE_OPTS) && !(opts && opts[:ascii_only] && opts[:script_safe])
+    end
+
     def parse(source, opts)
       # NOSJ.parse is deliberately strict about encodings (json-3.0
       # semantics), but the drop-in must match the installed gem, which
@@ -61,30 +85,60 @@ module NOSJ
       # (copy-on-write bytes), and the validity scan is memoized
       # coderange the parse would compute anyway. Anything else
       # non-UTF-8 (UTF-16, ...) belongs to gem json, which transcodes.
+      input = source
       if source.is_a?(String)
         case source.encoding
         when Encoding::UTF_8, Encoding::US_ASCII
         # the fast path as-is
         when Encoding::BINARY
           utf8 = source.dup.force_encoding(Encoding::UTF_8)
-          source = utf8 if utf8.valid_encoding?
+          input = utf8 if utf8.valid_encoding?
         else
-          return ::JSON.nosj_original_parse(source, **(opts || {}))
+          return original_parse(source, opts)
         end
       end
-      NOSJ.parse(source, opts)
-    rescue NOSJ::NestingError => e
-      raise ::JSON::NestingError, e.message
-    rescue NOSJ::ParserError => e
-      raise ::JSON::ParserError, e.message
+      NOSJ.parse(input, opts)
+    rescue NOSJ::ParserError, NOSJ::NestingError
+      original_parse(source, opts)
+    end
+
+    # json 2's options without quirks_mode (see QUIRKS_MODE), allocating
+    # nothing for Rails' lone `quirks_mode: true`.
+    def without_quirks_mode(opts)
+      return opts unless opts&.key?(QUIRKS_MODE)
+      if opts.size == 1
+        nil
+      else
+        opts.except(QUIRKS_MODE)
+      end
+    end
+
+    # The installed gem's parse. json 3 takes keywords only; json 2's
+    # positional options hash receives them just the same.
+    def original_parse(source, opts)
+      ::JSON.nosj_original_parse(source, **(opts || {}))
     end
 
     def generate(obj, opts, pretty)
       pretty ? NOSJ.pretty_generate(obj, opts) : NOSJ.generate(obj, opts)
-    rescue NOSJ::NestingError => e
-      raise ::JSON::NestingError, e.message
-    rescue NOSJ::GeneratorError => e
-      raise ::JSON::GeneratorError, e.message
+    rescue NOSJ::GeneratorError, NOSJ::NestingError
+      if pretty
+        ::JSON.nosj_original_pretty_generate(obj, opts)
+      else
+        ::JSON.nosj_original_generate(obj, opts)
+      end
+    end
+
+    # The options JSON.dump generates with before the caller's own: fixed
+    # in json 3; json 2 reads its user-settable dump_default_options,
+    # through the internal reader 2.11 added when it deprecated the
+    # public one. Which one is decided here, once.
+    if JSON3
+      def dump_defaults = JSON3_DUMP_DEFAULTS
+    elsif ::JSON.respond_to?(:_dump_default_options)
+      def dump_defaults = ::JSON._dump_default_options
+    else
+      def dump_defaults = ::JSON.dump_default_options
     end
   end
 end
@@ -101,16 +155,26 @@ module JSON
       alias_method :nosj_original_pretty_generate, :pretty_generate
       alias_method :nosj_original_dump, :dump
 
-      def parse(source, opts = nil)
-        if NOSJ::JSONDropIn.supported?(opts, NOSJ::JSONDropIn::PARSE_OPTS)
-          NOSJ::JSONDropIn.parse(source, opts)
-        else
-          nosj_original_parse(source, opts)
+      if NOSJ::JSONDropIn::JSON3
+        def parse(source, **opts)
+          if NOSJ::JSONDropIn.supported?(opts, NOSJ::JSONDropIn::PARSE_OPTS)
+            NOSJ::JSONDropIn.parse(source, opts)
+          else
+            nosj_original_parse(source, **opts)
+          end
+        end
+      else
+        def parse(source, opts = nil)
+          if NOSJ::JSONDropIn.supported?(opts, NOSJ::JSONDropIn::JSON2_PARSE_OPTS)
+            NOSJ::JSONDropIn.parse(source, NOSJ::JSONDropIn.without_quirks_mode(opts))
+          else
+            nosj_original_parse(source, opts)
+          end
         end
       end
 
       def generate(obj, opts = nil)
-        if NOSJ::JSONDropIn.supported?(opts, NOSJ::JSONDropIn::GENERATE_OPTS)
+        if NOSJ::JSONDropIn.generate_supported?(opts)
           NOSJ::JSONDropIn.generate(obj, opts, false)
         else
           nosj_original_generate(obj, opts)
@@ -118,7 +182,7 @@ module JSON
       end
 
       def pretty_generate(obj, opts = nil)
-        if NOSJ::JSONDropIn.supported?(opts, NOSJ::JSONDropIn::GENERATE_OPTS)
+        if NOSJ::JSONDropIn.generate_supported?(opts)
           NOSJ::JSONDropIn.generate(obj, opts, true)
         else
           nosj_original_pretty_generate(obj, opts)
@@ -127,17 +191,19 @@ module JSON
 
       def dump(obj, an_io = nil, limit = nil, kwargs = nil)
         # Fast path for the common shapes, dump(obj) and dump(obj, opts
-        # hash), mirroring gem json: dump defaults merged under the
-        # user's options, NestingError surfaced as ArgumentError. IO and
-        # limit arguments take gem json's own dump.
-        if limit.nil? && kwargs.nil? && (an_io.nil? || an_io.instance_of?(Hash))
-          opts = _dump_default_options
+        # hash): the installed gem's dump defaults merged under the
+        # caller's options. IO and limit arguments, and anything the
+        # fast path refuses, take gem json's own dump, which also turns
+        # json 2's NestingError into its ArgumentError.
+        if limit.nil? && kwargs.nil? &&
+            (an_io.nil? || NOSJ::JSONDropIn::DUMP_MERGES_OPTIONS && an_io.instance_of?(Hash))
+          opts = NOSJ::JSONDropIn.dump_defaults
           opts = opts.merge(an_io) if an_io
-          if NOSJ::JSONDropIn.supported?(opts, NOSJ::JSONDropIn::GENERATE_OPTS)
+          if NOSJ::JSONDropIn.generate_supported?(opts)
             begin
-              return NOSJ::JSONDropIn.generate(obj, opts, false)
-            rescue ::JSON::NestingError
-              raise ArgumentError, "exceed depth limit"
+              return NOSJ.generate(obj, opts)
+            rescue NOSJ::GeneratorError, NOSJ::NestingError
+              # the gem's own dump below runs it again and decides
             end
           end
         end

data/lib/nosj/version.rb

@@ -2,5 +2,5 @@
 
 module NOSJ
   # The gem version.
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/nosj.rb

@@ -86,10 +86,13 @@ module NOSJ
   # Parses a JSON document, JSON.parse-compatible: same values, same
   # option names, same behavior, byte-for-byte.
   #
-  # The +json+ gem's legacy object-deserialization options
-  # (+object_class+, +array_class+, +decimal_class+,
-  # +create_additions+) are deliberately unsupported and raise
-  # ArgumentError.
+  # Options follow json 3: an unknown key raises ArgumentError
+  # (<code>unknown keyword: foo</code>). The json options nosj does not
+  # implement (+object_class+, +array_class+, +decimal_class+,
+  # +on_load+, +create_additions+, +allow_comments+,
+  # +allow_control_characters+, +allow_invalid_escape+) raise
+  # ArgumentError unless falsy, since their falsy default is nosj's
+  # behavior.
   #
   # @example
   #   NOSJ.parse('{"a":[1,true]}')                      #=> {"a" => [1, true]}
@@ -98,12 +101,14 @@ module NOSJ
   # @param source [String] the JSON document (UTF-8 or US-ASCII)
   # @param opts [Hash, nil] +symbolize_names+, +freeze+, +max_nesting+
   #   (Integer or +false+ for unlimited), +allow_nan+,
-  #   +allow_trailing_comma+
+  #   +allow_trailing_comma+, +allow_duplicate_key+ (json 3 semantics:
+  #   a repeated key raises unless this is true, then the last one wins)
   # @return [Object] the parsed value tree
-  # @raise [ParserError] when the document is malformed or not UTF-8;
-  #   carries the failure position ({ParserError#line} and friends)
+  # @raise [ParserError] when the document is malformed, repeats a key,
+  #   holds a lone surrogate (+"\udc00"+), or is not UTF-8; carries the
+  #   failure position ({ParserError#line} and friends)
   # @raise [NestingError] when nesting exceeds +max_nesting+
-  # @raise [ArgumentError] for unsupported options
+  # @raise [ArgumentError] for unknown or unsupported options
   def self.parse(source, opts = nil)
     parse_native(source, opts)
   end
@@ -119,12 +124,18 @@ module NOSJ
   #   @param obj [Object] the value tree to serialize
   #   @param opts [Hash, nil] +indent+, +space+, +space_before+,
   #     +object_nl+, +array_nl+, +max_nesting+ (Integer or +false+),
-  #     +allow_nan+, +ascii_only+, +script_safe+ (alias +escape_slash+),
-  #     +strict+, +depth+, +buffer_initial_length+
+  #     +allow_nan+, +ascii_only+, +script_safe+, +strict+, +depth+,
+  #     +buffer_initial_length+, +allow_duplicate_key+ (json 3
+  #     semantics: keys that render alike, like <code>"a"</code> and
+  #     <code>:a</code>, raise unless true). As in json 3, an unknown
+  #     key raises (+escape_slash+ is gone: use +script_safe+), and the
+  #     unimplemented +sort_keys+ and +as_json+ raise unless falsy.
   #   @return [String] the JSON document
   #   @raise [GeneratorError] for non-finite floats without +allow_nan+,
-  #     unsupported objects under +strict+, or broken string encodings
+  #     unsupported objects under +strict+, keys that render alike, or
+  #     broken string encodings
   #   @raise [NestingError] when nesting exceeds +max_nesting+
+  #   @raise [ArgumentError] for unknown or unsupported options
 
   # Generates human-readable JSON, JSON.pretty_generate-compatible
   # (two-space indent, newlines between elements). Options override the
@@ -156,7 +167,7 @@ module NOSJ
   # @param source [String] the JSON document
   # @param opts [Hash, nil] same options as {.parse}
   # @return [Boolean]
-  # @raise [ArgumentError] for unsupported options
+  # @raise [ArgumentError] for unknown or unsupported options
   def self.valid?(source, opts = nil)
     valid_native(source, opts)
   end
@@ -205,7 +216,8 @@ module NOSJ
 
   # Partial parsing by JSON Pointer (with the standard +~0+/+~1+
   # escapes). The matched subtree materializes under the same options
-  # as {.parse}.
+  # as {.parse}; +allow_nan+ and +allow_trailing_comma+ also govern the
+  # walk to it.
   #
   # @example
   #   NOSJ.at_pointer(json, "/users/3/name")  #=> "grace" or nil
@@ -322,18 +334,19 @@ module NOSJ
   # Minifies a document without building any Ruby values: the parser's
   # events pipe straight into the emission kernels, SIMD in and SIMD
   # out. Output is exactly what <code>generate(parse(json))</code>
-  # would produce, except duplicate object keys pass through instead of
-  # being collapsed (a reformatter must not silently drop data).
-  # Numbers come out in the canonical spelling (+1.50+ becomes +1.5+)
-  # and string escapes are normalized.
+  # would produce, and it accepts exactly what {.parse} accepts; under
+  # +allow_duplicate_key+, repeated keys pass through instead of being
+  # collapsed (a reformatter must not silently drop data). Numbers come
+  # out in the canonical spelling (+1.50+ becomes +1.5+) and string
+  # escapes are normalized.
   #
   # @example
   #   NOSJ.minify(%({ "a": [1, 2],\n  "b": "x" }))  #=> '{"a":[1,2],"b":"x"}'
   #
   # @param json [String] the document (UTF-8 or US-ASCII)
   # @param opts [Hash, nil] acceptance options (+allow_nan+,
-  #   +allow_trailing_comma+, +max_nesting+); trailing commas are
-  #   normalized away when accepted
+  #   +allow_trailing_comma+, +allow_duplicate_key+, +max_nesting+);
+  #   trailing commas are normalized away when accepted
   # @return [String] the minified document
   # @raise [ParserError] when the document is malformed
   # @raise [NestingError] past +max_nesting+
@@ -357,8 +370,7 @@ module NOSJ
   # @return [String] the reformatted document
   # @raise [ParserError] when the document is malformed
   # @raise [NestingError] past +max_nesting+
-  # @raise [GeneratorError] when +ascii_only+ meets a lone-surrogate
-  #   string it cannot represent
+  # @raise [GeneratorError] for a non-finite float without +allow_nan+
   def self.reformat(json, opts = nil)
     if opts&.key?(:pretty)
       pretty = opts[:pretty]
@@ -597,7 +609,9 @@ module NOSJ
   #
   # @param source [String] the JSON document (UTF-8 or US-ASCII)
   # @param opts [Hash, nil] +max_nesting+, +allow_nan+,
-  #   +allow_trailing_comma+ (acceptance options only)
+  #   +allow_trailing_comma+ (acceptance options only). Being a
+  #   diagnostic, stats also describes documents {.parse} would refuse
+  #   for a repeated key or a lone surrogate.
   # @return [Hash] the statistics described above
   # @raise [ParserError] when the document is malformed or not UTF-8
   def self.stats(source, opts = nil)

data/sig/nosj.rbs

@@ -14,9 +14,10 @@ module NOSJ
   # Options arrive as a positional Hash (the JSON gem's own calling
   # convention; an explicit **kwargs would allocate per call), nil when
   # omitted. Parse: symbolize_names, freeze, max_nesting, allow_nan,
-  # allow_trailing_comma. Generate: indent, space, space_before,
-  # object_nl, array_nl, max_nesting, allow_nan, ascii_only,
-  # script_safe/escape_slash, strict, depth, buffer_initial_length.
+  # allow_trailing_comma, allow_duplicate_key. Generate: indent, space,
+  # space_before, object_nl, array_nl, max_nesting, allow_nan,
+  # ascii_only, script_safe, strict, depth, buffer_initial_length,
+  # allow_duplicate_key. Unknown keys raise ArgumentError (json 3).
   type opts = Hash[Symbol, untyped]?
 
   # One NOSJ.dig path element (negative Integer indices resolve to nil).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nosj
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Yaroslav Markin
@@ -64,6 +64,8 @@ files:
 - ext/nosj/src/lazy.rs
 - ext/nosj/src/lib.rs
 - ext/nosj/src/lines.rs
+- ext/nosj/src/locate.rs
+- ext/nosj/src/opt_reader.rs
 - ext/nosj/src/parse.rs
 - ext/nosj/src/patch.rs
 - ext/nosj/src/pointer.rs
@@ -104,7 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 3.3.11
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: An extremely fast JSON parser and generator for Ruby, written in Rust and
   SIMD-accelerated on every platform.