document

Documentation

Index

• Variables
• func DeleteAllInContainer(container *cst.Node)
• func Get[T any](doc *Document, key string) (T, error)
• func GetFromContainer[T any](doc *Document, container *cst.Node, key string) (T, error)
• func GetRawFromContainer(doc *Document, container *cst.Node, key string) (any, error)
• func GetStringMapFromTable(table *cst.Node) map[string]string
• func IsMultilineStringInContainer(container *cst.Node, key string) bool
• func MarkAllConsumed(table *cst.Node, prefix string, consumed map[string]bool)
• func SubTableKey(table *cst.Node, prefix string) string
• func SubTableKeyInContainer(table *cst.Node, container *cst.Node, prefix string) string
• func UndecodedKeys(root *cst.Node, consumed map[string]bool) []string
• type Document
  • func Parse(input []byte) (*Document, error)
  • func ParseReader(r io.Reader) (*Document, error)
  • func (doc *Document) AppendArrayTableEntry(key string) *cst.Node
  • func (doc *Document) Bytes() []byte
  • func (doc *Document) Delete(key string) error
  • func (doc *Document) DeleteFromContainer(container *cst.Node, key string) error
  • func (doc *Document) EnsureSubTable(prefix, key string) *cst.Node
  • func (doc *Document) EnsureSubTableInContainer(container *cst.Node, prefix, key string) *cst.Node
  • func (doc *Document) EnsureTable(name string) *cst.Node
  • func (doc *Document) EnsureTableInContainer(container *cst.Node, key string) *cst.Node
  • func (doc *Document) FindArrayTableNodes(key string) []*cst.Node
  • func (doc *Document) FindNestedArrayTableNodes(parentKey string, parentIndex int, childKey string) []*cst.Node
  • func (doc *Document) FindSubTables(prefix string) []*cst.Node
  • func (doc *Document) FindSubTablesInContainer(container *cst.Node, prefix string) []*cst.Node
  • func (doc *Document) FindTable(name string) *cst.Node
  • func (doc *Document) FindTableInContainer(container *cst.Node, key string) *cst.Node
  • func (doc *Document) GetComment(key string) string
  • func (doc *Document) GetInlineComment(key string) string
  • func (doc *Document) Has(key string) bool
  • func (doc *Document) HasInContainer(container *cst.Node, key string) bool
  • func (doc *Document) IsMultilineString(key string) bool
  • func (doc *Document) RemoveArrayTableEntry(node *cst.Node) error
  • func (doc *Document) Root() *cst.Node
  • func (doc *Document) Set(key string, value any) error
  • func (doc *Document) SetComment(key, comment string)
  • func (doc *Document) SetInContainer(container *cst.Node, key string, value any) error
  • func (doc *Document) SetInlineComment(key, comment string)
  • func (doc *Document) SetMultiline(key string, value string) error
  • func (doc *Document) SetMultilineInContainer(container *cst.Node, key string, value string) error

Variables

var ErrNotFound = fmt.Errorf("not found")

Functions

func DeleteAllInContainer

func DeleteAllInContainer(container *cst.Node)

DeleteAllInContainer removes all key-value children from a container node.

func Get

func Get[T any](doc *Document, key string) (T, error)

Get retrieves a value by dotted key path and converts it to the requested Go type.

func GetFromContainer

func GetFromContainer[T any](doc *Document, container *cst.Node, key string) (T, error)

GetFromContainer reads a value from a specific table or array-table node.

func GetRawFromContainer

func GetRawFromContainer(doc *Document, container *cst.Node, key string) (any, error)

GetRawFromContainer reads a value from a container and returns it as its natural Go type (string, int64, float64, bool, or []any) without requiring a type parameter.

func GetStringMapFromTable

func GetStringMapFromTable(table *cst.Node) map[string]string

GetStringMapFromTable reads all key-value pairs from a [table] node as a map[string]string. Returns nil if the table has no key-value children.

func IsMultilineStringInContainer

func IsMultilineStringInContainer(container *cst.Node, key string) bool

IsMultilineStringInContainer is like IsMultilineString but searches within a specific container node.

func MarkAllConsumed

func MarkAllConsumed(table *cst.Node, prefix string, consumed map[string]bool)

MarkAllConsumed marks all key-value children in a table as consumed, using the given prefix (e.g. "env") to build qualified keys like "env.FOO".

func SubTableKey

func SubTableKey(table *cst.Node, prefix string) string

SubTableKey returns the sub-key portion of a [prefix.key] table header. For a table with header "actions.build", SubTableKey("actions") returns "build".

func SubTableKeyInContainer

func SubTableKeyInContainer(table *cst.Node, container *cst.Node, prefix string) string

SubTableKeyInContainer returns the sub-key portion of a table header scoped to a container. For a table with header "outer.actions.build" inside container "outer", SubTableKeyInContainer("actions") returns "build".

func UndecodedKeys

func UndecodedKeys(root *cst.Node, consumed map[string]bool) []string

UndecodedKeys walks the CST and returns all key paths not present in the consumed set. Table headers are prefixed to their children (e.g. "hooks.create"). Keys under consumed tables are skipped entirely.

Types

type Document

type Document struct {
	// contains filtered or unexported fields
}

func Parse

func Parse(input []byte) (*Document, error)

func ParseReader

func ParseReader(r io.Reader) (*Document, error)

ParseReader parses TOML from an io.Reader into a Document.

