use json
JSON parsing and querying.
Two ways in. parse reads a document once into a Value tree, which is what
you want when more than one field is read out of it. The get_* family scans
the text for a single key and allocates nothing, which is cheaper for exactly
that -- one lookup, one document.
Constants
| Name | Value | Description |
|---|---|---|
Array |
4 |
Type: Array value. |
Bool |
1 |
Type: Boolean value. |
ErrDepth |
14 |
Error: the document nests deeper than MaxDepth. |
ErrIndex |
12 |
Error: the array index is out of range. |
ErrKey |
13 |
Error: the object has no member with that key. |
ErrSyntax |
10 |
Error: the document is not well-formed JSON. |
ErrType |
11 |
Error: the value is not of the requested type. |
MaxDepth |
200 |
Deepest array/object nesting parse accepts. Parsing is recursive, so this is what stops a document like [[[[... from running the process out of stack. |
Null |
0 |
Type: Null value. |
Number |
2 |
Type: Number value. |
Object |
5 |
Type: Object value. |
String |
3 |
Type: String value. |
Functions
fn array_get_array
Get array element as nested array by index.
Signature: (json:str index:i64 -- value:str found:i64)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON array string |
index |
i64 |
Element index (0-based) |
| Output | Type | Description |
|---|---|---|
value |
str |
Nested array as JSON string |
found |
i64 |
1 if found, 0 otherwise |
Example:
"[[1,2],[3,4]]" 0 json::array_get_array // "[1,2]" 1
fn array_get_float
Get array element as float by index.
Signature: (json:str index:i64 -- value:f64 found:i64)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON array string |
index |
i64 |
Element index (0-based) |
| Output | Type | Description |
|---|---|---|
value |
f64 |
Float value |
found |
i64 |
1 if found, 0 otherwise |
Example:
"[1.5,2.5]" 0 json::array_get_float // 1.5 1
fn array_get_int
Get array element as integer by index.
Signature: (json:str index:i64 -- value:i64 found:i64)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON array string |
index |
i64 |
Element index (0-based) |
| Output | Type | Description |
|---|---|---|
value |
i64 |
Integer value |
found |
i64 |
1 if found, 0 otherwise |
Example:
"[10,20,30]" 2 json::array_get_int // 30 1
fn array_get_object
Get array element as object by index.
Signature: (json:str index:i64 -- value:str found:i64)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON array string |
index |
i64 |
Element index (0-based) |
| Output | Type | Description |
|---|---|---|
value |
str |
Object as JSON string |
found |
i64 |
1 if found, 0 otherwise |
Example:
"[{\"a\":1},{\"b\":2}]" 1 json::array_get_object // "{\"b\":2}" 1
fn array_get_string
Get array element as string by index.
Signature: (json:str index:i64 -- value:str found:i64)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON array string |
index |
i64 |
Element index (0-based) |
| Output | Type | Description |
|---|---|---|
value |
str |
String value |
found |
i64 |
1 if found, 0 otherwise |
Example:
"[\"a\",\"b\"]" 1 json::array_get_string // "b" 1
fn array_len
Get length of JSON array.
Signature: (json:str -- length:i64)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON array string |
| Output | Type | Description |
|---|---|---|
length |
i64 |
Number of elements |
Example:
"[1,2,3]" json::array_len print // 3
fn arr
Build a JSON array from comma-separated elements.
Signature: (content:str -- arr:str)
| Parameter | Type | Description |
|---|---|---|
content |
str |
Comma-separated elements |
| Output | Type | Description |
|---|---|---|
arr |
str |
JSON array |
Example:
"1,2,3" json::arr print // [1,2,3]
fn empty_arr
Build an empty JSON array.
Signature: ( -- arr:str)
| Output | Type | Description |
|---|---|---|
arr |
str |
Empty JSON array |
Example:
json::empty_arr print // []
fn empty_obj
Build an empty JSON object.
Signature: ( -- obj:str)
| Output | Type | Description |
|---|---|---|
obj |
str |
Empty JSON object |
Example:
json::empty_obj print // {}
fn encode
Encode a string for JSON (add quotes and escape special chars).
Signature: (s:str -- encoded:str)
| Parameter | Type | Description |
|---|---|---|
s |
str |
String to encode |
| Output | Type | Description |
|---|---|---|
encoded |
str |
JSON-encoded string with quotes |
Example:
"hello" json::encode print // "hello"
fn extract_str
Extract string value at position.
Signature: (json:str pos:i64 -- value:str)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON string |
pos |
i64 |
Position of opening quote |
| Output | Type | Description |
|---|---|---|
value |
str |
Extracted string |
fn find_str_end
Find end of JSON string (pos at opening quote).
Signature: (json:str pos:i64 -- end_pos:i64)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON string |
pos |
i64 |
Position of opening quote |
| Output | Type | Description |
|---|---|---|
end_pos |
i64 |
Position after closing quote |
fn get_array
Get nested array as string by key.
Signature: (json:str key:str -- value:str found:i64)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON object string |
key |
str |
Key to look up |
| Output | Type | Description |
|---|---|---|
value |
str |
Array as string |
found |
i64 |
1 if found, 0 otherwise |
Example:
"{\"arr\":[1,2]}" "arr" json::get_array // "[1,2]" 1
fn get_bool
Get boolean value by key from object.
Signature: (json:str key:str -- value:i64 found:i64)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON object string |
key |
str |
Key to look up |
| Output | Type | Description |
|---|---|---|
value |
i64 |
1 for true, 0 for false |
found |
i64 |
1 if found, 0 otherwise |
Example:
"{\"ok\":true}" "ok" json::get_bool // 1 1
fn get_float
Get float value by key from object.
Signature: (json:str key:str -- value:f64 found:i64)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON object string |
key |
str |
Key to look up |
| Output | Type | Description |
|---|---|---|
value |
f64 |
Float value |
found |
i64 |
1 if found, 0 otherwise |
Example:
"{\"pi\":3.14}" "pi" json::get_float // 3.14 1
fn get_int
Get integer value by key from object.
Signature: (json:str key:str -- value:i64 found:i64)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON object string |
key |
str |
Key to look up |
| Output | Type | Description |
|---|---|---|
value |
i64 |
Integer value |
found |
i64 |
1 if found, 0 otherwise |
Example:
"{\"age\":42}" "age" json::get_int // 42 1
fn get_object
Get nested object as string by key.
Signature: (json:str key:str -- value:str found:i64)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON object string |
key |
str |
Key to look up |
| Output | Type | Description |
|---|---|---|
value |
str |
Nested object as string |
found |
i64 |
1 if found, 0 otherwise |
Example:
"{\"obj\":{\"x\":1}}" "obj" json::get_object // "{\"x\":1}" 1
fn get_string
Get string value by key from object.
Signature: (json:str key:str -- value:str found:i64)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON object string |
key |
str |
Key to look up |
| Output | Type | Description |
|---|---|---|
value |
str |
String value |
found |
i64 |
1 if found, 0 otherwise |
Example:
"{\"name\":\"Bob\"}" "name" json::get_string // "Bob" 1
fn has_key
Check if key exists in object.
Signature: (json:str key:str -- exists:i64)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON object string |
key |
str |
Key to check |
| Output | Type | Description |
|---|---|---|
exists |
i64 |
1 if exists, 0 otherwise |
Example:
"{\"a\":1}" "a" json::has_key print // 1
fn is_null_at
Check if value at position is null.
Signature: (json:str pos:i64 -- is_null:i64)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON string |
pos |
i64 |
Position to check |
| Output | Type | Description |
|---|---|---|
is_null |
i64 |
1 if null, 0 otherwise |
Example:
"null" 0 json::is_null_at print // 1
fn join
Join multiple JSON fragments with commas.
Signature: (a:str b:str -- joined:str)
| Parameter | Type | Description |
|---|---|---|
a |
str |
First fragment |
b |
str |
Second fragment |
| Output | Type | Description |
|---|---|---|
joined |
str |
Comma-joined fragments |
Example:
"\"a\":1" "\"b\":2" json::join print // "a":1,"b":2
fn kv_bool
Build a key-value pair with boolean value.
Signature: (key:str value:i64 -- kv:str)
| Parameter | Type | Description |
|---|---|---|
key |
str |
Key name |
value |
i64 |
Boolean value (0=false, non-zero=true) |
| Output | Type | Description |
|---|---|---|
kv |
str |
JSON key-value pair |
Example:
"active" 1 json::kv_bool print // "active":true
fn kv_int
Build a key-value pair with integer value.
Signature: (key:str value:i64 -- kv:str)
| Parameter | Type | Description |
|---|---|---|
key |
str |
Key name |
value |
i64 |
Integer value |
| Output | Type | Description |
|---|---|---|
kv |
str |
JSON key-value pair |
Example:
"age" 42 json::kv_int print // "age":42
fn kv
Build a key-value pair with string value.
Signature: (key:str value:str -- kv:str)
| Parameter | Type | Description |
|---|---|---|
key |
str |
Key name |
value |
str |
String value |
| Output | Type | Description |
|---|---|---|
kv |
str |
JSON key-value pair |
Example:
"name" "Bob" json::kv print // "name":"Bob"
fn kv_raw
Build a key-value pair with raw JSON value (object, array, or literal).
Signature: (key:str value:str -- kv:str)
| Parameter | Type | Description |
|---|---|---|
key |
str |
Key name |
value |
str |
Raw JSON value (not quoted) |
| Output | Type | Description |
|---|---|---|
kv |
str |
JSON key-value pair |
Example:
"data" "{}" json::kv_raw print // "data":{}
fn obj
Build a JSON object from comma-separated key-value pairs.
Signature: (content:str -- obj:str)
| Parameter | Type | Description |
|---|---|---|
content |
str |
Comma-separated key-value pairs |
| Output | Type | Description |
|---|---|---|
obj |
str |
JSON object |
Example:
"\"a\":1,\"b\":2" json::obj print // {"a":1,"b":2}
fn type_at
Get JSON value type at position.
Signature: (json:str pos:i64 -- result:i64)
| Parameter | Type | Description |
|---|---|---|
json |
str |
JSON string |
pos |
i64 |
Position to check |
| Output | Type | Description |
|---|---|---|
result |
i64 |
Type constant (Null, Bool, Number, String, Array, Object) |
Example:
"{\"a\":1}" 5 json::type_at print // 2 (Number)
Value
A parsed JSON value. Children are a singly linked list rather than an array: head is the first element (or member), next chains siblings, and tail is kept only so that appending stays O(1). An object member carries its name in key.
Struct
| Field | Type | Description |
|---|---|---|
kind |
i64 |
One of Null, Bool, Number, String, Array, Object |
inum |
i64 |
Bool payload (0 or 1), or the Number payload when isint |
num |
f64 |
Number payload, always set for a Number |
isint |
i64 |
1 when the number was written without fraction or exponent |
text |
str |
String payload |
key |
str |
Member name, when this value is a member of an object |
head |
ptr |
First child, or null |
tail |
ptr |
Last child, or null |
next |
ptr |
Next sibling, or null |
count |
i64 |
Number of children |
Constructors
fn new_array
Create an empty array.
Signature: ( -- v:Value)
| Output | Type | Description |
|---|---|---|
v |
Value |
JSON array |
Example:
json::new_array // v
fn new_bool
Create a boolean value.
Signature: (b:i64 -- v:Value)
| Parameter | Type | Description |
|---|---|---|
b |
i64 |
0 for false, anything else for true |
| Output | Type | Description |
|---|---|---|
v |
Value |
JSON boolean |
Example:
1 json::new_bool // v
fn new_float
Create a number from a float.
Signature: (f:f64 -- v:Value)
| Parameter | Type | Description |
|---|---|---|
f |
f64 |
Floating point value |
| Output | Type | Description |
|---|---|---|
v |
Value |
JSON number |
Example:
1.5 json::new_float // v
fn new_int
Create a number from an integer.
Signature: (n:i64 -- v:Value)
| Parameter | Type | Description |
|---|---|---|
n |
i64 |
Integer value |
| Output | Type | Description |
|---|---|---|
v |
Value |
JSON number |
Example:
42 json::new_int // v
fn new_null
Create a null value.
Signature: ( -- v:Value)
| Output | Type | Description |
|---|---|---|
v |
Value |
JSON null |
Example:
json::new_null // v
fn new_object
Create an empty object.
Signature: ( -- v:Value)
| Output | Type | Description |
|---|---|---|
v |
Value |
JSON object |
Example:
json::new_object // v
fn new_string
Create a string value.
Signature: (s:str -- v:Value)
| Parameter | Type | Description |
|---|---|---|
s |
str |
String contents (unescaped) |
| Output | Type | Description |
|---|---|---|
v |
Value |
JSON string |
Example:
"hello" json::new_string // v
fn parse
Parse a JSON document into a Value tree. The whole document is read once, so a lookup on the result costs a walk of the tree rather than a rescan of the text -- which is what the get_* family above does on every call. Failure reports the byte offset.
Signature: (text:str -- v:Value)!
| Parameter | Type | Description |
|---|---|---|
text |
str |
JSON document |
| Output | Type | Description |
|---|---|---|
v |
Value |
Parsed value |
Example:
"{\x22a\x22:1}" json::parse! // doc
Methods
fn as_bool
Read a boolean value.
Signature: (v:Value) as_bool( -- b:i64)!
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Boolean value |
| Output | Type | Description |
|---|---|---|
b |
i64 |
0 or 1 |
Example:
v json::as_bool! // b
fn as_float
Read a number as a float.
Signature: (v:Value) as_float( -- f:f64)!
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Number value |
| Output | Type | Description |
|---|---|---|
f |
f64 |
Floating point value |
Example:
v json::as_float! // f
fn as_int
Read a number as an integer. A number written with a fraction or an exponent is truncated toward zero.
Signature: (v:Value) as_int( -- n:i64)!
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Number value |
| Output | Type | Description |
|---|---|---|
n |
i64 |
Integer value |
Example:
v json::as_int! // n
fn as_str
Read a string value.
Signature: (v:Value) as_str( -- s:str)!
| Parameter | Type | Description |
|---|---|---|
v |
Value |
String value |
| Output | Type | Description |
|---|---|---|
s |
str |
String contents, with escapes already decoded |
Example:
v json::as_str! // s
fn at
Read the element at an index. Works on an object too, where it reads the member at that position.
Signature: (v:Value) at(index:i64 -- child:Value)!
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Array or object |
index |
i64 |
Zero-based position |
| Output | Type | Description |
|---|---|---|
child |
Value |
Value at that position |
Example:
doc 0 json::at! // first
fn first
Read the first child of an array or object.
Signature: (v:Value) first( -- child:Value)!
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Array or object with at least one child |
| Output | Type | Description |
|---|---|---|
child |
Value |
First child |
Example:
doc json::first! // c
fn get
Read an object member by name.
Signature: (v:Value) get(key:str -- child:Value)!
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Object |
key |
str |
Member name |
| Output | Type | Description |
|---|---|---|
child |
Value |
Member value |
Example:
doc "name" json::get! // name_value
fn has_next
Report whether this value has a sibling after it.
Signature: (v:Value) has_next( -- b:i64)
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Child value |
| Output | Type | Description |
|---|---|---|
b |
i64 |
1 when a sibling follows |
Example:
c json::has_next // b
fn has
Report whether an object has a member with this name.
Signature: (v:Value) has(key:str -- exists:i64)
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Object |
key |
str |
Member name |
| Output | Type | Description |
|---|---|---|
exists |
i64 |
1 when the member is present |
Example:
doc "name" json::has // exists
fn is_array
Report whether the value is an array.
Signature: (v:Value) is_array( -- b:i64)
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Value to test |
| Output | Type | Description |
|---|---|---|
b |
i64 |
1 when the value is an array |
Example:
v json::is_array // b
fn is_bool
Report whether the value is a boolean.
Signature: (v:Value) is_bool( -- b:i64)
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Value to test |
| Output | Type | Description |
|---|---|---|
b |
i64 |
1 when the value is a boolean |
Example:
v json::is_bool // b
fn is_null
Report whether the value is JSON null.
Signature: (v:Value) is_null( -- b:i64)
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Value to test |
| Output | Type | Description |
|---|---|---|
b |
i64 |
1 when the value is null |
Example:
v json::is_null // b
fn is_number
Report whether the value is a number.
Signature: (v:Value) is_number( -- b:i64)
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Value to test |
| Output | Type | Description |
|---|---|---|
b |
i64 |
1 when the value is a number |
Example:
v json::is_number // b
fn is_object
Report whether the value is an object.
Signature: (v:Value) is_object( -- b:i64)
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Value to test |
| Output | Type | Description |
|---|---|---|
b |
i64 |
1 when the value is an object |
Example:
v json::is_object // b
fn is_string
Report whether the value is a string.
Signature: (v:Value) is_string( -- b:i64)
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Value to test |
| Output | Type | Description |
|---|---|---|
b |
i64 |
1 when the value is a string |
Example:
v json::is_string // b
fn len
Count the elements of an array or the members of an object. Any other value has no children and counts 0.
Signature: (v:Value) len( -- n:i64)
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Value to measure |
| Output | Type | Description |
|---|---|---|
n |
i64 |
Number of children |
Example:
v json::len // n
fn name
Read the name this value carries as a member of an object. Empty for a value that is not a member.
Signature: (v:Value) name( -- k:str)
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Member value |
| Output | Type | Description |
|---|---|---|
k |
str |
Member name |
Example:
v json::name // k
fn next
Read the sibling after this value. Walking first then next visits the children of an array or object in order, in linear time overall -- at walks from the head on every call.
Signature: (v:Value) next( -- sibling:Value)!
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Child value |
| Output | Type | Description |
|---|---|---|
sibling |
Value |
Next sibling |
Example:
c json::next! // c
fn pretty
Serialize a value to indented JSON text.
Signature: (v:Value) pretty(width:i64 -- s:str)
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Value to serialize |
width |
i64 |
Spaces per nesting level |
| Output | Type | Description |
|---|---|---|
s |
str |
JSON text, one element or member to a line |
Example:
doc 2 json::pretty print
fn push
Append a value to an array.
Signature: (v:Value) push(child:Value -- v2:Value)!
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Array |
child |
Value |
Value to append |
| Output | Type | Description |
|---|---|---|
v2 |
Value |
The same array |
Example:
arr 42 json::new_int json::push! // arr
fn put
Set an object member. Replaces the member of that name if there is one, keeping its position.
Signature: (v:Value) put(key:str child:Value -- v2:Value)!
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Object |
key |
str |
Member name |
child |
Value |
Member value |
| Output | Type | Description |
|---|---|---|
v2 |
Value |
The same object |
Example:
obj "n" 1 json::new_int json::put! // obj
fn stringify
Serialize a value to compact JSON text.
Signature: (v:Value) stringify( -- s:str)
| Parameter | Type | Description |
|---|---|---|
v |
Value |
Value to serialize |
| Output | Type | Description |
|---|---|---|
s |
str |
JSON text with no space between tokens |
Example:
doc json::stringify print