smarter_json 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbc1f54c56cf5a1fd4c569660faf9f4115e5e7ed8442ac9e8e7105bc880a3912
-  data.tar.gz: 5e68d7b1dafa55347cf5de1ee10e8ac39a97b645996fd0c58538799bbbb1191d
+  metadata.gz: 44970fff9a74d5d18ef8ce1f909afb35ed8db60e92e7fd6ddee0d399ed98f826
+  data.tar.gz: 6b02c6491a049ce306bc07de1b5bb06cf71ec14a579f2f6a659ffc634b1b2555
 SHA512:
-  metadata.gz: 0e84fb4caf1fc9b192aa0e88f5111c3178557078abd8a31e7ce73373590e2487344c8df9ad61e718756e78a15239b460fd05b5f7a6fdbede35d8859f1873f5be
-  data.tar.gz: 9d808b8b3e8465ce7b12ae861053e67a77ef1550df425c6383ffe4b799ba401a6f927f692b09709942fdb9e690a1c9d25a5f4453d57b9b532e18f979d171199d
+  metadata.gz: 3040050ab8538786344d7cdafb7959b0b28e2c869b2c5c5609228226de4cc52f2a70a8460c97790f537c19eb44a6defb7774ca8945aacd26ae2040684f3587c6
+  data.tar.gz: 389be8c3a940d29cfef4bf14df69c4f917fcb6fc1ff37d4c3fc4c3ec716c3985363a408d17ebc303370a110f057e7fdd200f726a46d05966b83b9e5eb6ac446d

data/CHANGELOG.md

@@ -1,6 +1,11 @@
 
 # SmarterJSON Change Log
 
+## 0.5.2 (2026-06-01)
+- `generate` now supports pretty-printing via the `indent:` option (spaces per nesting level; default `0` = compact). Empty objects/arrays stay inline; `indent:` combined with `format: :ndjson` raises `ArgumentError`.
+- `generate` adds `sort_keys:` (emit object keys in sorted order), `ascii_only:` (escape non-ASCII as `\uXXXX`, astral chars as surrogate pairs), and `script_safe:` (escape `</` and U+2028/U+2029 for safe embedding in an HTML `<script>` tag).
+- `generate` adds opt-in `coerce:` — when `true`, a value that isn't natively supported (e.g. `Time`, `Date`, app objects) is converted via its own `as_json` (result re-emitted) or `to_json` (spliced); strict-by-default still raises `GenerateError`.
+
 ## 0.5.1 (2026-06-01)
 - Unified the error classes under a single `SmarterJSON::Error` base: `ParseError` and `EncodingError` now inherit from it, and `generate` raises a new `GenerateError`. `rescue SmarterJSON::Error` now catches everything the gem raises.
 - Added a CI test matrix (Ruby 2.6–4.0 + head, on Ubuntu and macOS).

data/README.md

@@ -1,6 +1,6 @@
 # SmarterJSON
 
