Documents

The example parses the people document in your selected format. It then reads Ada's age through the document nodes. Typed reads give you these values without serializing the document.

Numbers

A document number is an i64 integer or a finite f64 value. The number type defines both.

An integer read requires an integer node. A floating-point node can cause the read to fail.
Choose the typed read that matches the node that you read.

Operations

Operation	Returns	Summary
parse	document	parse(text, format) returns an owned document.
Document.root	node	document.root() returns the root node ID.
Document.count	count	document.count() returns the number of nodes.
Document.read	node_view	document.read(id) returns a node view: kind, boolean, parent, position, first_child, next_sibling, key and text.
Document.read_many	node_views	document.read_many(start, capacity) reads consecutive node views.
Document.member	node	document.member(id, key) returns the first matching object member ID.
Document.children	node_views	document.children(id) iterates the node views of a node's children in order.
Document.members	node_views	document.members(id) iterates the members of an object node in order, each with its key.
Document.i64	integer	Read an exact signed integer.
Document.f64	real	Read a finite floating-point number.
Document.close	none	Release the document handle.

parse

python

84 B

def parse(text: str | bytes, format: str, *, library: str | None = None) -> Document

Parameters

Parameter	Type	Ownership	Default	Meaning
`text`	`str \| bytes`	Value	Required	Encoded input bytes in the selected format. TRON is binary.
`format`	`str`	Value	Required	The codec to use for this operation.
`library`	`str \| None`	Value	None	Loaded native library used by this call.

Errors

Status	When
`"invalid_json"`	JSON text is malformed
`"invalid_argument"`	the text is malformed, the format is unknown or a number is outside `i64` or finite `f64`
`"out_of_memory"`	native memory is exhausted

Examples

Parse the shared DUST expression fixture

expression_text holds these bytes:

text

278 B

// One expression built once and evaluated against several inputs. The
// evaluate examples load this file, build `expression`, evaluate it with each
// of `inputs` in order and compare each result with `expected`.
expression [+ ?x 1]
inputs     [{x 1} {x 41}]
expected   [2 42]

python

56 B

result = (await stardust.parse(expression_text, "dust"))

Result / 381 B

{
  "$comment": "One expression built once and evaluated against several inputs. The\nevaluate examples load this file, build `expression`, evaluate it with each\nof `inputs` in order and compare each result with `expected`.",
  "expression": [
    "+",
    "?x",
    1
  ],
  "inputs": [
    {
      "x": 1
    },
    {
      "x": 41
    }
  ],
  "expected": [
    2,
    42
  ]
}

Report a malformed byte at offset zero

malformed_text holds these bytes:

text

1 B

python

139 B

try:
    async with (await stardust.parse(malformed_text, "dust")):
        pass
except stardust.StardustError as error:
    result = error

Result / 169 B

{
  "code": "invalid_dust",
  "message": "Invalid_Syntax at offset 0",
  "path": null,
  "field": null,
  "entity": null,
  "offset": 0,
  "status": "invalid_argument"
}

Report malformed DUST

malformed_text holds these bytes:

text

1 B

python

139 B

try:
    async with (await stardust.parse(malformed_text, "dust")):
        pass
except stardust.StardustError as error:
    result = error

Result / 169 B

{
  "code": "invalid_dust",
  "message": "Unexpected_End at offset 2",
  "path": null,
  "field": null,
  "entity": null,
  "offset": 2,
  "status": "invalid_argument"
}

C exports: stardust_parse, stardust_document_error

Document.root

python

21 B

def root(self) -> int

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Document`	Borrowed for the call	Required	The document owner for this operation. Keep it alive during the call.

Errors

Status	When
`"closed"`	the document is closed

Examples

document/root

input_text holds this document:

json

14 B

{
  "x": 41
}

python

97 B

async with (await stardust.parse(input_text, "json")) as input:
    result = (await input.root())

Result / 1 B

C exports: stardust_document_root

Document.count

python

22 B

def count(self) -> int

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Document`	Borrowed for the call	Required	The document owner for this operation. Keep it alive during the call.

Errors

Status	When
`"closed"`	the document is closed

Examples

document/count

input_text holds this document:

json

14 B

{
  "x": 41
}

python

98 B

async with (await stardust.parse(input_text, "json")) as input:
    result = (await input.count())

Result / 1 B

C exports: stardust_document_count

Document.read

python

35 B

def read(self, id: int) -> NodeView

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Document`	Borrowed for the call	Required	The document owner for this operation. Keep it alive during the call.
`id`	`int`	Value	Required	A node ID within the receiver document.

Errors

Status	When
`"invalid_argument"`	id is not a node of the document
`"closed"`	the document is closed

Notes

Text contains string values. Read numbers with i64 or f64.

Examples

document/read

input_text holds this document:

json

14 B

{
  "x": 41
}

python

117 B

async with (await stardust.parse(input_text, "json")) as input:
    result = (await input.read((await input.root())))

Result / 148 B

{
  "kind": "object",
  "boolean": false,
  "parent": null,
  "position": 0,
  "first_child": 1,
  "next_sibling": null,
  "key": "",
  "text": ""
}

C exports: stardust_document_read_many

Document.read_many

python

64 B

def read_many(self, start: int, capacity: int) -> list[NodeView]

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Document`	Borrowed for the call	Required	The document owner for this operation. Keep it alive during the call.
`start`	`int`	Value	Required	The first node ID of the consecutive read.
`capacity`	`int`	Value	Required	The maximum number of node views to read. For output slices, the call uses the caller's slice length.

Errors

