Change a tag, a style or an anchor¶

Use Transaction.ChangePresentation to set or remove a node's tag and keep its value, and Transaction.ReplaceWithPresentation to write a new value and state its tag or style in one command:

err := file.Edit(func(tx *yamldoc.Transaction) error {
    return tx.ChangePresentation(node, yamldoc.Presentation{Tag: yamldoc.RemoveTag()})
})

An ordinary Replace never changes a tag. A write that would need one is refused with ErrTagIntent, and an ordinary write picks the style for you. These two commands are the way to say you mean it.

Replace a value and its tag¶

tx.ReplaceWithPresentation(node, 3, yamldoc.Presentation{Tag: yamldoc.RemoveTag()})
// value: !!str "3"  →  value: 3

tx.ReplaceWithPresentation(node, 3, yamldoc.Presentation{Tag: yamldoc.SetTag("!!int")})
// value: !!str "3"  →  value: !!int 3

The value is written as an ordinary write would write it, and the tag follows. It works across kinds too:

tx.ReplaceWithPresentation(node, map[string]any{"a": 1}, yamldoc.Presentation{Tag: yamldoc.SetTag("!!map")})
// value: !!str x  →  value: !!map
//                      a: 1

Change only the tag¶

ChangePresentation leaves the source alone where it can, so a spelling such as 0x10 survives:

tx.ChangePresentation(node, yamldoc.Presentation{Tag: yamldoc.SetTag("!!int")})
// value: 0x10       →  value: !!int 0x10

tx.ChangePresentation(node, yamldoc.Presentation{Tag: yamldoc.RemoveTag()})
// value: !!int 0x10 →  value: 0x10

Removing a tag keeps the typed value, so the style changes when the bare source would mean something else:

tx.ChangePresentation(node, yamldoc.Presentation{Tag: yamldoc.RemoveTag()})
// value: !!str 3    →  value: "3"
// value: !!str true →  value: "true"

How to spell a tag¶

SetTag takes the tag as it should appear in the source:

Spelling counts. !<tag:yaml.org,2002:int> over !!int is a respelling, and it is written. Setting the exact spelling a node already carries changes nothing, and neither does removing a tag from an untagged node.

What gets refused¶

A refused intent fails with the error below, poisons the transaction, and leaves the file as it was.

The profile decides what a tag means. A tag it doesn't interpret, such as !local or !!set under Core, is opaque: the document can carry it, but it has no typed value to compare. So ReplaceWithPresentation writes one, and ChangePresentation refuses to add one because the value would change. Under a profile with !!set, a mapping whose values aren't all null is refused.

Choose a scalar's style¶

UseStyle writes a scalar in the style you name, or refuses:

tx.ChangePresentation(node, yamldoc.Presentation{Style: yamldoc.UseStyle(yamldoc.StyleSingleQuoted)})
// value: abc        →  value: 'abc'

tx.ReplaceWithPresentation(node, "one\ntwo\n", yamldoc.Presentation{Style: yamldoc.UseStyle(yamldoc.StyleLiteral)})
// value: 'old'      →  value: |
//                        one
//                        two

The styles are StylePlain, StyleSingleQuoted, StyleDoubleQuoted, StyleLiteral and StyleFolded. There's no fallback: where an ordinary write would quite happily switch to double quotes, a stated style that can't be written is refused. A comment on the scalar's line stays on it, and a block style goes on the line with its body below. Asking for the style a scalar already has changes nothing, so "\x41" stays spelled that way.

A style and a tag can go together, which is how a plain scalar reads as something it wouldn't on its own:

tx.ReplaceWithPresentation(node, "true", yamldoc.Presentation{
    Tag:   yamldoc.SetTag("!!str"),
    Style: yamldoc.UseStyle(yamldoc.StylePlain),
})
// value: true       →  value: !!str true

Both are honoured or the command is refused, and the tag is applied first.

Add, rename or remove an anchor¶

tx.ChangePresentation(node, yamldoc.Presentation{Anchor: yamldoc.AddAnchor("base")})
// value: x          →  value: &base x

tx.ChangePresentation(node, yamldoc.Presentation{Anchor: yamldoc.RenameAnchor("shared")})
// value: &base x    →  value: &shared x
// copy: *base       →  copy: *shared

tx.ChangePresentation(node, yamldoc.Presentation{Anchor: yamldoc.RemoveAnchor()})
// value: &shared x  →  value: x

A rename rewrites every alias bound to this anchor and no other: an alias after a redefinition of the old name still belongs to the redefinition. An anchor can go with a tag and a style in one command, and is written after the tag.

Adding the name a node already has, renaming to it, or removing an anchor from a node without one changes nothing.

Make or expand an alias¶

ReplaceWithAlias writes an alias over a node, to an earlier node that already has an anchor:

tx.ReplaceWithAlias(second, first)
// first: &shared {a: 1}     first: &shared {a: 1}
// second: {a: 1}         →  second: *shared

ExpandAlias writes the value the alias refers to in its place. The copy is a new value, so it has no anchor at its root and takes none of the original's comments or number spellings. An anchor nested in the copy takes a fresh name, and the aliases in the copy that refer to it follow:

tx.ExpandAlias(value)
// base: &a                  base: &a
//   x: &in 1                  x: &in 1
//   y: *in                    y: *in
// value: *a              →  value:
//                             x: &yaml1 1
//                             y: *yaml1

To remove an anchor that has aliases, expand each alias and then remove it. All of these can share a transaction.