Documentation
¶
Overview ¶
Package sourceindex answers, in one walk, the questions asked of a decoded source tree before any of it is lowered.
The questions are small and unrelated to each other — how many nodes did the document declare, and does any alias point back at one of its own ancestors — but each was answered by a whole traversal of its own, so a compile walked the same tree once per question. They share a walk here instead, and the answers become a value the caller carries rather than a walk the caller repeats.
The index is a value with no exported fields and no maps, so a copy is independent of the original and nothing that receives one can write through it to a holder. It is derived from the tree alone: two indexes built over the same tree are equal, whatever order their answers are read in.
Index ¶
Constants ¶
const MaxIndexedNodes = 1 << 24 // 16,777,216
MaxIndexedNodes bounds how many nodes one index walks.
It is not a memory guard: the tree is already materialized by the decode that produced it, and the index itself holds one counter and one node pointer whatever the tree's size. It is the explicit limit the bounded-everything rule requires of every loop, placed far above any document that could have been decoded in the first place — the largest spec in this repository's corpora parses to fewer than 5,000 nodes, and the largest public OpenAPI documents to a few million. A document past it is refused by the caller rather than half-counted, because a truncated count would understate the alias-expansion allowance derived from it and could refuse a document on a bound it never crossed.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Index ¶
type Index struct {
// contains filtered or unexported fields
}
Index is what one walk over a decoded source tree found.
A zero Index is the answer for a document with no content: no root, no nodes, no anchor cycle, nothing truncated. That is the same answer Build returns for an empty document, so a caller never has to tell the two apart.
func Build ¶
Build walks the tree under root once and returns what it found. root may be a document node or the content node itself; either way the index is rooted at the content, which is the node every consumer scans from.
maxNodes is the caller's bound on the walk — MaxIndexedNodes in the compiler, smaller in a test that drives the truncated path. A non-positive bound indexes nothing and reports Truncated, which is the safe direction: it never claims a count it did not reach.
func (Index) AnchorCycle ¶
AnchorCycle is the first alias, in document order, whose target is one of its own ancestors — a recursive YAML anchor that expands without bound. Legal anchor reuse, where an alias names a node that is not an ancestor, is not one.
func (Index) Nodes ¶
Nodes is how many nodes the tree declares, before any alias is substituted. An alias counts as one and its target is not counted again through it, which is what makes this the document's own size rather than its expansion. It is meaningful only when Truncated is false.
Source Files