119 lines
3.0 KiB
Go
119 lines
3.0 KiB
Go
// Copyright 2025 The go-yaml Project Contributors
|
|
// SPDX-License-Identifier: Apache-2.0
|
|
|
|
// This file contains the Dumper API for writing YAML documents.
|
|
//
|
|
// Primary functions:
|
|
// - Dump: Encode value(s) to YAML (use WithAll for multi-doc)
|
|
// - NewDumper: Create a streaming dumper to io.Writer
|
|
|
|
package yaml
|
|
|
|
import (
|
|
"bytes"
|
|
"errors"
|
|
"io"
|
|
"reflect"
|
|
|
|
"go.yaml.in/yaml/v4/internal/libyaml"
|
|
)
|
|
|
|
// Dump encodes a value to YAML with the given options.
|
|
//
|
|
// By default, Dump encodes a single value as a single YAML document.
|
|
//
|
|
// Use WithAllDocuments() to encode multiple values as a multi-document stream:
|
|
//
|
|
// docs := []Config{config1, config2, config3}
|
|
// yaml.Dump(docs, yaml.WithAllDocuments())
|
|
//
|
|
// When WithAllDocuments is used, in must be a slice.
|
|
// Each element is encoded as a separate YAML document with "---" separators.
|
|
//
|
|
// See [Marshal] for details about the conversion of Go values to YAML.
|
|
func Dump(in any, opts ...Option) (out []byte, err error) {
|
|
defer handleErr(&err)
|
|
|
|
o, err := libyaml.ApplyOptions(opts...)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
|
|
var buf bytes.Buffer
|
|
d, err := NewDumper(&buf, func(opts *libyaml.Options) error {
|
|
*opts = *o // Copy options
|
|
return nil
|
|
})
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
|
|
if o.AllDocuments {
|
|
// Multi-document mode: in must be a slice
|
|
inVal := reflect.ValueOf(in)
|
|
if inVal.Kind() != reflect.Slice {
|
|
return nil, &LoadErrors{Errors: []*libyaml.ConstructError{{
|
|
Err: errors.New("yaml: WithAllDocuments requires a slice input"),
|
|
}}}
|
|
}
|
|
|
|
// Dump each element as a separate document
|
|
for i := 0; i < inVal.Len(); i++ {
|
|
if err := d.Dump(inVal.Index(i).Interface()); err != nil {
|
|
return nil, err
|
|
}
|
|
}
|
|
} else {
|
|
// Single-document mode
|
|
if err := d.Dump(in); err != nil {
|
|
return nil, err
|
|
}
|
|
}
|
|
|
|
if err := d.Close(); err != nil {
|
|
return nil, err
|
|
}
|
|
return buf.Bytes(), nil
|
|
}
|
|
|
|
// A Dumper writes YAML values to an output stream with configurable options.
|
|
type Dumper struct {
|
|
encoder *libyaml.Representer
|
|
opts *libyaml.Options
|
|
}
|
|
|
|
// NewDumper returns a new Dumper that writes to w with the given options.
|
|
//
|
|
// The Dumper should be closed after use to flush all data to w.
|
|
func NewDumper(w io.Writer, opts ...Option) (*Dumper, error) {
|
|
o, err := libyaml.ApplyOptions(opts...)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
return &Dumper{
|
|
encoder: libyaml.NewRepresenter(w, o),
|
|
opts: o,
|
|
}, nil
|
|
}
|
|
|
|
// Dump writes the YAML encoding of v to the stream.
|
|
//
|
|
// If multiple values are dumped to the stream, the second and subsequent
|
|
// documents will be preceded with a "---" document separator.
|
|
//
|
|
// See the documentation for [Marshal] for details about the conversion of Go
|
|
// values to YAML.
|
|
func (d *Dumper) Dump(v any) (err error) {
|
|
defer handleErr(&err)
|
|
d.encoder.MarshalDoc("", reflect.ValueOf(v))
|
|
return nil
|
|
}
|
|
|
|
// Close closes the Dumper by writing any remaining data.
|
|
// It does not write a stream terminating string "...".
|
|
func (d *Dumper) Close() (err error) {
|
|
defer handleErr(&err)
|
|
d.encoder.Finish()
|
|
return nil
|
|
}
|