Documentation
¶
Overview ¶
Package unstable provides APIs that do not meet the backward compatibility guarantees yet.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewParserError ¶
NewParserError is a convenience function to create a ParserError
Warning: Highlight needs to be a subslice of Parser.data, so only slices returned by Parser.Raw are valid candidates.
Types ¶
type Iterator ¶
type Iterator struct {
// contains filtered or unexported fields
}
Iterator over a sequence of nodes.
Starts uninitialized, you need to call Next() first.
For example:
it := n.Children()
for it.Next() {
n := it.Node()
// do something with n
}
func (*Iterator) IsLast ¶
IsLast returns true if the current node of the iterator is the last one. Subsequent calls to Next() will return false.
type Kind ¶
type Kind int
Kind represents the type of TOML structure contained in a given Node.
const ( // Invalid represents an invalid meta node. Invalid Kind = iota // Comment represents a comment meta node. Comment // Key represents a key meta node. Key // Table represents a top-level table. Table // ArrayTable represents a top-level array table. ArrayTable // KeyValue represents a top-level key value. KeyValue // Array represents an array container value. Array // InlineTable represents an inline table container value. InlineTable // String represents a string value. String // Bool represents a boolean value. Bool // Float represents a floating point value. Float // Integer represents an integer value. Integer // LocalDate represents a a local date value. LocalDate // LocalTime represents a local time value. LocalTime // LocalDateTime represents a local date/time value. LocalDateTime // DateTime represents a data/time value. DateTime )
type Node ¶
type Node struct {
Kind Kind
Raw Range // Raw bytes from the input.
Data []byte // Node value (either allocated or referencing the input).
// contains filtered or unexported fields
}
Node in a TOML expression AST.
Depending on Kind, its sequence of children should be interpreted differently.
- Array have one child per element in the array.
- InlineTable have one child per key-value in the table (each of kind InlineTable).
- KeyValue have at least two children. The first one is the value. The rest make a potentially dotted key.
- Table and ArrayTable's children represent a dotted key (same as KeyValue, but without the first node being the value).
When relevant, Raw describes the range of bytes this node is referring to in the input document. Use Parser.Raw() to retrieve the actual bytes.
func (*Node) Child ¶
Child returns a pointer to the first child node of this node. Other children can be accessed calling Next on the first child. Returns nil if this Node has no child.
func (*Node) Key ¶
Key returns the children nodes making the Key on a supported node. Panics otherwise. They are guaranteed to be all be of the Kind Key. A simple key would return just one element.
type Parser ¶
type Parser struct {
KeepComments bool
// contains filtered or unexported fields
}
Parser scans over a TOML-encoded document and generates an iterative AST.
To prime the Parser, first reset it with the contents of a TOML document. Then, process all top-level expressions sequentially. See Example.
Don't forget to check Error() after you're done parsing.
Each top-level expression needs to be fully processed before calling NextExpression() again. Otherwise, calls to various Node methods may panic if the parser has moved on the next expression.
For performance reasons, go-toml doesn't make a copy of the input bytes to the parser. Make sure to copy all the bytes you need to outlive the slice given to the parser.
Example ¶
doc := `
hello = "world"
value = 42
`
p := Parser{}
p.Reset([]byte(doc))
for p.NextExpression() {
e := p.Expression()
fmt.Printf("Expression: %s\n", e.Kind)
value := e.Value()
it := e.Key()
k := it.Node() // shortcut: we know there is no dotted key in the example
fmt.Printf("%s -> (%s) %s\n", k.Data, value.Kind, value.Data)
}
Output: Expression: KeyValue hello -> (String) world Expression: KeyValue value -> (Integer) 42
Example (Comments) ¶
This example demonstrates how to parse a TOML document and preserving comments. Comments are stored in the AST as Comment nodes. This example displays the structure of the full AST generated by the parser using the following structure:
- Each root-level expression is separated by three dashes.
- Bytes associated to a node are displayed in square brackets.
- Siblings have the same indentation.
- Children of a node are indented one level.
doc := `# Top of the document comment.
# Optional, any amount of lines.
# Above table.
[table] # Next to table.
# Above simple value.
key = "value" # Next to simple value.
# Below simple value.
# Some comment alone.
# Multiple comments, on multiple lines.
# Above inline table.
name = { first = "Tom", last = "Preston-Werner" } # Next to inline table.
# Below inline table.
# Above array.
array = [ 1, 2, 3 ] # Next to one-line array.
# Below array.
# Above multi-line array.
key5 = [ # Next to start of inline array.
# Second line before array content.
1, # Next to first element.
# After first element.
# Before second element.
2,
3, # Next to last element
# After last element.
] # Next to end of array.
# Below multi-line array.
# Before array table.
[[products]] # Next to array table.
# After array table.
`
var printGeneric func(*Parser, int, *Node)
printGeneric = func(p *Parser, indent int, e *Node) {
if e == nil {
return
}
s := p.Shape(e.Raw)
x := fmt.Sprintf("%d:%d->%d:%d (%d->%d)", s.Start.Line, s.Start.Column, s.End.Line, s.End.Column, s.Start.Offset, s.End.Offset)
fmt.Printf("%-25s | %s%s [%s]\n", x, strings.Repeat(" ", indent), e.Kind, e.Data)
printGeneric(p, indent+1, e.Child())
printGeneric(p, indent, e.Next())
}
printTree := func(p *Parser) {
for p.NextExpression() {
e := p.Expression()
fmt.Println("---")
printGeneric(p, 0, e)
}
if err := p.Error(); err != nil {
panic(err)
}
}
p := &Parser{
KeepComments: true,
}
p.Reset([]byte(doc))
printTree(p)
Output: --- 1:1->1:31 (0->30) | Comment [# Top of the document comment.] --- 2:1->2:33 (31->63) | Comment [# Optional, any amount of lines.] --- 4:1->4:15 (65->79) | Comment [# Above table.] --- 1:1->1:1 (0->0) | Table [] 5:2->5:7 (81->86) | Key [table] 5:9->5:25 (88->104) | Comment [# Next to table.] --- 6:1->6:22 (105->126) | Comment [# Above simple value.] --- 7:1->7:14 (127->140) | KeyValue [] 7:7->7:14 (133->140) | String [value] 7:1->7:4 (127->130) | Key [key] 7:15->7:38 (141->164) | Comment [# Next to simple value.] --- 8:1->8:22 (165->186) | Comment [# Below simple value.] --- 10:1->10:22 (188->209) | Comment [# Some comment alone.] --- 12:1->12:40 (211->250) | Comment [# Multiple comments, on multiple lines.] --- 14:1->14:22 (252->273) | Comment [# Above inline table.] --- 15:1->15:50 (274->323) | KeyValue [] 15:8->15:9 (281->282) | InlineTable [] 15:10->15:23 (283->296) | KeyValue [] 15:18->15:23 (291->296) | String [Tom] 15:10->15:15 (283->288) | Key [first] 15:25->15:48 (298->321) | KeyValue [] 15:32->15:48 (305->321) | String [Preston-Werner] 15:25->15:29 (298->302) | Key [last] 15:1->15:5 (274->278) | Key [name] 15:51->15:74 (324->347) | Comment [# Next to inline table.] --- 16:1->16:22 (348->369) | Comment [# Below inline table.] --- 18:1->18:15 (371->385) | Comment [# Above array.] --- 19:1->19:20 (386->405) | KeyValue [] 1:1->1:1 (0->0) | Array [] 19:11->19:12 (396->397) | Integer [1] 19:14->19:15 (399->400) | Integer [2] 19:17->19:18 (402->403) | Integer [3] 19:1->19:6 (386->391) | Key [array] 19:21->19:46 (406->431) | Comment [# Next to one-line array.] --- 20:1->20:15 (432->446) | Comment [# Below array.] --- 22:1->22:26 (448->473) | Comment [# Above multi-line array.] --- 23:1->31:2 (474->694) | KeyValue [] 1:1->1:1 (0->0) | Array [] 23:10->23:42 (483->515) | Comment [# Next to start of inline array.] 24:3->24:38 (518->553) | Comment [# Second line before array content.] 25:3->25:4 (556->557) | Integer [1] 25:6->25:30 (559->583) | Comment [# Next to first element.] 26:3->26:25 (586->608) | Comment [# After first element.] 27:3->27:27 (611->635) | Comment [# Before second element.] 28:3->28:4 (638->639) | Integer [2] 29:3->29:4 (643->644) | Integer [3] 29:6->29:28 (646->668) | Comment [# Next to last element] 30:3->30:24 (671->692) | Comment [# After last element.] 23:1->23:5 (474->478) | Key [key5] 31:3->31:26 (695->718) | Comment [# Next to end of array.] --- 32:1->32:26 (719->744) | Comment [# Below multi-line array.] --- 34:1->34:22 (746->767) | Comment [# Before array table.] --- 1:1->1:1 (0->0) | ArrayTable [] 35:3->35:11 (770->778) | Key [products] 35:14->35:36 (781->803) | Comment [# Next to array table.] --- 36:1->36:21 (804->824) | Comment [# After array table.]
func (*Parser) Expression ¶
Expression returns a pointer to the node representing the last successfully parsed expression.
func (*Parser) NextExpression ¶
NextExpression parses the next top-level expression. If an expression was successfully parsed, it returns true. If the parser is at the end of the document or an error occurred, it returns false.
Retrieve the parsed expression with Expression().
func (*Parser) Range ¶
Range returns a range description that corresponds to a given slice of the input. If the argument is not a subslice of the parser input, this function panics.
type ParserError ¶
ParserError describes an error relative to the content of the document.
It cannot outlive the instance of Parser it refers to, and may cause panics if the parser is reset.
func (*ParserError) Error ¶
func (e *ParserError) Error() string
Error is the implementation of the error interface.
type Position ¶ added in v2.0.8
type Position struct {
// Number of bytes from the beginning of the input.
Offset int
// Line number, starting at 1.
Line int
// Column number, starting at 1.
Column int
}
Position describes a position in the input.
type RawMessage ¶ added in v2.3.0
type RawMessage []byte
RawMessage is a raw encoded TOML value. It implements Unmarshaler and can be used to delay TOML decoding or capture raw content.
Example usage:
type Config struct {
Plugin RawMessage `toml:"plugin"`
}
var cfg Config
toml.NewDecoder(r).EnableUnmarshalerInterface().Decode(&cfg)
// cfg.Plugin now contains the raw TOML bytes for [plugin]
func (*RawMessage) UnmarshalTOML ¶ added in v2.3.0
func (m *RawMessage) UnmarshalTOML(data []byte) error
UnmarshalTOML implements Unmarshaler.
type Unmarshaler ¶ added in v2.2.0
Unmarshaler is implemented by types that can unmarshal a TOML description of themselves. The input is a valid TOML document containing the relevant portion of the parsed document.
For tables (including split tables defined in multiple places), the data contains the raw key-value bytes from the original document with adjusted table headers to be relative to the unmarshaling target.
Source Files