Handle multi-document files¶

A YAML file may hold several documents separated by ---. yamldoc exposes all of them, and editing one leaves the others untouched.

f, _ := yamldoc.Parse(src)

fmt.Println(len(f.Documents()))   // 3

err := f.Documents()[1].Set("server.port", 7070)

Separators, per-document comments and every other document survive byte for byte.

The library assigns no meaning to their order¶

This matters, and it is easy to assume otherwise.

YAML defines a multi-document stream as a sequence of independent documents. Kubernetes treats them as separate resources. A configuration system might reasonably treat later documents as overriding earlier ones.

yamldoc takes no position. It hands you the documents in file order and lets you decide what that order means:

// A configuration loader might merge them, later winning:
for _, d := range f.Documents() {
    mergeInto(effective, d)
}

// A manifest tool might treat them as unrelated:
for _, d := range f.Documents() {
    apply(d)
}

See Mechanism, not policy.

Detecting the separator correctly¶

A --- inside a block scalar is content, not a separator:

script: |
  echo start
  ---
  echo end
after: true

That is one document, and yamldoc reports it as one.

Not supported¶

Creating or removing whole documents. The set of documents in a file is fixed by the file; you can edit any of them, but you cannot add a fourth.