# `Formata.Codec.JSON5`
[🔗](https://github.com/gsmlg-dev/formata/blob/v0.3.5/lib/formata/codec/json5.ex#L1)

JSON5 codec ([JSON5 1.0.0](https://spec.json5.org/)).

JSON5 is a separate format, not a mode of `:json`: use
`Formata.decode(input, :json5)` and `Formata.encode(data, :json5)`.

## Decoding

The full JSON5 1.0.0 grammar is accepted:

  * `//` and `/* */` comments, and a trailing comma in arrays and objects
  * single- or double-quoted strings, with the ECMAScript 5.1 escapes
    (`\v`, `\0`, `\xHH`, `\uHHHH`, `\'`, any other character escaping
    itself) and line continuations (a backslash before LF, CR, CRLF, U+2028,
    or U+2029); U+2028 and U+2029 may appear unescaped in strings
  * unquoted object keys that are ECMAScript 5.1 `IdentifierName`s,
    including Unicode letters and `\uHHHH` escapes. Character classes come
    from the Unicode general-category tables of the runtime's PCRE library
    (a newer Unicode version than ES5.1 references)
  * the additional JSON5 whitespace (VT, FF, NBSP, BOM, U+2028, U+2029,
    and other `Zs` space separators)
  * numbers with a leading `+`, leading or trailing decimal point (`.5`,
    `5.`), hexadecimal integers (`0x1F`, `-0xff`), `Infinity`, `-Infinity`,
    `+Infinity`, and `NaN` (also `+NaN` / `-NaN`)

Decoded values use the portable domain (see `Formata.Codec`):

  * object keys are strings (never atoms); duplicate keys, compared after
    unescaping (`{a: 1, "\u0061": 2}`), are `:parse` / `:duplicate_key` errors
  * numbers without a fraction or exponent (decimal or hexadecimal) are
    integers, others are floats. `Infinity`, `-Infinity`, and `NaN` become
    `:infinity`, `:negative_infinity`, and `:nan`. The sign of `NaN` is not
    kept. `-0` is the integer `0`, while `-0.0` stays the float `-0.0`
  * a finite literal outside the float range (`1e400`) is a `:parse` /
    `:syntax` error; it never becomes `Infinity`. Integers are limited to
    1024 digits, like `:json`
  * a `\u` escape of an unpaired UTF-16 surrogate cannot be represented in
    a UTF-8 string and is a `:syntax` error

Errors carry the byte offset and the line/column derived from it (lines
are counted by LF). JSON5 decoding takes no options: comments and trailing
commas are always allowed, so `:comments` and `:trailing_commas` are
rejected as `:invalid_option`.

## Encoding

The output is deterministic and minimal: the JSON subset of JSON5, with
object keys sorted and quoted, plus `Infinity`, `-Infinity`, and `NaN` for
`:infinity`, `:negative_infinity`, and `:nan`. No comments, unquoted keys,
or trailing commas are produced. The domain is the JSON domain plus those
three values; everything else is rejected with `:encode` errors.

Options:

  * `:pretty` - indent with two spaces (default `false`)

## Conversions

`Formata.convert(input, :json5, :json)` works for data inside the JSON
domain. Non-finite numbers are rejected by the JSON encoder with
`:unrepresentable` errors at their path; replace them explicitly (for
example `transforms: [:special_floats_to_strings]`) when that loss is
acceptable. JSON Schema validation likewise rejects them as
`:non_json_value`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
