Capy-Bearer Documentation

Description

Options default to relaxed: false. Omitted options and none use strict JSON parsing. Options must be none or an explicit map, not a list or scalar. Unknown fields are ignored. An invalid recognized option type returns a failure. Neither the input nor the options map changes.

With relaxed: true, the parser also accepts // line comments, /* */ block comments, and trailing commas in arrays and objects. Single-quoted strings accept \' and standard JSON escapes. Unquoted object keys must match the ASCII pattern [A-Za-z_$][A-Za-z0-9_$]*. Comment markers and punctuation inside strings remain string content. Strict mode rejects these extensions.

Relaxed mode still rejects array holes, missing values, incomplete comments or strings, unescaped controls, NaN, Infinity, and trailing junk. It does not change the number grammar, numeric types, duplicate-key behavior, or resource limits.

json_decode() preserves integer-form tokens exactly within the signed and unsigned 64-bit ranges. Nonnegative values through INT64_MAX use s64. Larger values through UINT64_MAX use u64. Negative values within the s64 range use s64. The token -0 keeps floating negative zero. Tokens with a decimal point or exponent use f64.

Quoted numeric text remains a string. Booleans and null keep their types. Empty objects remain maps, and empty arrays remain lists.

The parser requires a complete JSON document. Invalid syntax, invalid Unicode escapes, unpaired surrogate escapes, or a resource limit returns a failure. The error includes the byte offset. JSON null succeeds with value: none. The parser accepts standard JSON whitespace and uses the last value for duplicate keys. It does not validate raw UTF-8 bytes inside strings.

Integer-form tokens outside these 64-bit ranges fall back to finite binary64 values and can round. Decimal and exponent tokens also use binary64 precision. Very small magnitudes can underflow to zero. A number too large for binary64, such as 1e400, decodes to positive or negative infinity, as PHP json_decode does. JSON has no infinity, so json_encode of a value that contains one fails. This is not arbitrary precision. Keep raw JSON when exact bytes or number spelling are required. Check ok to distinguish invalid input from JSON null.

The limits match BRRB: 64 value levels and 262,144 value nodes, each including the root. Object keys do not count as nodes. The input text and decoded value must fit runtime memory.

Object keys remain map keys, including sequential numeric keys from "0". Maps retain insertion order. Empty maps and empty lists remain distinct.