7.1. JSON manipulation library

The JSON module implements JSON parsing and serialization. It provides read_json for parsing JSON text into a JsonValue tree, write_json for serializing back to text, and JV helpers for constructing JSON values from daslang types.

See also Boost package for JSON for automatic struct-to-JSON conversion and the %json~ reader macro. See JSON for a hands-on tutorial.

All functions and symbols are in “json” module, use require to get access to it.

require daslib/json

Example:

require daslib/json

    [export]
    def main() {
        let data = "[1, 2, 3]"
        var error = ""
        var js <- read_json(data, error)
        print("json: {write_json(js)}\n")
        unsafe {
            delete js
        }
    }
    // output:
    // json: [1,2,3]

7.1.1. Type aliases

variant JsValue

Single JSON element.

Variants:

  • _object : table<string; JsonValue?> - JSON object

  • _array : array< JsonValue?> - JSON array

  • _string : string - JSON string

  • _number : double - JSON number

  • _longint : int64 - extension, not part of JSON standard (represents long integer numbers)

  • _bool : bool - JSON boolean

  • _null : void? - JSON null

variant Token

JSON input stream token.

Variants:

  • _string : string - string token

  • _number : double - number token

  • _longint : int64 - extension, not part of JSON standard (represents long integer numbers)

  • _bool : bool - boolean token

  • _null : void? - null token

  • _symbol : int - symbol token (one of []{}:,)

  • _error : string - error token

7.1.2. Structures

JsonValue

JSON value, wraps any JSON element.

Fields:

  • value : JsValue - value of the JSON element

TokenAt

JSON parsing token. Contains token and its position.

Fields:

  • value : Token - token value

  • line : int - token position in the input stream

  • row : int - token position in the input stream

7.1.3. Value conversion

7.1.3.1. JV

JV(v: bitfield ): JsonValue?

Creates JsonValue out of bitfield value.

Arguments:

  • v : bitfield<>

JV(v: bitfield16:uint16<> ): JsonValue?
JV(v: bitfield64:uint64<> ): JsonValue?
JV(v: bitfield8:uint8<> ): JsonValue?
JV(v: bool ): JsonValue?
JV(v: double ): JsonValue?
JV(v: float ): JsonValue?
JV(v: int ): JsonValue?
JV(v: string ): JsonValue?
JV(val: int16 ): JsonValue?
JV(val: int64 ): JsonValue?
JV(val: int8 ): JsonValue?
JV(val: uint ): JsonValue?
JV(val: uint16 ): JsonValue?
JV(val: uint64 ): JsonValue?
JV(val: uint8 ): JsonValue?
JV(v: array<JsonValue?> ): JsonValue?
JV(v: table<string, JsonValue?> ): JsonValue?
JVNull(): JsonValue?

Creates JsonValue representing null.

7.1.4. Read and write

7.1.4.1. read_json

read_json(text: array<uint8>; error: string& ): JsonValue?

reads JSON from the text array of uint8. if error is not empty, it contains the parsing error message.

Arguments:

  • text : array<uint8>

  • error : string&

read_json(text: string; error: string& ): JsonValue?

7.1.4.2. write_json

write_json(val: JsonValue?# ): string

Overload accepting temporary type

Arguments:
write_json(val: JsonValue? ): string

7.1.5. Memory management

delete_json(jsv: JsonValue? )

Free a JsonValue tree. JsonValue? is owned (this module is strict_smart_pointers), so delete already recurses — finalizing the _object table / _array deletes the child nodes in turn — and one top-level delete frees the whole tree. This wraps that in the required unsafe plus a null guard, and names the intent at call sites. Pass an owned tree you are done with (a parsed read_json input, a built result, a per-frame payload); assumes unique ownership — do not call on a shared/aliased tree. No-op on null or on the shared missing-key sentinel (json_null_sentinel), so freeing a tree that a careless caller navigated into is still safe.

Arguments:
json_null_sentinel(): JsonValue?

Shared, per-context null JsonValue returned by operator ?[] / ?. when a key/index is absent — so missing-key navigation allocates nothing (a fresh JVNull() per miss was a steady GC-pressure source). It preserves the “?[] is never null” contract callers rely on. INTERNAL: it is shared and must never be freed, mutated, or stored into a tree. delete_json and update guard against it; do not delete a ?[] result directly or insert it into an object/array.

update(obj: JsonValue?; key: string; jsv: JsonValue? )

Set object field key to jsv, first freeing (via delete_json) whatever JsonValue was stored at key. Use this instead of a bare insert when overwriting a field on a reused/long-lived object every frame — a bare insert drops the old value on the heap. No-op when obj is null or not an _object.

Arguments:

7.1.6. JSON properties

set_allow_duplicate_keys(value: bool ): bool

if value is true, then duplicate keys are allowed in objects. the later key overwrites the earlier one.

Arguments:

  • value : bool

set_no_empty_arrays(value: bool ): bool

if value is true, then empty arrays are not written at all

Arguments:

  • value : bool

set_no_trailing_zeros(value: bool ): bool

if value is true, then numbers are written without trailing zeros.

Arguments:

  • value : bool

7.1.7. Broken JSON

try_fixing_broken_json(bad: string ): string

fixes broken json. so far supported 1. “string” + “string” string concatenation 2. “text “nested text” text” nested quotes 3. extra , at the end of object or array 4. /uXXXXXX sequences in the middle of white space

Arguments:

  • bad : string