Anchors, aliases and merge keys
Writing an anchor
Tag the field that holds the shared value with ,anchor, and the field that
refers to it with ,alias:
codec.MarshalAnchor gives you a callback to name each anchor yourself, and
codec.WithSmartAnchor names them from the field.
Reading a merge key
A plain << does nothing under YAML 1.2
<< is a plain scalar that a 1.1 processor resolves to the merge type. YAML 1.2
dropped resolution by scalar shape, and this library follows the schema β so
under the 1.2 default << is an ordinary key, the merge never happens, and
there is no error.
Writing the tag out says the same thing without relying on resolution, and that is honoured at every version:
| written | 1.2 | 1.1 |
|---|---|---|
<<: *d | not merged | merged |
!!merge <<: *d | merged | merged |
!!merge on any key other than << is refused: could not find merge key.
Decode the document above, exactly as Marshal wrote it:
people[1] is meant to be the default person entire. Under 1.2 it comes back
empty.
Use parser.WithMergeKeys() when you have to read documents written this
way. It resolves a bare << at any version and changes nothing else:
| merge | a: yes | b: 0100 | |
|---|---|---|---|
| default | no | "yes" | 100 |
WithMergeKeys() | yes | "yes" | 100 |
WithYAMLVersion(YAML11) | yes | true | 64 |
Reading a whole document under 1.1 to get one merge key changes far more than the
merge: 0100 becomes 64, 1_000 becomes 1000, 1:30 becomes 90 and yes
becomes true. Reach for WithMergeKeys instead, or write !!merge <<: in the
document if you control it.
This follows from one rule the library holds everywhere: a written tag is
honoured at any version, and only resolution by scalar shape is version-gated.
It has a consequence worth knowing before you rely on a round trip β the encoder
writes the plain <<, so Marshal produces a document that Unmarshal will not
merge unless the reading side passes WithMergeKeys. Other Go libraries resolve
<< at any version, which is what WithMergeKeys exists to match.
When the merge does fire, the mapping’s own key beats the merged one, and an earlier merge beats a later one.
Reading an alias
By default an alias decodes to an independent value. Given
a and b are two Go values, and changing one does not change the other.
codec.ShareAliases makes them the same value.
Sharing and round-tripping go together
The encoder finds anchors by pointer address. Two independent values are two
anchors, so a decode without ShareAliases followed by an encode writes the
shared subtree out twice instead of anchoring it once. If you are reading a
document in order to write it back, pass ShareAliases.
Anchors declared in another file
codec.ReferenceDirs, ReferenceFiles and ReferenceReaders publish anchors
from elsewhere. Given testdata/anchor.yml:
RecursiveDir(true) walks subdirectories; on its own it means nothing.
Anchors do not cross documents
Documents in one stream are independent, so an alias must name an anchor declared
in the same document. To reach an anchor from another parse, hand it over with
parser.WithAnchors β see the parser.
The alias budget
A document can name one anchor from many aliases, and an anchor can hold a large
subtree, so an adversarial document expands enormously. The decoder caps the work
and returns errors.NewExcessiveAliasing when a document exceeds it.
NewRecursiveAlias and NewUnknownAnchor cover the other two failures.