smarter_json 0.5.2

data/docs/examples.md

@@ -0,0 +1,140 @@
+
+### Contents
+
+  * [Introduction](./_introduction.md)
+  * [The Basic Read API](./basic_read_api.md)
+  * [The Basic Write API](./basic_write_api.md)
+  * [Configuration Options](./options.md)
+  * [**Examples**](./examples.md)
+
+--------------
+
+# Examples
+
+**Rescue from `SmarterJSON::Error` (recommended):** SmarterJSON raises only on genuinely unparseable input (an unterminated string, a mismatched bracket), with line and column in the message. Rescuing from `SmarterJSON::Error` lets your application handle bad input gracefully.
+
+---
+
+1. [Read a JSON String](#example-1-read-a-json-string)
+2. [Read a JSON File](#example-2-read-a-json-file)
+3. [Implicit Root Object (config-style, no braces)](#example-3-implicit-root-object-config-style-no-braces)
+4. [Multiple Documents (NDJSON) → Array](#example-4-multiple-documents-ndjson--array)
+5. [Streaming a Large File with a Block](#example-5-streaming-a-large-file-with-a-block)
+6. [Symbolize Keys](#example-6-symbolize-keys)
+7. [Duplicate Keys](#example-7-duplicate-keys)
+8. [High-Precision Numbers: BigDecimal vs Float](#example-8-high-precision-numbers-bigdecimal-vs-float)
+9. [Lenient Input: Comments, Trailing Commas, Unquoted Keys](#example-9-lenient-input-comments-trailing-commas-unquoted-keys)
+10. [Write JSON](#example-10-write-json)
+11. [Write NDJSON](#example-11-write-ndjson)
+12. [Round-Trip Read and Write](#example-12-round-trip-read-and-write)
+
+---
+
+### Example 1: Read a JSON String
+
+```ruby
+require "smarter_json"
+
+SmarterJSON.process('{"a": 1, "b": [2, 3]}')   # => {"a"=>1, "b"=>[2, 3]}
+```
+
+### Example 2: Read a JSON File
+
+```ruby
+SmarterJSON.process_file("config.json")        # => the parsed value
+```
+
+`process_file` opens the file, reads it with the labeled [`encoding:`](./options.md) (default `"UTF-8"`), and parses it.
+
+### Example 3: Implicit Root Object (config-style, no braces)
+
+A config file that starts with `key: value` and has no outer `{}` is read as an object:
+
+```ruby
+SmarterJSON.process("host: localhost\nport: 5432")   # => {"host"=>"localhost", "port"=>5432}
+```
+
+### Example 4: Multiple Documents (NDJSON) → Array
+
+Plain `process` reads NDJSON / JSONL / concatenated documents with no block and no special method. Zero documents → `nil`, one → its value, two or more → an `Array`:
+
+```ruby
+SmarterJSON.process(%({"id":1}\n{"id":2}\n{"id":3}))   # => [{"id"=>1}, {"id"=>2}, {"id"=>3}]
+SmarterJSON.process('{"id":1}')                          # => {"id"=>1}
+SmarterJSON.process("")                                  # => nil
+```
+
+### Example 5: Streaming a Large File with a Block
+
+For input larger than memory, pass a block. Each document is yielded as it is read; the whole file is never loaded:
+
+```ruby
+SmarterJSON.process_file("events.ndjson") { |event| EventJob.perform_async(event) }
+```
+
+### Example 6: Symbolize Keys
+
+```ruby
+SmarterJSON.process('{"a": 1, "b": 2}', symbolize_keys: true)   # => {:a=>1, :b=>2}
+```
+
+### Example 7: Duplicate Keys
+
+By default the last value wins. Choose `:first_wins` or `:raise` instead:
+
+```ruby
+SmarterJSON.process('{"a":1,"a":2}')                          # => {"a"=>2}   (:last_wins, the default)
+SmarterJSON.process('{"a":1,"a":2}', duplicate_key: :first_wins)  # => {"a"=>1}
+SmarterJSON.process('{"a":1,"a":2}', duplicate_key: :raise)   # raises SmarterJSON::ParseError
+```
+
+### Example 8: High-Precision Numbers: BigDecimal vs Float
+
+The default `:auto` keeps high-precision decimals as `BigDecimal` (matching Oj). Force `Float` for raw speed when you don't need the precision:
+
+```ruby
+SmarterJSON.process("65.613616999999977")                        # => BigDecimal (:auto, the default)
+SmarterJSON.process("65.613616999999977", bigdecimal_load: :float)  # => 65.613616999999977 (a Float)
+```
+
+### Example 9: Lenient Input: Comments, Trailing Commas, Unquoted Keys
+
+```ruby
+SmarterJSON.process(<<~JSON)
+  {
+    host: localhost,   # unquoted key, quoteless value, and a trailing comma
+    port: 5432,
+    /* block comment */
+    url: http://example.com
+  }
+JSON
+# => {"host"=>"localhost", "port"=>5432, "url"=>"http://example.com"}
+```
+
+A `#`/`//` only starts a comment when preceded by whitespace, so `http://example.com` stays a string rather than being truncated.
+
+### Example 10: Write JSON
+
+```ruby
+SmarterJSON.generate({ "a" => 1, "b" => [2, 3] })   # => '{"a":1,"b":[2,3]}'
+SmarterJSON.generate([1, 2, 3])                       # => '[1,2,3]'
+```
+
+### Example 11: Write NDJSON
+
+An Array writes one element per line:
+
+```ruby
+SmarterJSON.generate([{ "id" => 1 }, { "id" => 2 }], format: :ndjson)   # => "{\"id\":1}\n{\"id\":2}\n"
+```
+
+### Example 12: Round-Trip Read and Write
+
+```ruby
+obj = { "a" => 1, "b" => [2, "three", nil, true] }
+SmarterJSON.process(SmarterJSON.generate(obj)) == obj   # => true
+```
+
+---------------
+
+PREVIOUS: [Configuration Options](./options.md) | UP: [README](../README.md)

data/docs/options.md

@@ -0,0 +1,69 @@
+
+### Contents
+
+  * [Introduction](./_introduction.md)
+  * [The Basic Read API](./basic_read_api.md)
+  * [The Basic Write API](./basic_write_api.md)
+  * [**Configuration Options**](./options.md)
+  * [Examples](./examples.md)
+
+--------------
+
+# Configuration Options
+
+## Reading
+
+These options are passed to [`SmarterJSON.process`](./basic_read_api.md) and `SmarterJSON.process_file` as the second argument; anything you set overrides the defaults below.
+
+| Option            | Default      | Explanation                                                                                                            |
+|-------------------|--------------|------------------------------------------------------------------------------------------------------------------------|
+| `:symbolize_keys` | `false`      | Return object keys as Symbols instead of Strings.                                                                      |
+| `:duplicate_key`  | `:last_wins` | How to handle a key that repeats within one object: `:last_wins`, `:first_wins`, or `:raise`.                          |
+| `:bigdecimal_load`| `:auto`      | `:auto` keeps high-precision decimals as `BigDecimal` (matches Oj); `:float` forces every number to `Float`; `:bigdecimal` forces every decimal to `BigDecimal`. |
+| `:acceleration`   | `true`       | Use the C extension when it is compiled and loadable; `false` forces the pure-Ruby parser. Both produce identical results. |
+| `:encoding`       | `nil`        | Labels the input's encoding (e.g. `"UTF-8"`). It does **not** trigger a transcoding pass — see below.                  |
+
+```ruby
+SmarterJSON.process('{"a": 1}', symbolize_keys: true)               # => {:a=>1}
+SmarterJSON.process('{"a":1,"a":2}', duplicate_key: :raise)         # raises SmarterJSON::ParseError
+SmarterJSON.process(big_decimal_json, bigdecimal_load: :float)      # every number as Float (fastest)
+```
+
+### A note on `:encoding`
+
+`:encoding` labels what the input *is* — it does not transcode. The parser works on the bytes in their native encoding and emits string values with the same encoding tag, the same way `smarter_csv` handles encodings. Bytes that are invalid for the claimed encoding raise `SmarterJSON::EncodingError` (a kind of `SmarterJSON::ParseError`). A UTF-8 BOM is handled automatically; UTF-16 / UTF-32 input is out of scope.
+
+### A note on `:bigdecimal_load`
+
+The default `:auto` preserves high-precision numbers as `BigDecimal`, matching Oj's default. That is intrinsically slower than producing `Float` on number-heavy files (e.g. `canada.json`). For raw speed when you don't need the extra precision, pass `bigdecimal_load: :float`.
+
+## Writing
+
+These options are passed to [`SmarterJSON.generate`](./basic_write_api.md) as the second argument.
+
+| Option     | Default | Explanation                                                                                                                |
+|------------|---------|-----------------------------------------------------------------------------------------------------------------------------|
+| `:format`       | `:json` | `:json` writes standard JSON (Hash → object, Array → array, scalar → scalar). `:ndjson` writes newline-delimited JSON: an Array becomes one element per line, any other value becomes a single line. |
+| `:indent`       | `0`     | Spaces per nesting level for pretty-printing. `0` (the default) is compact output. Empty objects/arrays stay inline. Not allowed with `:ndjson` (a record must be a single line). |
+| `:sort_keys`    | `false` | Emit object keys in sorted order (Symbol keys sorted by their string form). Useful for canonical, diff-friendly output. |
+| `:ascii_only`   | `false` | Escape every non-ASCII character as `\uXXXX` (astral characters as a UTF-16 surrogate pair). The default emits raw UTF-8. |
+| `:script_safe`  | `false` | Escape the `/` in `</` and the JS line separators U+2028 / U+2029, so output is safe to embed in an HTML `<script>` tag. |
+| `:coerce`       | `false` | When `true`, a value that isn't natively supported is converted by its own `as_json` (the result is re-emitted, so the other options still apply) or, failing that, `to_json` (spliced verbatim). When `false` (the default), such a value raises `SmarterJSON::GenerateError`. |
+
+Any other `:format` value, a negative/non-Integer `:indent`, or combining `:indent` with `:ndjson`, raises `ArgumentError`.
+
+```ruby
+SmarterJSON.generate([1, 2, 3])                              # => "[1,2,3]"   (default :json — a single JSON array)
+SmarterJSON.generate([1, 2, 3], format: :ndjson)            # => "1\n2\n3\n" (one element per line)
+SmarterJSON.generate({ "a" => 1 }, indent: 2)               # => "{\n  \"a\": 1\n}"  (pretty-printed)
+SmarterJSON.generate({ "b" => 2, "a" => 1 }, sort_keys: true) # => '{"a":1,"b":2}'
+SmarterJSON.generate("café", ascii_only: true)              # => '"caf\u00e9"'
+SmarterJSON.generate("</script>", script_safe: true)        # => '"<\/script>"'
+SmarterJSON.generate(model, coerce: true)                   # => uses model.as_json (else model.to_json)
+SmarterJSON.generate(model)                                 # raises SmarterJSON::GenerateError (coerce off)
+SmarterJSON.generate({}, format: :bogus)                    # raises ArgumentError
+```
+
+---------------
+
+PREVIOUS: [The Basic Write API](./basic_write_api.md) | NEXT: [Examples](./examples.md) | UP: [README](../README.md)

data/ext/smarter_json/extconf.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rbconfig"
+
+# Ruby sometimes ships CFLAGS with "-g -O3"; drop the debug half so the
+# extension is built optimized, not with debug info.
+if RbConfig::MAKEFILE_CONFIG["CFLAGS"].include?("-g -O3")
+  RbConfig::MAKEFILE_CONFIG["CFLAGS"] = RbConfig::MAKEFILE_CONFIG["CFLAGS"].sub("-g -O3", "-O3 $(cflags)")
+end
+
+optflags = "-O3 -flto -fomit-frame-pointer -DNDEBUG".dup
+# -march=native is skipped on arm64-darwin (Apple clang already targets the host).
+optflags << " -march=native" unless RUBY_PLATFORM.start_with?("arm64-darwin")
+# -fno-semantic-interposition: GCC/Clang only (not MSVC).
+optflags << " -fno-semantic-interposition" unless RUBY_PLATFORM.include?("mswin")
+
+CONFIG["optflags"]   = optflags
+CONFIG["debugflags"] = ""
+
+# rb_enc_interned_str (Ruby 3.0+) lets us intern object keys straight from the
+# input bytes; on older Rubies the C code falls back to a plain new string.
+have_func("rb_enc_interned_str", "ruby.h")
+
+# Pre-sized hashes (3.2+) and bulk insert (2.6+) for object building; the C code
+# falls back to rb_hash_new + per-pair aset when these are unavailable.
+have_func("rb_hash_new_capa", "ruby.h")
+have_func("rb_hash_bulk_insert", "ruby.h")
+
+create_makefile("smarter_json/smarter_json")