func (*Document) AppendArrayTableEntry

func (doc *Document) AppendArrayTableEntry(key string) *cst.Node

AppendArrayTableEntry adds a new [[key]] section after the last existing one, or at the end of the document. Returns the new node.

func (*Document) Bytes

func (doc *Document) Bytes() []byte

func (*Document) Delete

func (doc *Document) Delete(key string) error

Delete removes a key-value pair from the document.

func (*Document) DeleteFromContainer

func (doc *Document) DeleteFromContainer(container *cst.Node, key string) error

DeleteFromContainer removes a key-value pair from a container node.

func (*Document) EnsureSubTable

func (doc *Document) EnsureSubTable(prefix, key string) *cst.Node

EnsureSubTable finds or creates a [prefix.key] table section.

func (*Document) EnsureSubTableInContainer

func (doc *Document) EnsureSubTableInContainer(container *cst.Node, prefix, key string) *cst.Node

EnsureSubTableInContainer finds or creates a [containerKey.prefix.key] table section, scoped to the container's qualified header.

func (*Document) EnsureTable

func (doc *Document) EnsureTable(name string) *cst.Node

EnsureTable finds or creates a [name] table section in the document. Returns the table node.

func (*Document) EnsureTableInContainer

func (doc *Document) EnsureTableInContainer(container *cst.Node, key string) *cst.Node

EnsureTableInContainer finds or creates a table for the given key within a container. It first checks direct children, then the document root for qualified headers (like FindTableInContainer), creating the table if absent.

func (*Document) FindArrayTableNodes

func (doc *Document) FindArrayTableNodes(key string) []*cst.Node

FindArrayTableNodes returns all [[key]] CST nodes in document order. Returns nil if none exist.

func (*Document) FindNestedArrayTableNodes

func (doc *Document) FindNestedArrayTableNodes(parentKey string, parentIndex int, childKey string) []*cst.Node

FindNestedArrayTableNodes returns [[parentKey.childKey]] entries that belong to the parentIndex-th [[parentKey]] entry. In TOML, nested array-of-tables entries belong to the most recently defined parent entry. This method finds all [[parentKey.childKey]] nodes between the parentIndex-th and (parentIndex+1)-th [[parentKey]] nodes in document order.

func (*Document) FindSubTables

func (doc *Document) FindSubTables(prefix string) []*cst.Node

FindSubTables returns all [prefix.key] table nodes for a given prefix, along with the sub-key (the part after the prefix dot). For example, FindSubTables("actions") returns tables like [actions.build].

func (*Document) FindSubTablesInContainer

func (doc *Document) FindSubTablesInContainer(container *cst.Node, prefix string) []*cst.Node

FindSubTablesInContainer returns all [containerKey.prefix.key] table nodes for a given prefix, scoped to the container's qualified header.

func (*Document) FindTable

func (doc *Document) FindTable(name string) *cst.Node

FindTable returns the [name] table node from the document root, or nil.

func (*Document) FindTableInContainer

func (doc *Document) FindTableInContainer(container *cst.Node, key string) *cst.Node

FindTableInContainer finds a [container.key] table that belongs to the given container node. It first checks direct children, then searches the document root for qualified table headers.

func (*Document) GetComment

func (doc *Document) GetComment(key string) string

GetComment returns the comment line(s) immediately above the given key. For dotted keys like "server.port", it looks inside the [server] table. Returns empty string if no comment exists above the key.

func (*Document) GetInlineComment

func (doc *Document) GetInlineComment(key string) string

GetInlineComment returns the inline comment on the same line as the given key. Returns empty string if no inline comment exists.

func (*Document) Has

func (doc *Document) Has(key string) bool

Has returns true if the key exists in the document.

func (*Document) HasInContainer

func (doc *Document) HasInContainer(container *cst.Node, key string) bool

HasInContainer returns true if the key exists within the given container node.

func (*Document) IsMultilineString

func (doc *Document) IsMultilineString(key string) bool

IsMultilineString reports whether the value node for the given key uses multiline string syntax (""" or ”').

func (*Document) RemoveArrayTableEntry

func (doc *Document) RemoveArrayTableEntry(node *cst.Node) error

RemoveArrayTableEntry removes a [[key]] section and its body from the document.

func (*Document) Root

func (doc *Document) Root() *cst.Node

func (*Document) Set

func (doc *Document) Set(key string, value any) error

Set updates or creates a key-value pair in the document.

func (*Document) SetComment

func (doc *Document) SetComment(key, comment string)

SetComment sets or replaces the comment line(s) immediately above the given key. The comment should include the "# " prefix. Multi-line comments should be newline-separated (e.g. "# line one\n# line two").

func (*Document) SetInContainer

func (doc *Document) SetInContainer(container *cst.Node, key string, value any) error

SetInContainer sets a key-value within a specific table or array-table node.

func (*Document) SetInlineComment

func (doc *Document) SetInlineComment(key, comment string)

SetInlineComment sets or replaces the inline comment on the given key's line. The comment should include the "# " prefix.

func (*Document) SetMultiline

func (doc *Document) SetMultiline(key string, value string) error

SetMultiline sets a string value using multiline basic string syntax (""").

func (*Document) SetMultilineInContainer

func (doc *Document) SetMultilineInContainer(container *cst.Node, key string, value string) error

SetMultilineInContainer sets a string value using multiline basic string syntax (""").