Status	When
`"invalid_argument"`	start is past the last node or capacity is negative
`"closed"`	the document is closed

Examples

document/read_many

input_text holds this document:

json

14 B

{
  "x": 41
}

python

142 B

async with (await stardust.parse(input_text, "json")) as input:
    views = (await input.read_many((await input.root()), 1))
result = views[0]

Result / 148 B

{
  "kind": "object",
  "boolean": false,
  "parent": null,
  "position": 0,
  "first_child": 1,
  "next_sibling": null,
  "key": "",
  "text": ""
}

C exports: stardust_document_read_many

Document.member

python

42 B

def member(self, id: int, key: str) -> int

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Document`	Borrowed for the call	Required	The document owner for this operation. Keep it alive during the call.
`id`	`int`	Value	Required	A node ID within the receiver document.
`key`	`str`	Value	Required	The object member name to find.

Errors

Status	When
`"not_found"`	the object has no member with the key
`"invalid_argument"`	id is not an object node of the document
`"closed"`	the document is closed

Examples

document/member

input_text holds this document:

json

14 B

{
  "x": 41
}

python

124 B

async with (await stardust.parse(input_text, "json")) as input:
    result = (await input.member((await input.root()), "x"))

Result / 1 B

C exports: stardust_document_member

Document.children

python

49 B

def children(self, id: int) -> Iterator[NodeView]

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Document`	Borrowed for the call	Required	The document owner for this operation. Keep it alive during the call.
`id`	`int`	Value	Required	A node ID within the receiver document.

Errors

Status	When
`"invalid_argument"`	id is not a node of the document
`"closed"`	the document is closed

Notes

Keep the document open during iteration. A scalar has no children. A read failure is reported once and ends iteration.

Examples

document/children

seed_text holds this document:

json

333 B

{
  "#_ada": {
    "name": "Ada",
    "role": "engineer",
    "age": 36
  },
  "#_bob": {
    "name": "Bob",
    "role": "engineer",
    "age": 41,
    "mentor": {
      "#link": "#_ada"
    }
  },
  "#_cy": {
    "name": "Cy",
    "role": "designer",
    "age": 29
  },
  "#_tx": {
    "author": "smoke",
    "reason": "seed"
  }
}

python

142 B

async with (await stardust.parse(seed_text, "json")) as source:
    result = sum([1 async for view in source.children((await source.root()))])

Result / 1 B

C exports: stardust_document_read_many

Document.members

python

60 B

def members(self, id: int) -> Iterator[tuple[str, NodeView]]

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Document`	Borrowed for the call	Required	The document owner for this operation. Keep it alive during the call.
`id`	`int`	Value	Required	A node ID within the receiver document.

Errors

Status	When
`"invalid_argument"`	id is not an object node of the document
`"closed"`	the document is closed

Notes

Duplicate keys appear in document order. Keep the document open during iteration. A read failure is reported once and ends iteration.

Examples

document/members

seed_text holds this document:

json

333 B

{
  "#_ada": {
    "name": "Ada",
    "role": "engineer",
    "age": 36
  },
  "#_bob": {
    "name": "Bob",
    "role": "engineer",
    "age": 41,
    "mentor": {
      "#link": "#_ada"
    }
  },
  "#_cy": {
    "name": "Cy",
    "role": "designer",
    "age": 29
  },
  "#_tx": {
    "author": "smoke",
    "reason": "seed"
  }
}

python

135 B

async with (await stardust.parse(seed_text, "json")) as source:
    result, view = (await anext(source.members((await source.root()))))

Result / 21 B

{
  "text": "#_ada"
}

C exports: stardust_document_read_many

Document.i64

python

29 B

def i64(self, id: int) -> int

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Document`	Borrowed for the call	Required	The document owner for this operation. Keep it alive during the call.
`id`	`int`	Value	Required	A node ID within the receiver document.

Errors

Status	When
`"invalid_argument"`	the node is not an integer number
`"closed"`	the document is closed

Examples

document/i64

input_text holds this document:

json

14 B

{
  "x": 41
}

python

153 B

async with (await stardust.parse(input_text, "json")) as input:
    x = (await input.member((await input.root()), "x"))
    result = (await input.i64(x))

Result / 2 B

C exports: stardust_document_i64

Status	When
`"invalid_argument"`	the node is not a number or its value overflows `f64`
`"closed"`	the document is closed

Parameter	Type	Ownership	Default	Meaning
`self`	`Document`	Consumed owner	Required	The document owner to release. Do not use it after this call.

node_view

This record contains the result of read and read_many. The key and text fields are owned strings and remain valid after the document closes.

Field	Type	Unit	Absent	Meaning
`kind`	`str`	None	—	—
`boolean`	`bool`	None	—	True only for true.
`parent`	`int \| None`	None	None	—
`position`	`int`	Count	—	Index within the parent container.
`first_child`	`int \| None`	None	None	—
`next_sibling`	`int \| None`	None	None	—
`key`	`str`	None	—	Member key of an object member, else empty.
`text`	`str`	None	—	Value of a string, else empty. It can contain NUL.

This record supplies a node for add and add_many. The number field holds a typed i64 or f64 value. Go uses I64/F64, Rust and Odin use Number, Clojure uses long or double, and Python uses int or float. This value sets the ABI number kind and the integer or real field.

Field	Type	Absent	Meaning
`parent`	`int \| None`	None	—
`kind`	`str`	—	—
`boolean`	`bool`	—	Value of a boolean node.
`number`	`int \| float \| None`	None	Value of a number node.
`key`	`str`	—	Member key when the parent is an object.
`text`	`str`	—	Value of a string node.