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
FromValue	document	from_value(value) copies host values into an owned document.
NewBuilder	builder	Create an owned document builder.
Builder.Add	node	builder.add(node) appends one node and returns its preorder ID.
Builder.AddMany	none	builder.add_many(nodes) appends nodes in order in one native call.
Builder.Seal	document	builder.seal() transfers the constructed document into an independent owned document.
Builder.Close	none	Release the builder handle.

FromValue

from_value(value) copies host values into an owned document.

Numbers use i64 or finite f64.
Host maps cannot preserve duplicate keys.
Use documents to preserve the full structure.

44B

func FromValue(value any) (*Document, error)

Concurrency: Other calls can overlap this call, except the release of a handle that this call uses.
Ownership: The caller owns the returned handle and releases it.

Parameters

Parameter	Type	Ownership	Default	Meaning
`value`	`any`	Value	Required	A host value to copy into native document nodes.

Errors

Status	When
`StatusInvalidArgument`	the value has a host type with no document form, a number outside `i64` or finite `f64`, or a cycle
`StatusOutOfMemory`	native memory is exhausted

Examples

Copy a host integer into a native document

95B

result, err := stardust.FromValue(int64(41))
if err != nil {
	return err
}
defer result.Close()

Result / 2B

C exports: stardust_document_builder_create, stardust_document_builder_add_many, stardust_document_builder_seal, stardust_document_builder_error, stardust_document_builder_release

NewBuilder

Create an owned document builder.

builder() creates an owned builder.

Add nodes in depth-first preorder, seal the document, and close the builder.
Native append failure makes the builder unusable.

35B

func NewBuilder() (*Builder, error)

Concurrency: Other calls can overlap this call, except the release of a handle that this call uses.
Ownership: The caller owns the returned handle and releases it.

Errors

Status	When
`StatusOutOfMemory`	native memory is exhausted

Examples

builder

464B

builder, err := stardust.NewBuilder()
if err != nil {
	return err
}
defer builder.Close()

object, err := builder.Add(stardust.NodeInput{
	Parent: stardust.NoNode,
	Kind:   stardust.Object,
})
if err != nil {
	return err
}
if _, err := builder.Add(stardust.NodeInput{
	Parent: object,
	Kind:   stardust.Number,
	Key:    "x",
	Number: stardust.I64(41),
}); err != nil {
	return err
}

result, err := builder.Seal()
if err != nil {
	return err
}
defer result.Close()

Result / 6B

{x 41}

C exports: stardust_document_builder_create

Builder.Add

builder.add(node) appends one node and returns its preorder ID.

A node specifies parent, kind, key, text, boolean and a typed i64 or f64 number.
The root has no parent.
Later parents must be open containers or their ancestors.

49B

func (b *Builder) Add(node NodeInput) (ID, error)

Concurrency: This call requires exclusive use of the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`node`	`NodeInput`	Value	Required	The next node's kind, parent and typed value.

Errors

Status	When
`StatusInvalidArgument`	the node breaks the preorder rules or has an invalid kind or number
`StatusClosed`	the builder is closed
`StatusOutOfMemory`	native memory is exhausted

Examples

builder/add

464B

builder, err := stardust.NewBuilder()
if err != nil {
	return err
}
defer builder.Close()

object, err := builder.Add(stardust.NodeInput{
	Parent: stardust.NoNode,
	Kind:   stardust.Object,
})
if err != nil {
	return err
}
if _, err := builder.Add(stardust.NodeInput{
	Parent: object,
	Kind:   stardust.Number,
	Key:    "x",
	Number: stardust.I64(41),
}); err != nil {
	return err
}

result, err := builder.Seal()
if err != nil {
	return err
}
defer result.Close()

Result / 6B

{x 41}

Add a typed integer node

262B

builder, err := stardust.NewBuilder()
if err != nil {
	return err
}
defer builder.Close()

result := stardust.NodeInput{
	Parent: stardust.NoNode,
	Kind:   stardust.Number,
	Number: stardust.I64(41),
}
if _, err := builder.Add(result); err != nil {
	return err
}

Result / 81B

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

C exports: stardust_document_builder_add_many, stardust_document_builder_error

Builder.AddMany

builder.add_many(nodes) appends nodes in order in one native call. Nodes have the same fields and preorder rules as add.

50B

func (b *Builder) AddMany(nodes []NodeInput) error

Concurrency: This call requires exclusive use of the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`nodes`	`[]NodeInput`	Value	Required	Nodes in depth-first preorder to append together.

Errors

Status	When
`StatusInvalidArgument`	a node breaks the preorder rules or has an invalid kind or number
`StatusClosed`	the builder is closed
`StatusOutOfMemory`	native memory is exhausted

Examples

builder/add_many

373B

builder, err := stardust.NewBuilder()
if err != nil {
	return err
}
defer builder.Close()

err = builder.AddMany([]stardust.NodeInput{
	{Parent: stardust.NoNode, Kind: stardust.Object},
	{Parent: 0, Kind: stardust.Number, Key: "x", Number: stardust.I64(41)},
})
if err != nil {
	return err
}

result, err := builder.Seal()
if err != nil {
	return err
}
defer result.Close()

Result / 6B

{x 41}

C exports: stardust_document_builder_add_many, stardust_document_builder_error

Builder.Seal

builder.seal() transfers the constructed document into an independent owned document. You cannot add more nodes after this call.

43B

func (b *Builder) Seal() (*Document, error)

Concurrency: This call requires exclusive use of the receiver handle.
Ownership: The caller owns the returned handle and releases it.

Errors

Status	When
`StatusInvalidArgument`	the builder has no root or a container is still open
`StatusClosed`	the builder is closed
`StatusOutOfMemory`	native memory is exhausted

Examples

builder/seal

464B

builder, err := stardust.NewBuilder()
if err != nil {
	return err
}
defer builder.Close()

object, err := builder.Add(stardust.NodeInput{
	Parent: stardust.NoNode,
	Kind:   stardust.Object,
})
if err != nil {
	return err
}
if _, err := builder.Add(stardust.NodeInput{
	Parent: object,
	Kind:   stardust.Number,
	Key:    "x",
	Number: stardust.I64(41),
}); err != nil {
	return err
}

result, err := builder.Seal()
if err != nil {
	return err
}
defer result.Close()

Result / 6B

{x 41}

C exports: stardust_document_builder_seal, stardust_document_builder_error

Builder.Close

Release the builder handle.

close(handle) releases the handle.

Do not use it after closure.
Result documents remain usable after the handle that produces them closes.

25B

func (b *Builder) Close()

Concurrency: This call is the last use of the receiver and ends its ownership.

Examples

builder/close

inputText holds this document:

dust

x 41

191B

builder, err := stardust.NewBuilder()
if err != nil {
	return err
}
builder.Close()

result, err := stardust.Parse(inputText, stardust.DUST)
if err != nil {
	return err
}
defer result.Close()

Result / 6B

{x 41}

C exports: stardust_document_builder_release