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:156

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:164

Json.is_bool

int Json.is_bool(Var value)

Reports whether value is a JSON boolean.

Source: lib/json.x:159

Json.parse

meta native 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: <malformed> with reason, 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:203

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 <malformed> as Json.parse does, with a path detail added.

Source: lib/json.x:209

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:482

JsonBool

JsonBool.repr

String JsonBool.repr(JsonBool value)

Returns true or false.

Source: lib/json.x:150

JsonBool.str

String JsonBool.str(JsonBool value)

Returns true or false.

Source: lib/json.x:147

JsonBool.truth

int JsonBool.truth(JsonBool value)

Returns nonzero for true.

Source: lib/json.x:153

JsonBool.var

Var JsonBool.var(JsonBool value)

Boxes a JSON boolean.

Source: lib/json.x:141

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:472

Var.jsonbool

meta native JsonBool Var.jsonbool(Var value)

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

Source: lib/json.x:144

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:477

Public types

Json

typedef Symbol Json

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

Source: lib/json.x:20

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:25

Design notes

Json owns the crossing between JSON text and ordinary x2c values: an object is a Map with String keys, an array an Array, null the all-zero Var, and true or false a JsonBool. A Map keeps neither member order nor duplicate names, so a repeated name keeps its last value and output writes names in byte order; packages/yyjson serves a program that needs either.

Tests and examples

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