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
stardust_document_builder_create	Status. builder through output	Create an owned document builder.
add	Unavailable	builder.add(node) appends one node and returns its preorder ID.
stardust_document_builder_add_many	Status. none through output	builder.add_many(nodes) appends nodes in order in one native call.
stardust_document_builder_seal	Status. document through output	builder.seal() transfers the constructed document into an independent owned document.
stardust_document_builder_release	`void`	Release the builder handle.

stardust_document_builder_create

78 B

uint32_t stardust_document_builder_create(stardust_document_builder **output);

Parameters

Parameter	Type	Ownership	Default	Meaning
`output`	`stardust_document_builder **`	Owned output	Required	Receives a library-owned handle. Release it after use.

Errors

Status	When
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted
`STARDUST_INVALID_ARGUMENT`	a required input or output pointer is NULL, or an input owner is not ready

Notes

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

Examples

builder

692 B

stardust_document_builder *builder = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_document_builder_create(&builder);
stardust_node_input nodes[] = {
    {.parent = STARDUST_DOCUMENT_NO_NODE, .kind = STARDUST_OBJECT},
    {.parent = 0, .kind = STARDUST_NUMBER, .key = {(const uint8_t *)"x", 1},
     .number = STARDUST_NUMBER_INTEGER, .integer = 41},
};
if (status == STARDUST_OK)
    status = stardust_document_builder_add_many(builder, nodes, 2);
if (status == STARDUST_OK)
    status = stardust_document_builder_seal(builder, &result);
stardust_document_builder_release(builder);
if (status != STARDUST_OK) {
    stardust_document_release(result);
    return status;
}

Result / 16 B

{:value {:x 41}}

add

Call stardust_document_builder_add_many with one node.

Examples

Add a typed integer node

452 B

stardust_node_input input = {.parent=STARDUST_DOCUMENT_NO_NODE, .kind=STARDUST_NUMBER, .number=STARDUST_NUMBER_INTEGER, .integer=41};
stardust_document_builder *builder = NULL;
uint32_t status = stardust_document_builder_create(&builder);
if (status == STARDUST_OK) status = stardust_document_builder_add_many(builder, &input, 1);
stardust_document_builder_release(builder);
if (status != STARDUST_OK) return status;
stardust_node_input result = input;

Result / 137 B

{:value {:parent  nil
         :kind    "number"
         :boolean false
         :number  41
         :key     ""
         :text    ""}}

Also calls: stardust_document_builder_add_many, stardust_document_builder_error

stardust_document_builder_add_many

129 B

uint32_t stardust_document_builder_add_many(stardust_document_builder *builder, const stardust_node_input *nodes, int64_t count);

117 B

uint32_t stardust_document_builder_error(const stardust_document_builder *builder, stardust_diagnostic_view *output);

Requires exclusive use of the receiver handle.

Parameters

stardust_document_builder_add_many

Parameter	Type	Ownership	Default	Meaning
`builder`	`stardust_document_builder *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`nodes`	`const stardust_node_input *`	Borrowed array	NULL	Nodes in depth-first preorder to append together.
`count`	`int64_t`	Value	Required	Value passed to the call.

stardust_document_builder_error

Parameter	Type	Ownership	Default	Meaning
`builder`	`const stardust_document_builder *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	a node breaks the preorder rules or has an invalid kind or number
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted

Examples

builder/add_many

692 B

stardust_document_builder *builder = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_document_builder_create(&builder);
stardust_node_input nodes[] = {
    {.parent = STARDUST_DOCUMENT_NO_NODE, .kind = STARDUST_OBJECT},
    {.parent = 0, .kind = STARDUST_NUMBER, .key = {(const uint8_t *)"x", 1},
     .number = STARDUST_NUMBER_INTEGER, .integer = 41},
};
if (status == STARDUST_OK)
    status = stardust_document_builder_add_many(builder, nodes, 2);
if (status == STARDUST_OK)
    status = stardust_document_builder_seal(builder, &result);
stardust_document_builder_release(builder);
if (status != STARDUST_OK) {
    stardust_document_release(result);
    return status;
}

Result / 16 B

{:value {:x 41}}

builder/add_many

692 B

stardust_document_builder *builder = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_document_builder_create(&builder);
stardust_node_input nodes[] = {
    {.parent = STARDUST_DOCUMENT_NO_NODE, .kind = STARDUST_OBJECT},
    {.parent = 0, .kind = STARDUST_NUMBER, .key = {(const uint8_t *)"x", 1},
     .number = STARDUST_NUMBER_INTEGER, .integer = 41},
};
if (status == STARDUST_OK)
    status = stardust_document_builder_add_many(builder, nodes, 2);
if (status == STARDUST_OK)
    status = stardust_document_builder_seal(builder, &result);
stardust_document_builder_release(builder);
if (status != STARDUST_OK) {
    stardust_document_release(result);
    return status;
}

Result / 16 B

{:value {:x 41}}

Also calls: stardust_document_builder_error

stardust_document_builder_seal

104 B

uint32_t stardust_document_builder_seal(stardust_document_builder *builder, stardust_document **output);

117 B

uint32_t stardust_document_builder_error(const stardust_document_builder *builder, stardust_diagnostic_view *output);

Requires exclusive use of the receiver handle.

Parameters

stardust_document_builder_seal

Parameter	Type	Ownership	Default	Meaning
`builder`	`stardust_document_builder *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_document **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_document_builder_error

Parameter	Type	Ownership	Default	Meaning
`builder`	`const stardust_document_builder *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	the builder has no root or a container is still open
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted

Notes

The builder accepts no more nodes after sealing.

Examples

builder/seal

692 B

stardust_document_builder *builder = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_document_builder_create(&builder);
stardust_node_input nodes[] = {
    {.parent = STARDUST_DOCUMENT_NO_NODE, .kind = STARDUST_OBJECT},
    {.parent = 0, .kind = STARDUST_NUMBER, .key = {(const uint8_t *)"x", 1},
     .number = STARDUST_NUMBER_INTEGER, .integer = 41},
};
if (status == STARDUST_OK)
    status = stardust_document_builder_add_many(builder, nodes, 2);
if (status == STARDUST_OK)
    status = stardust_document_builder_seal(builder, &result);
stardust_document_builder_release(builder);
if (status != STARDUST_OK) {
    stardust_document_release(result);
    return status;
}

Result / 16 B

{:value {:x 41}}

Also calls: stardust_document_builder_error

stardust_document_builder_release

75 B

void stardust_document_builder_release(stardust_document_builder *builder);

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`builder`	`stardust_document_builder *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

Examples

builder/close

input_text holds this document:

edn

7 B

{:x 41}

363 B

stardust_document_builder *builder = NULL;
uint32_t status = stardust_document_builder_create(&builder);
stardust_document_builder_release(builder);
if (status != STARDUST_OK) return status;
stardust_document *result = NULL;
status = stardust_parse(input_text, STARDUST_EDN, &result);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

Result / 16 B

{:value {:x 41}}