-![Gem Version](https://img.shields.io/gem/v/smarter_json) [![codecov](https://codecov.io/gh/tilo/smarter_json/branch/main/graph/badge.svg)](https://codecov.io/gh/tilo/smarter_json) [![Downloads](https://img.shields.io/gem/dt/smarter_json)](https://rubygems.org/gems/smarter_json) [![RubyGems](https://img.shields.io/badge/RubyGems-smarter__json-brightgreen?logo=rubygems&logoColor=white)](https://rubygems.org/gems/smarter_json) [![Ruby Toolbox](https://img.shields.io/badge/Ruby%20Toolbox-smarter__json-brightgreen)](https://www.ruby-toolbox.com/projects/smarter_json)
+![Gem Version](https://img.shields.io/gem/v/smarter_json) [![codecov](https://codecov.io/gh/tilo/smarter_json/branch/main/graph/badge.svg)](https://codecov.io/gh/tilo/smarter_json) <!-- [![Downloads](https://img.shields.io/gem/dt/smarter_json)](https://rubygems.org/gems/smarter_json) --> [![RubyGems](https://img.shields.io/badge/RubyGems-smarter__json-brightgreen?logo=rubygems&logoColor=white)](https://rubygems.org/gems/smarter_json) [![Ruby Toolbox](https://img.shields.io/badge/Ruby%20Toolbox-smarter__json-brightgreen)](https://www.ruby-toolbox.com/projects/smarter_json)
 
 A lenient, fast JSON parser for Ruby. It parses strict JSON, JSON5, HJSON-style config, and the messy JSON-ish input humans actually write — and in benchmarks it matches or beats Oj on nearly every file. SmarterJSON is opinionated: we want your JSON processing to be successful. Other parsers are strict - they stop at the first deviation - SmarterJSON keeps going - it optimizes for getting your data out, not for policing the JSON spec.
 

data/docs/basic_write_api.md

@@ -53,12 +53,65 @@ Strings escape `"`, `\`, and the control characters `0x00–0x1F`; everything el
 `generate` raises `SmarterJSON::Error` on input it cannot represent as strict JSON:
 
 ```ruby
-SmarterJSON.generate(Time.now)          # raises SmarterJSON::Error — unsupported type
-SmarterJSON.generate(Float::INFINITY)   # raises SmarterJSON::Error — non-finite Float
-SmarterJSON.generate(Float::NAN)        # raises SmarterJSON::Error — non-finite Float
+SmarterJSON.generate(Time.now)          # raises SmarterJSON::GenerateError — unsupported type
+SmarterJSON.generate(Float::INFINITY)   # raises SmarterJSON::GenerateError — non-finite Float
+SmarterJSON.generate(Float::NAN)        # raises SmarterJSON::GenerateError — non-finite Float
 ```
 
-(`Infinity` and `NaN` are accepted on the *read* side as a leniency, but they are not valid JSON to *write*.)
+(`GenerateError` is a kind of `SmarterJSON::Error`, so `rescue SmarterJSON::Error` catches it. `Infinity` and `NaN` are accepted on the *read* side as a leniency, but they are not valid JSON to *write*.)
+
+By default `generate` is strict: it only writes the types above and raises on anything else. To serialize `Time`, `Date`, or your own objects, pass `coerce: true` — an unsupported value is then converted by its own `as_json` (whose result is re-emitted, so escaping/`indent`/`sort_keys` still apply) or, failing that, `to_json` (spliced verbatim):
+
+```ruby
+class Money
+  def as_json(*)
+    { "cents" => @cents, "currency" => @currency }
+  end
+end
+
+SmarterJSON.generate({ "price" => Money.new(500, "USD") }, coerce: true)
+# => '{"price":{"cents":500,"currency":"USD"}}'
+```
+
+Strict-by-default stays the default precisely so you opt in to delegating serialization rather than silently emitting an object's `to_s`. See [Configuration Options](./options.md).
+
+## Pretty-printing
+
+By default `generate` produces compact output (no spaces). Pass `indent:` (a number of spaces per nesting level) to pretty-print:
+
+```ruby
+SmarterJSON.generate({ "a" => 1, "b" => [2, 3] }, indent: 2)
+# => "{\n  \"a\": 1,\n  \"b\": [\n    2,\n    3\n  ]\n}"
+```
+
+which prints as:
+
+```json
+{
+  "a": 1,
+  "b": [
+    2,
+    3
+  ]
+}
+```
+
+Empty objects and arrays stay inline (`{}` / `[]`) even when indenting. `indent: 0` (the default) is compact output. Pretty-printing is multi-line, so it can't be combined with `format: :ndjson` (where each record must be a single line) — doing so raises `ArgumentError`. See [Configuration Options](./options.md).
+
+## Safe and canonical output
+
+Three more options shape the output, and they compose with each other and with `indent:`:
+
+- **`sort_keys: true`** — emit object keys in sorted order (Symbol keys sorted by their string form). Handy for canonical, diff-friendly JSON.
+- **`ascii_only: true`** — escape every non-ASCII character as `\uXXXX` (characters above U+FFFF become a UTF-16 surrogate pair). The default emits raw UTF-8.
+- **`script_safe: true`** — escape the `/` in `</` and the JavaScript line separators U+2028 / U+2029, so the output is safe to embed directly in an HTML `<script>` tag without breaking out of it.
+
+```ruby
+SmarterJSON.generate({ "b" => 2, "a" => 1 }, sort_keys: true)   # => '{"a":1,"b":2}'
+SmarterJSON.generate("</script>", script_safe: true)            # => '"<\/script>"'
+```
+
+See [Configuration Options](./options.md) for the full table.
 
 ## Writing NDJSON
 

data/docs/options.md

@@ -39,18 +39,29 @@ The default `:auto` preserves high-precision numbers as `BigDecimal`, matching O
 
 ## Writing
 
-This option is passed to [`SmarterJSON.generate`](./basic_write_api.md) as the second argument.
+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. |
+| `: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 raises `ArgumentError`.
+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({}, format: :bogus)                 # raises ArgumentError
+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
 ```
 
 ---------------

data/lib/smarter_json/generator.rb

@@ -14,9 +14,13 @@ module SmarterJSON
   #                       line; any other value writes as a single line. The
   #                       inverse of process reading NDJSON back into an Array.
   #
+  # options[:indent]: spaces per nesting level for pretty-printing (Integer, default
+  #   0 = compact). Empty objects/arrays stay inline. Not allowed with :ndjson (a
+  #   record must be a single line) — combining them raises ArgumentError.
+  #
   # Symbol keys/values are emitted as strings; BigDecimal as a JSON number.
   # Unsupported types (Time, custom objects) and non-finite Floats raise
-  # SmarterJSON::Error. Returns a String.
+  # SmarterJSON::GenerateError. Returns a String.
   def generate(obj, options = {})
     Generator.new(options).generate(obj)
   end
@@ -35,6 +39,22 @@ module SmarterJSON
       unless %i[json ndjson].include?(@format)
         raise ArgumentError, "unknown writer format: #{@format.inspect} (expected :json or :ndjson)"
       end
+
+      @indent = options.fetch(:indent, 0) # spaces per nesting level; 0 = compact (default)
+      unless @indent.is_a?(Integer) && @indent >= 0
+        raise ArgumentError, "indent must be a non-negative Integer, got #{@indent.inspect}"
+      end
+      if @indent > 0 && @format == :ndjson
+        raise ArgumentError, "indent is not compatible with format: :ndjson (each record must be a single line)"
+      end
+
+      @pretty = @indent > 0
+
+      @ascii_only  = options.fetch(:ascii_only, false)  # escape non-ASCII as \uXXXX
+      @script_safe = options.fetch(:script_safe, false) # escape </ and U+2028 / U+2029
+      @sort_keys   = options.fetch(:sort_keys, false)   # emit object keys in sorted order
+      @coerce      = options.fetch(:coerce, false)      # convert unknown types via as_json / to_json
+      @escape_re   = build_escape_re
     end
 
     def generate(obj)
@@ -57,7 +77,7 @@ module SmarterJSON
 
     private
 
-    def emit(obj, buf)
+    def emit(obj, buf, level = 0)
       case obj
       when nil        then buf << "null"
       when true       then buf << "true"
@@ -67,39 +87,111 @@ module SmarterJSON
       when Integer    then buf << obj.to_s
       when Float      then emit_float(obj, buf)
       when BigDecimal then emit_bigdecimal(obj, buf)
-      when Array      then emit_array(obj, buf)
-      when Hash       then emit_hash(obj, buf)
+      when Array      then emit_array(obj, buf, level)
+      when Hash       then emit_hash(obj, buf, level)
       else
+        return emit_coerced(obj, buf, level) if @coerce
+
         raise SmarterJSON::GenerateError, "SmarterJSON.generate cannot serialize #{obj.class}"
       end
     end
 
-    def emit_array(arr, buf)
-      buf << "["
-      arr.each_with_index do |v, i|
-        buf << "," unless i.zero?
-        emit(v, buf)
+    # coerce: true — let a value that isn't natively supported convert itself.
+    # Prefer as_json (its result is re-emitted through the normal pipeline, so the
+    # escaping/format options still apply); fall back to to_json (spliced as-is, so
+    # ascii_only / script_safe do not reach inside it). Raise if it defines neither.
+    def emit_coerced(obj, buf, level)
+      if obj.respond_to?(:as_json)
+        emit(obj.as_json, buf, level)
+      elsif obj.respond_to?(:to_json)
+        buf << obj.to_json
+      else
+        raise SmarterJSON::GenerateError, "SmarterJSON.generate cannot serialize #{obj.class} (no as_json or to_json)"
+      end
+    end
+
+    def emit_array(arr, buf, level)
+      return buf << "[]" if arr.empty? # empty stays inline, even in pretty mode
+
+      if @pretty
+        pad = " " * (@indent * (level + 1))
+        buf << "[\n"
+        arr.each_with_index do |v, i|
+          buf << ",\n" unless i.zero?
+          buf << pad
+          emit(v, buf, level + 1)
+        end
+        buf << "\n" << (" " * (@indent * level)) << "]"
+      else
+        buf << "["
+        arr.each_with_index do |v, i|
+          buf << "," unless i.zero?
+          emit(v, buf, level)
+        end
+        buf << "]"
       end
-      buf << "]"
     end
 
-    def emit_hash(hash, buf)
-      buf << "{"
-      first = true
-      hash.each do |k, v|
-        buf << "," unless first
-        first = false
-        emit_string(k.is_a?(String) ? k : k.to_s, buf) # Symbol/other keys -> string
-        buf << ":"
-        emit(v, buf)
+    def emit_hash(hash, buf, level)
+      return buf << "{}" if hash.empty? # empty stays inline, even in pretty mode
+
+      pairs = @sort_keys ? hash.sort_by { |k, _| k.is_a?(String) ? k : k.to_s } : hash
+
+      if @pretty
+        pad = " " * (@indent * (level + 1))
+        buf << "{\n"
+        first = true
+        pairs.each do |k, v|
+          buf << ",\n" unless first
+          first = false
+          buf << pad
+          emit_string(k.is_a?(String) ? k : k.to_s, buf) # Symbol/other keys -> string
+          buf << ": "
+          emit(v, buf, level + 1)
+        end
+        buf << "\n" << (" " * (@indent * level)) << "}"
+      else
+        buf << "{"
+        first = true
+        pairs.each do |k, v|
+          buf << "," unless first
+          first = false
+          emit_string(k.is_a?(String) ? k : k.to_s, buf) # Symbol/other keys -> string
+          buf << ":"
+          emit(v, buf, level)
+        end
+        buf << "}"
       end
-      buf << "}"
     end
 
     def emit_string(str, buf)
-      buf << '"'
-      buf << str.gsub(ESCAPE_RE) { |c| ESCAPE[c] || format("\\u%04x", c.ord) }
-      buf << '"'
+      buf << '"' << str.gsub(@escape_re) { |m| escape_match(m) } << '"'
+    end
+
+    # Per-instance escape regex from the active options. Always: ", backslash, C0
+    # controls. script_safe adds the slash in </ and the JS line separators
+    # U+2028/U+2029. ascii_only adds every non-ASCII char.
+    def build_escape_re
+      res = [ESCAPE_RE]
+      res.unshift(%r{</}) if @script_safe
+      res << Regexp.new("[#{[0x2028, 0x2029].pack('U*')}]") if @script_safe
+      res << /[^\x00-\x7f]/ if @ascii_only
+      Regexp.union(*res)
+    end
+
+    def escape_match(m)
+      return "<\\/" if m == "</" # <\/ — stops </ from closing a <script> tag
+
+      ESCAPE[m] || unicode_escape(m)
+    end
+
+    # \uXXXX for a BMP char; a UTF-16 surrogate pair for astral (> U+FFFF) chars.
+    def unicode_escape(char)
+      cp = char.ord
+      return format("\\u%04x", cp) if cp <= 0xffff
+
+      cp -= 0x10000
+      format("\\u%04x\\u%04x", 0xd800 + (cp >> 10), 0xdc00 + (cp & 0x3ff))
     end
 
     def emit_float(flt, buf)

data/lib/smarter_json/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SmarterJSON
-  VERSION = "0.5.1"
+  VERSION = "0.5.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smarter_json
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.2
 platform: ruby
 authors:
 - Tilo Sloboda