json

json.Parse

json.Parse(text) -> int

Parses a JSON text into an internal tree and returns the root handle.

The root handle (a positive integer). Invalid JSON or a full handle registry causes a runtime error; on malformed JSON the message gives the error location (line, column, byte).

i32 $h;
$h = json.Parse("{\"name\":\"Ada\"}");
printf("%s\n", json.GetString($h, "name"));
json.Free($h);

Ada

json.ParseLen

json.ParseLen(text, len) -> int

Like Parse, but it parses only the first len bytes of the text.

The root handle. A negative length, invalid JSON, or a full registry causes a runtime error.

i32 $h;
// parse only the first 8 bytes
$h = json.ParseLen("{\"n\":1} extra", 8);
printf("%d\n", json.GetInt($h, "n"));
json.Free($h);

1

json.Free

json.Free(handle) -> int

Frees the handle. For a root, the whole tree; for a sub-handle, only the script-level identifier (the tree is untouched).

Always 1.

i32 $h;
$h = json.Parse("{}");
printf("%d\n", json.Free($h));

1

json.GetType

json.GetType(handle, path) -> int

Gives the type of the node at the path as an integer type code.

The type code: 1=false, 2=true, 4=null, 8=number, 16=string, 32=array, 64=object.

i32 $h;
$h = json.Parse("{\"user\":{},\"tags\":[]}");
printf("%d\n", json.GetType($h, "user"));
printf("%d\n", json.GetType($h, "tags"));
json.Free($h);

64
32

json.GetString

json.GetString(handle, path) -> string

Reads the string value at the path.

The string value. If the node is not a string (or the path is missing), a runtime error.

i32 $h;
$h = json.Parse("{\"user\":{\"name\":\"Ada\"}}");
printf("%s\n", json.GetString($h, "user.name"));
json.Free($h);

Ada

json.GetInt

json.GetInt(handle, path) -> int

Reads the number at the path as an integer.

The integer value. If the node is not a number (or the path is missing), a runtime error.

i32 $h;
$h = json.Parse("{\"user\":{\"age\":36}}");
printf("%d\n", json.GetInt($h, "user.age"));
json.Free($h);

36

json.GetDouble

json.GetDouble(handle, path) -> double

Reads the number at the path as a floating-point (double) value.

The floating-point value. If the node is not a number (or the path is missing), a runtime error.

i32 $h;
$h = json.Parse("{\"ratio\":0.5}");
printf("%f\n", json.GetDouble($h, "ratio"));
json.Free($h);

0.500000

json.GetBool

json.GetBool(handle, path) -> int

Reads the boolean value at the path.

1 if true; 0 if false. If the node is not a boolean (or the path is missing), a runtime error.

i32 $h;
$h = json.Parse("{\"user\":{\"admin\":true}}");
printf("%d\n", json.GetBool($h, "user.admin"));
json.Free($h);

1

json.HasKey

json.HasKey(handle, path) -> int

Tells whether the key at the path exists. The only read function that does not fail on a missing key.

1 if the key exists; 0 if not (or if an intermediate segment is missing).

i32 $h;
$h = json.Parse("{\"user\":{\"name\":\"Ada\"}}");
printf("%d\n", json.HasKey($h, "user.name"));
printf("%d\n", json.HasKey($h, "user.xxx"));
json.Free($h);

1
0

json.GetObject

json.GetObject(handle, path) -> int

Returns a sub-handle to the nested object at the path.

A sub-handle to the object. If the node is not an object (or is missing), a runtime error.

i32 $h;
i32 $sub;
$h = json.Parse("{\"user\":{\"name\":\"Ada\"}}");
$sub = json.GetObject($h, "user");
printf("%s\n", json.GetString($sub, "name"));
json.Free($h);

Ada

json.GetArray

json.GetArray(handle, path) -> int

Returns a sub-handle to the array at the path.

A sub-handle to the array. If the node is not an array (or is missing), a runtime error.

i32 $h;
i32 $arr;
$h = json.Parse("{\"tags\":[\"x\",\"y\",\"z\"]}");
$arr = json.GetArray($h, "tags");
printf("%d\n", json.ArrayLength($arr));
json.Free($h);

3

json.ArrayLength

json.ArrayLength(arrayHandle) -> int

Gives the number of elements of an array handle.

The number of elements. If the handle is not an array, a runtime error.

i32 $h;
i32 $arr;
$h = json.Parse("{\"tags\":[\"x\",\"y\",\"z\"]}");
$arr = json.GetArray($h, "tags");
printf("%d\n", json.ArrayLength($arr));
json.Free($h);

3

json.ArrayGet

json.ArrayGet(arrayHandle, index) -> int

Returns a sub-handle to the array element at the given index.

A sub-handle to the element. If the handle is not an array or the index is out of range, a runtime error.

i32 $h;
i32 $arr;
i32 $elem;
$h = json.Parse("{\"tags\":[\"x\",\"y\",\"z\"]}");
$arr = json.GetArray($h, "tags");
$elem = json.ArrayGet($arr, 1);
// empty path = the element itself
printf("%s\n", json.GetString($elem, ""));
json.Free($h);

y

json.NewObject

json.NewObject() -> int

Creates a new, empty JSON object and returns the root handle.

This function takes no arguments.

The root handle of the new object.

i32 $o;
$o = json.NewObject();
json.SetString($o, "name", "Bob");
printf("%s\n", json.Serialize($o));
json.Free($o);

