yamlpatchcommon

type YAMLContainer[NodeT any] interface {
	// Get returns the child node at the key index. If the key does not exist, it returns nil, nil.
	Get(key string) (NodeT, error)
	// Set overwrites the key with val. It returns an error if the key does not already exist (or index out of bounds, for sequences).
	Set(key string, val NodeT) error
	// Add adds a new node to the container. It returns an error if the key already exists.
	Add(key string, val NodeT) error
	// Remove removes a node from the container. It returns an error if the key does not exist.
	Remove(key string) error
}

type YAMLLibrary[NodeT any] interface {
	// Unmarshal unmarshals the provided YAML bytes into the provided output value.
	Unmarshal(in []byte, out interface{}) (err error)

	// BytesToNode unmarshals the provided YAML bytes into a node. The unmarshalled node will typically be a node that
	// represents a YAML document (a YAML document node), but the specifics depend on the implementation.
	BytesToNode(in []byte) (node NodeT, err error)

	// BytesToContentNode unmarshals the provided YAML bytes into a node. This function is similar to BytesToNode, but
	// if the node returned by the initial unmarshal is a document node, this function will return the content node of
	// the document node (if effectively "unwraps" the document node).
	BytesToContentNode(in []byte) (node NodeT, err error)

	NodeToBytes(node NodeT) (out []byte, err error)

	NodeToValue(node NodeT) (out any, err error)

	ValueToNode(value any, comment string) (NodeT, error)

	SetDocumentNodeContent(documentNode NodeT, valueNode NodeT) error

	NewContainer(node NodeT) (YAMLContainer[NodeT], error)

	CopyNode(node NodeT) (NodeT, error)

	// NodeIsNil returns true if the provided NodeT is nil (or its conceptual equivalent). For most implementations,
	// this will simply be implemented as "return node == nil". However, this function is necessary because the type
	// constraint of "NodeT" is "any", so in generic code "node == nil" / "node == *new(NodeT)" does not compile because
	// "NodeT" is not guaranteed to be comparable or a pointer type.
	// See https://groups.google.com/g/golang-nuts/c/bloyX1Zxjaw, https://github.com/golang/go/issues/61372
	NodeIsNil(node NodeT) bool
}