Skip to main content

traceless.json

A custom JSON codec, not a complete Lua CJSON implementation. Settings are shared by all scripts in the Lua state. Strings, booleans, numbers, tables, nil, and json.null are supported; unsupported userdata/functions and cycles fail.

parse​

traceless.json.parse(text)

Returns: decoded Lua value.

Requires a string containing one JSON value. Arrays become one-based Lua arrays and objects become tables; JSON null becomes json.null. Invalid JSON, trailing nonwhitespace, or excessive nesting raises a Lua error.

stringify​

traceless.json.stringify(value)

Returns: string.

Encodes the value to JSON; nil and json.null encode as null. An empty table encodes as []. Dense positive integer-key tables encode as arrays; other tables encode as objects. Numeric strings can be coerced to numbers because the encoder checks lua_isnumber before strings. Numbers are formatted through a native float, so precision can be lost. Unsupported values, cycles/depth errors, and rejected sparse arrays raise value cannot be encoded as JSON. Avoid nonfinite numbers; the compatibility flag does not gate their formatting.

decode_invalid_numbers​

traceless.json.decode_invalid_numbers([enabled])

Returns: boolean.

Gets or sets a compatibility flag using Lua truthiness; default false. The current parser does not consult it and does not add NaN/Infinity token support when enabled.

decode_max_depth​

traceless.json.decode_max_depth([depth])

Returns: integer.

Gets/sets maximum decode nesting. Integer setter is clamped to 1–128; default 64.

encode_invalid_numbers​

traceless.json.encode_invalid_numbers([enabled])

Returns: boolean.

Gets/sets a compatibility flag using Lua truthiness; default false. The current encoder does not consult it. Nonfinite-number formatting is not controlled by this option, so avoid such inputs when interoperating with JSON consumers.

encode_keep_buffer​

traceless.json.encode_keep_buffer([enabled])

Returns: boolean.

Gets/sets the shared keep-buffer compatibility setting, default true. The current stringify implementation still releases its temporary output buffer; this setting does not guarantee reuse.

encode_max_depth​

traceless.json.encode_max_depth([depth])

Returns: integer.

Gets/sets encode nesting limit. Integer setter is clamped to 1–128; default 64.

encode_number_precision​

traceless.json.encode_number_precision([precision])

Returns: integer.

Gets/sets the custom encoder's number formatting precision. Clamped to 1–9; default 9. Do not assume full double precision preservation.

encode_sparse_array​

traceless.json.encode_sparse_array([convert [, ratio [, safe]]])

Returns: convert boolean, ratio integer, safe integer.

Defaults false, 2, 10. Set convert by truthiness; ratio and safe are integers clamped to at least 1. Any nondense positive integer-key table fails unless convert is true and its maximum index is both greater than safe and greater than entry_count * ratio. Only that sufficiently sparse case converts to an object. Smaller gaps fail too; use json.null to make a dense array instead.

null​

traceless.json.null is the shared lightuserdata sentinel for JSON null. Use it to retain null entries in arrays; assigning Lua nil removes a table entry.

local traceless = require("traceless")
local text = traceless.json.stringify({status = "ready", extra = traceless.json.null})
local result = traceless.json.parse(text)