Building documents

These operations construct a document one node at a time. For most operations, parse a document in your selected format. Use these operations only when you cannot parse the document from text.

Create a builder.
Add the nodes in preorder.
Seal the builder to create an owned document.

Operations

Operation	Returns	Summary
builder	builder	Create an owned document builder.
add	node	builder.add(node) appends one node and returns its preorder ID.
add_many	none	builder.add_many(nodes) appends nodes in order in one native call.
seal	document	builder.seal() transfers the constructed document into an independent owned document.
close	none	Release the builder handle.

builder

odin

67 B

builder :: proc(allocator := context.allocator) -> (Builder, Error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Out_Of_Memory`	native memory is exhausted

Notes

Add nodes in depth-first preorder. An append failure makes the builder unusable.

Examples

builder

odin

329 B

builder := stardust.builder() or_return
defer stardust.close(&builder)

object := stardust.add(&builder, {parent = stardust.NO_NODE, kind = .Object}) or_return
stardust.add(&builder, {parent = object, kind = .Number, key = "x", number = i64(41)}) or_return
result := stardust.seal(builder) or_return
defer stardust.close(&result)

Result / 13 B

{
  "x": 41
}

C exports: stardust_document_builder_create

add

odin

96 B

add :: proc(builder: ^Builder, node: Node_Input, allocator := context.allocator) -> (u32, Error)

Requires exclusive use of the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`builder`	`^Builder`	Borrowed for the call	Required	The builder owner for this operation. Keep it alive during the call.
`node`	`Node_Input`	Value	Required	The next node's kind, parent and typed value.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Invalid_Argument`	the node breaks the preorder rules or has an invalid kind or number
`.Closed`	the builder is closed
`.Out_Of_Memory`	native memory is exhausted

Notes

The root has no parent. Each later parent must be an open container or one of its ancestors.

Examples

builder/add

odin

329 B

builder := stardust.builder() or_return
defer stardust.close(&builder)

object := stardust.add(&builder, {parent = stardust.NO_NODE, kind = .Object}) or_return
stardust.add(&builder, {parent = object, kind = .Number, key = "x", number = i64(41)}) or_return
result := stardust.seal(builder) or_return
defer stardust.close(&result)

Result / 13 B

{
  "x": 41
}

Add a typed integer node

odin

217 B

input := stardust.Node_Input{parent = stardust.NO_NODE, kind = .Number, number = i64(41)}
builder := stardust.builder() or_return
defer stardust.close(&builder)

stardust.add(&builder, input) or_return
result := input

Result / 103 B

{
  "parent": null,
  "kind": "number",
  "boolean": false,
  "number": 41,
  "key": "",
  "text": ""
}

C exports: stardust_document_builder_add_many, stardust_document_builder_error

add_many

odin

97 B

add_many :: proc(builder: ^Builder, nodes: []Node_Input, allocator := context.allocator) -> Error

Requires exclusive use of the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`builder`	`^Builder`	Borrowed for the call	Required	The builder owner for this operation. Keep it alive during the call.
`nodes`	`[]Node_Input`	Value	Required	Nodes in depth-first preorder to append together.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Invalid_Argument`	a node breaks the preorder rules or has an invalid kind or number
`.Closed`	the builder is closed
`.Out_Of_Memory`	native memory is exhausted

Examples

builder/add_many

odin

299 B

builder := stardust.builder() or_return
defer stardust.close(&builder)

stardust.add_many(&builder, {
    {parent = stardust.NO_NODE, kind = .Object},
    {parent = 0, kind = .Number, key = "x", number = i64(41)},
}) or_return
result := stardust.seal(builder) or_return
defer stardust.close(&result)

Result / 13 B

{
  "x": 41
}

C exports: stardust_document_builder_add_many, stardust_document_builder_error

seal

odin

83 B

seal :: proc(builder: Builder, allocator := context.allocator) -> (Document, Error)

Requires exclusive use of the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`builder`	`Builder`	Borrowed for the call	Required	The builder owner for this operation. Keep it alive during the call.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Invalid_Argument`	the builder has no root or a container is still open
`.Closed`	the builder is closed
`.Out_Of_Memory`	native memory is exhausted

Notes

The builder accepts no more nodes after sealing.

Examples

builder/seal

odin

329 B

builder := stardust.builder() or_return
defer stardust.close(&builder)

object := stardust.add(&builder, {parent = stardust.NO_NODE, kind = .Object}) or_return
stardust.add(&builder, {parent = object, kind = .Number, key = "x", number = i64(41)}) or_return
result := stardust.seal(builder) or_return
defer stardust.close(&result)

Result / 13 B

{
  "x": 41
}

C exports: stardust_document_builder_seal, stardust_document_builder_error

close

odin

32 B

close :: proc(builder: ^Builder)

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`builder`	`^Builder`	Consumed owner	Required	The builder owner to release. Do not use it after this call.

Examples

builder/close

input_text holds this document:

json

14 B

{
  "x": 41
}

odin

149 B

builder := stardust.builder() or_return
stardust.close(&builder)

result := stardust.parse(input_text, .JSON) or_return
defer stardust.close(&result)

Result / 13 B

{
  "x": 41
}

C exports: stardust_document_builder_release