Add support for document markers

[Luzifer]

YAML specs describe document markers for document start and end:

---

some: yaml

...

In order to have a consistent YAML file after passing through go-yaml when the style guide forces the usage of explicit_start and explicit_end (PyYAML) add an option to add those document markers to the output.

[niemeyer]

It's not entirely clear what a consistent file means in that case. Most yaml files do not include those markers, and the most common case for them is the separation of documents, which is what yaml.Encoder does when there is more than one document.

If more decoration than this is necessary, the easiest route is to simply add that before/after using yaml.Encoder.

[Luzifer]

Sorry for not being clear: consistent in the corporate environment… There is a style guide for writing YAML files which tells to add the document markers for single documents too though it is not required for the file to be parsable.

Having options for those markers would avoid doing stuff like this and have sort of a compatibility to PyYAML:

buf := new(bytes.Buffer)
buf.Write([]byte("---\n\n"))

if err := yaml.NewEncoder(buf).Encode(in); err != nil {
        return fmt.Errorf("Unable to marshal roles file: %s", err)
}

buf.Write([]byte("\n...\n"))

[niemeyer]

Replacing that by something like

enc := yaml.NewEncoder(buf)
enc.SetExplicitMarkers(true)
if err := enc.Encode(in); err != nil {
        return fmt.Errorf("Unable to marshal roles file: %s", err)
}
if err := enc.Close(); err != nil {
        return fmt.Errorf("Unable to marshal roles file: %s", err)
}

doesn't really sound like a huge win.

[Luzifer]

Hmm indeed… And currently I can't imagine a better solution…

Closing this and leaving it here as a documentation the idea was discussed… Maybe someone will have a better idea or at least have an use for the example code…