The syntax tree
Editing a document, end to end
Parse, find the node, replace it, write it out:
The layout is the renderer’s, not the document’s
Compare that output with the input. Three things moved that you did not ask to move:
ports:had its entries indented two spaces; they come back at column 0version: 1.2.3 # bump mehad three spaces before the comment# bump meis gone entirely β it belonged to the node that was replaced
Indentation comes from depth in the tree, not from the positions the document was read at: those positions say where a node was, which stops being true the moment anything is edited. So an edit-and-write-back changes the shape of the whole document, not just the line you touched.
If you need the rest of the file untouched, use the positions to splice the new text into the original bytes yourself. Rendering a document back byte for byte is a target, not a feature.
The node types
Every node satisfies ast.Node β String, GetToken, Type, GetComment,
GetPath. Beyond that they group by shape:
| family | types |
|---|---|
| scalars | StringNode, IntegerNode, FloatNode, BoolNode, NullNode, InfinityNode, NanNode, LiteralNode |
| collections | MappingNode, MappingValueNode, SequenceNode, SequenceEntryNode |
| keys | MappingKeyNode (an explicit ? key), MergeKeyNode |
| references | AnchorNode, AliasNode |
| structure | DocumentNode, DirectiveNode, TagNode, CommentNode, CommentGroupNode |
Four interfaces cut across them: ScalarNode, MapNode, MapKeyNode,
ArrayNode. A MappingNode holds Values []*MappingValueNode, in document
order, each with a Key and a Value.
Walking
A node pointer does not outlive the walk
Nodes come from an arena that recycles them. A pointer you keep across a walk β
AliasNode.Target in particular β can end up naming a different part of the
document. Read what you need out of a node while you hold it, rather than storing
the node and coming back to it.
Rendering
Node.String() and File.String() render with the defaults.
ast.NewRenderer configures it:
The options are WithComments, WithIndent, WithIndentSequence and
WithAliasTargets. The encoder drives this same renderer, which is why encoding
and rendering a tree agree.
Merging
ast.Merge merges one node into another. ast.MergeOf reads a
*MappingValueNode and reports whether it is a merge and what it merges β
ast.MergeEntry and ast.Verdict carry the answer. See
merge keys for what fires at which version.
The size of this package
go doc -all ./ast renders over 300 entries, four times any other package here β
roughly one node type per shape, each with a full method set. Most programs need
Node, MappingNode, MappingValueNode, SequenceNode, the scalars, Walk
and the renderer. The rest is there for the parser and the encoder.