lib/json.x

JSON text to and from ordinary x2c values.

Primary API

Json

Json.bool

Var Json.bool(int value)

Returns the JSON boolean for the truth of value.

Source: lib/json.x:69

Json.boolean

int Json.boolean(Var value)

Returns 1 for JSON true and 0 for JSON false.

Raises: <bad-types> when value is not a JSON boolean.

Source: lib/json.x:77

Json.is_bool

int Json.is_bool(Var value)

Reports whether value is a JSON boolean.

Source: lib/json.x:72

Json.parse

Var Json.parse(String source)

Returns the x2c value of the JSON text source. Objects become Maps, arrays Arrays, and strings Strings. A number without a fraction or exponent is an int Var when it fits, then a long, then an unsigned long; any other number is a double. JSON null is the all-zero Var, and true and false are JsonBools. A repeated object name keeps its last value.

Raises: <bad-arg> with why, offset, line, and column details when source is not one JSON value surrounded only by whitespace, nests arrays and objects more than 512 deep, or contains a number too large for a double, an unpaired surrogate escape, or \u0000.

Source: lib/json.x:397

Json.read_file

Var Json.read_file(Path path)

Returns the x2c value of the JSON file at path, as Json.parse does.

Raises: the causes of Path.read_text, or <bad-arg> as Json.parse does, with a path detail added.

Source: lib/json.x:403

Json.write_file

void Json.write_file(Var value, Path path)

Replaces the file at path with value as compact JSON text.

Raises: the causes of Var.json and Path.write_text.

Source: lib/json.x:570

JsonBool

JsonBool.repr

String JsonBool.repr(JsonBool value)

Returns true or false.

Source: lib/json.x:63

JsonBool.str

String JsonBool.str(JsonBool value)

Returns true or false.

Source: lib/json.x:60

JsonBool.truth

int JsonBool.truth(JsonBool value)

Returns nonzero for true.

Source: lib/json.x:66

JsonBool.var

Var JsonBool.var(JsonBool value)

Boxes a JSON boolean.

Source: lib/json.x:54

Var

Var.json

String Var.json(Var value)

Returns value as compact JSON text. Map names are written in byte order and must be Strings or Symbols with distinct spellings; a Symbol value is written as a string. A List is written as an array. A double is written with the fewest digits that read back to the same value. Each maximal ill-formed UTF-8 subsequence in a string is written as U+FFFD, as Python and JavaScript decoders replace it.

Raises: <bad-types> for a value or name JSON cannot hold, <bad-arg> for a String and a Symbol name with the same spelling, <conv-range> for NaN or an infinity, or <size-limit> for nesting deeper than 512 levels.

Source: lib/json.x:560

Var.jsonbool

JsonBool Var.jsonbool(Var value)

Unboxes a JSON boolean from a Var produced by JsonBool.var.

Source: lib/json.x:57

Var.pretty_json

String Var.pretty_json(Var value)

Returns value as JSON text indented two spaces per level.

Raises: the causes of Var.json.

Source: lib/json.x:565

Public types

Json

typedef enum Json { JSON_NAMESPACE } Json

The receiverless owner of Json.parse and the other JSON operations.

Source: lib/json.x:23

JsonBool

typedef struct JsonBool *JsonBool

A JSON true or false, kept distinct from the numbers 1 and 0. The two values are process-lifetime singletons made by Json.bool.

Source: lib/json.x:30

Design notes

A JSON object becomes a Map with String keys, an array an Array, a string a String, a number an integer or double Var, null the all-zero Var, and true or false a JsonBool. The names match the converting surface of packages/yyjson, which a program can use instead when it needs object order, duplicate names, or numeric intent. A Map has none of those: a repeated name keeps its last value, and output lists names in byte order so the same value always writes the same text.

Input follows the RFC 8259 grammar. Rejected text raises <bad-arg> with the byte offset, one-based line and byte column, and a why.

Tests and examples

make verify (unittest/test-json.x).