feat(node): add ability to merge mapping nodes (node.merge())

[sitano]

A merge API for a yaml.Node that can merge/replace mapping and sequence nodes depending on the configuration. The implementation currently consumes src Node to avoid copy-pasting the whole tree hierarchy for the use cases where in the most cases I expect the src value will be dumped.

func (dst *Node) Merge(src *Node, opts ...MergeOption) error {}
func (dst *Node) MergeWithOptions(src *Node, opts MergeOptions) error {}

type MergeOptions struct {
	// When MergeMap is true mapping nodes are merged instead of replaced. Default is true.
	MergeMap bool
	// When AppendSeq is true sequence nodes are appended instead of replaced. Default is false.
	AppendSeq bool
}

var (
	ErrYamlUnknown          = errors.New("yaml: unknown error")
	ErrYamlUnmergable       = errors.New("yaml: unmergable error")
	ErrYamlInvalidNodeKinds = errors.New("yaml: invalid node kinds")
	ErrYamlManyDocs         = errors.New("yaml: too many documents")
)

Example

map:
  key1: value1
  key2: value2

+

map:
  key2: updated_value2
  key3: value3

->

map:
  key1: value1
  key2: updated_value2
  key3: value3

Notes

See test material for more details on the specifics of behavior.

The rules for processing nulls, implicit and explicit values are a bit complicated. Take a look at the tests.

There are a few cut corners but overall I think its more of a good than the opposite. e.g., it probably should not allow multi doc merge.