{"name":"Bob"}

json.SetString

json.SetString(obj, key, val) -> int

Sets a string-valued key on the object.

Always 1.

i32 $o;
$o = json.NewObject();
json.SetString($o, "name", "Bob");
printf("%s\n", json.Serialize($o));
json.Free($o);

{"name":"Bob"}

json.SetInt

json.SetInt(obj, key, val) -> int

Sets an integer-valued key on the object.

Always 1.

i32 $o;
$o = json.NewObject();
json.SetInt($o, "age", 41);
printf("%s\n", json.Serialize($o));
json.Free($o);

{"age":41}

json.SetDouble

json.SetDouble(obj, key, val) -> int

Sets a floating-point-valued key on the object.

Always 1.

i32 $o;
$o = json.NewObject();
json.SetDouble($o, "score", 9.5);
printf("%s\n", json.Serialize($o));
json.Free($o);

{"score":9.5}

json.SetBool

json.SetBool(obj, key, val) -> int

Sets a boolean-valued key on the object.

Always 1.

i32 $o;
$o = json.NewObject();
json.SetBool($o, "active", 1);
printf("%s\n", json.Serialize($o));
json.Free($o);

{"active":true}

json.SetNull

json.SetNull(obj, key) -> int

Sets a null-valued key on the object.

Always 1.

i32 $o;
$o = json.NewObject();
json.SetNull($o, "note");
printf("%s\n", json.Serialize($o));
json.Free($o);

{"note":null}

json.NewArray

json.NewArray() -> int

Creates a new, empty JSON array and returns the root handle.

This function takes no arguments.

The root handle of the new array.

i32 $a;
$a = json.NewArray();
json.AddInt($a, 7);
printf("%s\n", json.Serialize($a));
json.Free($a);

[7]

json.AddString

json.AddString(arr, val) -> int

Appends a string value to the end of the array.

Always 1.

i32 $a;
$a = json.NewArray();
json.AddString($a, "alpha");
printf("%s\n", json.Serialize($a));
json.Free($a);

["alpha"]

json.AddInt

json.AddInt(arr, val) -> int

Appends an integer value to the end of the array.

Always 1.

i32 $a;
$a = json.NewArray();
json.AddInt($a, 7);
printf("%s\n", json.Serialize($a));
json.Free($a);

[7]

json.AddDouble

json.AddDouble(arr, val) -> int

Appends a floating-point value to the end of the array.

Always 1.

i32 $a;
$a = json.NewArray();
json.AddDouble($a, 1.5);
printf("%s\n", json.Serialize($a));
json.Free($a);

[1.5]

json.AddBool

json.AddBool(arr, val) -> int

Appends a boolean value to the end of the array.

Always 1.

i32 $a;
$a = json.NewArray();
json.AddBool($a, 0);
printf("%s\n", json.Serialize($a));
json.Free($a);

[false]

json.Serialize

json.Serialize(handle) -> string

Turns the JSON tree under the handle into compact (single-line, no spaces) JSON text.

The compact JSON text.

i32 $o;
$o = json.NewObject();
json.SetString($o, "name", "Bob");
json.SetInt($o, "age", 41);
printf("%s\n", json.Serialize($o));
json.Free($o);

{"name":"Bob","age":41}

json.SerializePretty

json.SerializePretty(handle) -> string

Turns the JSON tree under the handle into human-readable, indented (formatted) JSON text.

The indented JSON text.

i32 $o;
$o = json.NewObject();
json.SetString($o, "name", "Bob");
json.SetInt($o, "age", 41);
printf("%s\n", json.SerializePretty($o));
json.Free($o);

{
"name": "Bob",
"age": 41
}

Practical notes

What the json plugin is good for

• Reading API responses and config files, and getting values out by path.

• Navigating nested structures (an object within an object, arrays) through sub-handles.

• Building output JSON from scratch (a request body, a response, a message), then turning it into text.

• Emitting data in compact (network) or indented (readable) form.

Reading safely

Since the Get* functions raise a runtime error both for a missing key and for a type mismatch, check optional or uncertain fields first with HasKey (existence) and GetType (type). You can read required, well-known fields directly — there an error precisely signals bad input.

Handle lifetime

The root handle (Parse/NewObject/NewArray) is freed by Free, together with the whole tree. The sub-handles (GetObject/GetArray/ArrayGet) are tied to the root's lifetime: after the root is freed they can no longer be used. In a long-running script, close every root with Free so the handle registry does not run out.

Common pitfalls

• An array in the path: the path can only navigate object members; an array needs GetArray + ArrayGet.

• Type mismatch: GetString on a number (or vice versa) is an error — use GetType first if the type is uncertain.

• Stale handle: after the root's Free, the sub-handles obtained from it are invalid.

• Missing libcjson: if cJSON is not installed on the system, the json.* calls fail (while loading still succeeds).

Error handling

A wrong argument count or type, a missing path, a type mismatch, an invalid or stale handle, an out-of-range array index, and bad JSON input are reported by the runtime as a runtime error, and the script stops. On malformed JSON the Parse and ParseLen message gives the exact error location (line, column, and byte offset), which makes it easier to find the broken part in the input. HasKey is the only read function that signals a missing key not as an error but with a 0 return value — so use it to check optional fields.

The sqlite database plugin

A thin wrapper over the SQLite C-API — complete function reference