pkg:data/json

JSON parsing, construction, and serialization.

import "pkg:data/json"

Overview

Provides a complete JSON library for parsing, constructing, serializing, and querying JSON values. All values are heap-allocated 24-byte nodes with a type tag, payload, and extra field. Numbers are integer-only (i64) in this version.

Value layout (24 bytes):

Dependencies: vera:memory, vera:string

Construction

json_null

function json_null() -> ptr

Create a JSON null value.

Returns: pointer to a new null node.

json_bool

function json_bool(v: i32) -> ptr

Create a JSON boolean value.

Parameters:

• v (i32) — 1 for true, 0 for false

Returns: pointer to a new boolean node.

json_number

function json_number(v: i64) -> ptr

Create a JSON number value (integer-only).

Parameters:

• v (i64) — the integer value

Returns: pointer to a new number node.

json_string

function json_string(data: ptr, len: i64) -> ptr

Create a JSON string value. The string data is copied to the heap.

Parameters:

• data (ptr) — pointer to the string bytes
• len (i64) — length of the string in bytes

Returns: pointer to a new string node.

json_array_new

function json_array_new() -> ptr

Create an empty JSON array. The array starts with an initial capacity of 4 and grows automatically when elements are pushed.

Returns: pointer to a new array node.

json_array_push

function json_array_push(arr: ptr, val: ptr)

Append a value to a JSON array. The array buffer is automatically doubled in capacity if full.

Parameters:

• arr (ptr) — pointer to the array node
• val (ptr) — pointer to the value node to append

json_object_new

function json_object_new() -> ptr

Create an empty JSON object. The object starts with an initial capacity of 4 entries and grows automatically.

Returns: pointer to a new object node.

json_object_set

function json_object_set(obj: ptr, key: ptr, key_len: i64, val: ptr)

Set a key-value pair in a JSON object. If the key already exists, the old value is freed and replaced. The key is copied to the heap.

Parameters:

• obj (ptr) — pointer to the object node
• key (ptr) — pointer to the key string bytes
• key_len (i64) — length of the key string
• val (ptr) — pointer to the value node to associate with the key

Type Inspection

json_type

function json_type(value: ptr) -> i8

Get the type tag of a JSON value.

Parameters:

• value (ptr) — pointer to a JSON node

Returns: the type tag:

Value Access

json_get_bool

function json_get_bool(value: ptr) -> i32

Extract the boolean value from a JSON bool node.

Parameters:

• value (ptr) — pointer to a boolean JSON node

Returns: 1 for true, 0 for false, or -1 if the node is not a boolean.

json_get_number

function json_get_number(value: ptr) -> i64

Extract the integer value from a JSON number node.

Parameters:

• value (ptr) — pointer to a number JSON node

Returns: the integer value, or 0 if the node is not a number.

json_get_string

function json_get_string(value: ptr, out_len: ptr) -> ptr

Get a pointer to the string data inside a JSON string node.

Parameters:

• value (ptr) — pointer to a string JSON node
• out_len (ptr) — pointer to an i64 where the string length will be written

Returns: pointer to the string data, or null if the node is not a string. The length is written to out_len (0 if not a string).

json_array_length

function json_array_length(value: ptr) -> i64

Get the number of elements in a JSON array.

Parameters:

• value (ptr) — pointer to an array JSON node

Returns: the element count, or -1 if the node is not an array.

json_array_get

function json_array_get(value: ptr, index: i64) -> ptr

Get an element from a JSON array by index.

Parameters:

• value (ptr) — pointer to an array JSON node
• index (i64) — zero-based index of the element

Returns: pointer to the element node, or null if the node is not an array or the index is out of bounds.

json_object_get

function json_object_get(value: ptr, key: ptr, key_len: i64) -> ptr

Look up a value in a JSON object by key. Performs a linear scan comparing keys by byte equality.

Parameters:

• value (ptr) — pointer to an object JSON node
• key (ptr) — pointer to the key string to search for
• key_len (i64) — length of the key string

Returns: pointer to the value node, or null if the key was not found or the node is not an object.

Parsing and Serialization

json_parse

function json_parse(buf: ptr, len: i64) -> ptr

Parse a JSON document from a byte buffer. Supports all JSON types: strings (with escape sequences), numbers (integer portion), booleans, null, arrays, and objects.

Parameters:

• buf (ptr) — pointer to the JSON text
• len (i64) — length of the JSON text in bytes

Returns: pointer to the root JSON node, or null on parse error.

json_serialize

function json_serialize(value: ptr, buf: ptr, buf_size: i64) -> i64

Serialize a JSON value tree into a byte buffer. Produces compact JSON (no whitespace). Strings are escaped according to JSON rules (\", \\, \n, \r, \t).

Parameters:

• value (ptr) — pointer to the root JSON node
• buf (ptr) — caller-allocated output buffer
• buf_size (i64) — size of the output buffer in bytes

Returns: number of bytes written to buf, or 0 if the value is null.

Memory

json_free

function json_free(value: ptr)

Recursively free a JSON value and all memory it owns. For strings, frees the string data. For arrays, frees each element recursively, then the element buffer. For objects, frees each key and value recursively, then the entry buffer. Safe to call with a null pointer.

Parameters:

• value (ptr) — pointer to the JSON node to free (or null)