blob: 30813884c0679281201db03b2342365bb8a6afda [file] [log] [blame]
Matteo Scandoloa4285862020-12-01 18:10:10 -08001// Package yaml implements YAML support for the Go language.
2//
3// Source code and other details for the project are available at GitHub:
4//
5// https://github.com/go-yaml/yaml
6//
7package yaml
8
9import (
10 "errors"
11 "fmt"
12 "io"
13 "reflect"
14 "strings"
15 "sync"
16)
17
18// MapSlice encodes and decodes as a YAML map.
19// The order of keys is preserved when encoding and decoding.
20type MapSlice []MapItem
21
22// MapItem is an item in a MapSlice.
23type MapItem struct {
24 Key, Value interface{}
25}
26
27// The Unmarshaler interface may be implemented by types to customize their
28// behavior when being unmarshaled from a YAML document. The UnmarshalYAML
29// method receives a function that may be called to unmarshal the original
30// YAML value into a field or variable. It is safe to call the unmarshal
31// function parameter more than once if necessary.
32type Unmarshaler interface {
33 UnmarshalYAML(unmarshal func(interface{}) error) error
34}
35
36// The Marshaler interface may be implemented by types to customize their
37// behavior when being marshaled into a YAML document. The returned value
38// is marshaled in place of the original value implementing Marshaler.
39//
40// If an error is returned by MarshalYAML, the marshaling procedure stops
41// and returns with the provided error.
42type Marshaler interface {
43 MarshalYAML() (interface{}, error)
44}
45
46// Unmarshal decodes the first document found within the in byte slice
47// and assigns decoded values into the out value.
48//
49// Maps and pointers (to a struct, string, int, etc) are accepted as out
50// values. If an internal pointer within a struct is not initialized,
51// the yaml package will initialize it if necessary for unmarshalling
52// the provided data. The out parameter must not be nil.
53//
54// The type of the decoded values should be compatible with the respective
55// values in out. If one or more values cannot be decoded due to a type
56// mismatches, decoding continues partially until the end of the YAML
57// content, and a *yaml.TypeError is returned with details for all
58// missed values.
59//
60// Struct fields are only unmarshalled if they are exported (have an
61// upper case first letter), and are unmarshalled using the field name
62// lowercased as the default key. Custom keys may be defined via the
63// "yaml" name in the field tag: the content preceding the first comma
64// is used as the key, and the following comma-separated options are
65// used to tweak the marshalling process (see Marshal).
66// Conflicting names result in a runtime error.
67//
68// For example:
69//
70// type T struct {
71// F int `yaml:"a,omitempty"`
72// B int
73// }
74// var t T
75// yaml.Unmarshal([]byte("a: 1\nb: 2"), &t)
76//
77// See the documentation of Marshal for the format of tags and a list of
78// supported tag options.
79//
80func Unmarshal(in []byte, out interface{}) (err error) {
81 return unmarshal(in, out, false)
82}
83
84// UnmarshalStrict is like Unmarshal except that any fields that are found
85// in the data that do not have corresponding struct members, or mapping
86// keys that are duplicates, will result in
87// an error.
88func UnmarshalStrict(in []byte, out interface{}) (err error) {
89 return unmarshal(in, out, true)
90}
91
92// A Decoder reads and decodes YAML values from an input stream.
93type Decoder struct {
94 strict bool
95 parser *parser
96}
97
98// NewDecoder returns a new decoder that reads from r.
99//
100// The decoder introduces its own buffering and may read
101// data from r beyond the YAML values requested.
102func NewDecoder(r io.Reader) *Decoder {
103 return &Decoder{
104 parser: newParserFromReader(r),
105 }
106}
107
108// SetStrict sets whether strict decoding behaviour is enabled when
109// decoding items in the data (see UnmarshalStrict). By default, decoding is not strict.
110func (dec *Decoder) SetStrict(strict bool) {
111 dec.strict = strict
112}
113
114// Decode reads the next YAML-encoded value from its input
115// and stores it in the value pointed to by v.
116//
117// See the documentation for Unmarshal for details about the
118// conversion of YAML into a Go value.
119func (dec *Decoder) Decode(v interface{}) (err error) {
120 d := newDecoder(dec.strict)
121 defer handleErr(&err)
122 node := dec.parser.parse()
123 if node == nil {
124 return io.EOF
125 }
126 out := reflect.ValueOf(v)
127 if out.Kind() == reflect.Ptr && !out.IsNil() {
128 out = out.Elem()
129 }
130 d.unmarshal(node, out)
131 if len(d.terrors) > 0 {
132 return &TypeError{d.terrors}
133 }
134 return nil
135}
136
137func unmarshal(in []byte, out interface{}, strict bool) (err error) {
138 defer handleErr(&err)
139 d := newDecoder(strict)
140 p := newParser(in)
141 defer p.destroy()
142 node := p.parse()
143 if node != nil {
144 v := reflect.ValueOf(out)
145 if v.Kind() == reflect.Ptr && !v.IsNil() {
146 v = v.Elem()
147 }
148 d.unmarshal(node, v)
149 }
150 if len(d.terrors) > 0 {
151 return &TypeError{d.terrors}
152 }
153 return nil
154}
155
156// Marshal serializes the value provided into a YAML document. The structure
157// of the generated document will reflect the structure of the value itself.
158// Maps and pointers (to struct, string, int, etc) are accepted as the in value.
159//
160// Struct fields are only marshalled if they are exported (have an upper case
161// first letter), and are marshalled using the field name lowercased as the
162// default key. Custom keys may be defined via the "yaml" name in the field
163// tag: the content preceding the first comma is used as the key, and the
164// following comma-separated options are used to tweak the marshalling process.
165// Conflicting names result in a runtime error.
166//
167// The field tag format accepted is:
168//
169// `(...) yaml:"[<key>][,<flag1>[,<flag2>]]" (...)`
170//
171// The following flags are currently supported:
172//
173// omitempty Only include the field if it's not set to the zero
174// value for the type or to empty slices or maps.
175// Zero valued structs will be omitted if all their public
176// fields are zero, unless they implement an IsZero
177// method (see the IsZeroer interface type), in which
David K. Bainbridge06631892021-08-19 13:07:00 +0000178// case the field will be excluded if IsZero returns true.
Matteo Scandoloa4285862020-12-01 18:10:10 -0800179//
180// flow Marshal using a flow style (useful for structs,
181// sequences and maps).
182//
183// inline Inline the field, which must be a struct or a map,
184// causing all of its fields or keys to be processed as if
185// they were part of the outer struct. For maps, keys must
186// not conflict with the yaml keys of other struct fields.
187//
188// In addition, if the key is "-", the field is ignored.
189//
190// For example:
191//
192// type T struct {
193// F int `yaml:"a,omitempty"`
194// B int
195// }
196// yaml.Marshal(&T{B: 2}) // Returns "b: 2\n"
197// yaml.Marshal(&T{F: 1}} // Returns "a: 1\nb: 0\n"
198//
199func Marshal(in interface{}) (out []byte, err error) {
200 defer handleErr(&err)
201 e := newEncoder()
202 defer e.destroy()
203 e.marshalDoc("", reflect.ValueOf(in))
204 e.finish()
205 out = e.out
206 return
207}
208
209// An Encoder writes YAML values to an output stream.
210type Encoder struct {
211 encoder *encoder
212}
213
214// NewEncoder returns a new encoder that writes to w.
215// The Encoder should be closed after use to flush all data
216// to w.
217func NewEncoder(w io.Writer) *Encoder {
218 return &Encoder{
219 encoder: newEncoderWithWriter(w),
220 }
221}
222
223// Encode writes the YAML encoding of v to the stream.
224// If multiple items are encoded to the stream, the
225// second and subsequent document will be preceded
226// with a "---" document separator, but the first will not.
227//
228// See the documentation for Marshal for details about the conversion of Go
229// values to YAML.
230func (e *Encoder) Encode(v interface{}) (err error) {
231 defer handleErr(&err)
232 e.encoder.marshalDoc("", reflect.ValueOf(v))
233 return nil
234}
235
236// Close closes the encoder by writing any remaining data.
237// It does not write a stream terminating string "...".
238func (e *Encoder) Close() (err error) {
239 defer handleErr(&err)
240 e.encoder.finish()
241 return nil
242}
243
244func handleErr(err *error) {
245 if v := recover(); v != nil {
246 if e, ok := v.(yamlError); ok {
247 *err = e.err
248 } else {
249 panic(v)
250 }
251 }
252}
253
254type yamlError struct {
255 err error
256}
257
258func fail(err error) {
259 panic(yamlError{err})
260}
261
262func failf(format string, args ...interface{}) {
263 panic(yamlError{fmt.Errorf("yaml: "+format, args...)})
264}
265
266// A TypeError is returned by Unmarshal when one or more fields in
267// the YAML document cannot be properly decoded into the requested
268// types. When this error is returned, the value is still
269// unmarshaled partially.
270type TypeError struct {
271 Errors []string
272}
273
274func (e *TypeError) Error() string {
275 return fmt.Sprintf("yaml: unmarshal errors:\n %s", strings.Join(e.Errors, "\n "))
276}
277
278// --------------------------------------------------------------------------
279// Maintain a mapping of keys to structure field indexes
280
281// The code in this section was copied from mgo/bson.
282
283// structInfo holds details for the serialization of fields of
284// a given struct.
285type structInfo struct {
286 FieldsMap map[string]fieldInfo
287 FieldsList []fieldInfo
288
289 // InlineMap is the number of the field in the struct that
290 // contains an ,inline map, or -1 if there's none.
291 InlineMap int
292}
293
294type fieldInfo struct {
295 Key string
296 Num int
297 OmitEmpty bool
298 Flow bool
299 // Id holds the unique field identifier, so we can cheaply
300 // check for field duplicates without maintaining an extra map.
301 Id int
302
303 // Inline holds the field index if the field is part of an inlined struct.
304 Inline []int
305}
306
307var structMap = make(map[reflect.Type]*structInfo)
308var fieldMapMutex sync.RWMutex
309
310func getStructInfo(st reflect.Type) (*structInfo, error) {
311 fieldMapMutex.RLock()
312 sinfo, found := structMap[st]
313 fieldMapMutex.RUnlock()
314 if found {
315 return sinfo, nil
316 }
317
318 n := st.NumField()
319 fieldsMap := make(map[string]fieldInfo)
320 fieldsList := make([]fieldInfo, 0, n)
321 inlineMap := -1
322 for i := 0; i != n; i++ {
323 field := st.Field(i)
324 if field.PkgPath != "" && !field.Anonymous {
325 continue // Private field
326 }
327
328 info := fieldInfo{Num: i}
329
330 tag := field.Tag.Get("yaml")
331 if tag == "" && strings.Index(string(field.Tag), ":") < 0 {
332 tag = string(field.Tag)
333 }
334 if tag == "-" {
335 continue
336 }
337
338 inline := false
339 fields := strings.Split(tag, ",")
340 if len(fields) > 1 {
341 for _, flag := range fields[1:] {
342 switch flag {
343 case "omitempty":
344 info.OmitEmpty = true
345 case "flow":
346 info.Flow = true
347 case "inline":
348 inline = true
349 default:
350 return nil, errors.New(fmt.Sprintf("Unsupported flag %q in tag %q of type %s", flag, tag, st))
351 }
352 }
353 tag = fields[0]
354 }
355
356 if inline {
357 switch field.Type.Kind() {
358 case reflect.Map:
359 if inlineMap >= 0 {
360 return nil, errors.New("Multiple ,inline maps in struct " + st.String())
361 }
362 if field.Type.Key() != reflect.TypeOf("") {
363 return nil, errors.New("Option ,inline needs a map with string keys in struct " + st.String())
364 }
365 inlineMap = info.Num
366 case reflect.Struct:
367 sinfo, err := getStructInfo(field.Type)
368 if err != nil {
369 return nil, err
370 }
371 for _, finfo := range sinfo.FieldsList {
372 if _, found := fieldsMap[finfo.Key]; found {
373 msg := "Duplicated key '" + finfo.Key + "' in struct " + st.String()
374 return nil, errors.New(msg)
375 }
376 if finfo.Inline == nil {
377 finfo.Inline = []int{i, finfo.Num}
378 } else {
379 finfo.Inline = append([]int{i}, finfo.Inline...)
380 }
381 finfo.Id = len(fieldsList)
382 fieldsMap[finfo.Key] = finfo
383 fieldsList = append(fieldsList, finfo)
384 }
385 default:
386 //return nil, errors.New("Option ,inline needs a struct value or map field")
387 return nil, errors.New("Option ,inline needs a struct value field")
388 }
389 continue
390 }
391
392 if tag != "" {
393 info.Key = tag
394 } else {
395 info.Key = strings.ToLower(field.Name)
396 }
397
398 if _, found = fieldsMap[info.Key]; found {
399 msg := "Duplicated key '" + info.Key + "' in struct " + st.String()
400 return nil, errors.New(msg)
401 }
402
403 info.Id = len(fieldsList)
404 fieldsList = append(fieldsList, info)
405 fieldsMap[info.Key] = info
406 }
407
408 sinfo = &structInfo{
409 FieldsMap: fieldsMap,
410 FieldsList: fieldsList,
411 InlineMap: inlineMap,
412 }
413
414 fieldMapMutex.Lock()
415 structMap[st] = sinfo
416 fieldMapMutex.Unlock()
417 return sinfo, nil
418}
419
420// IsZeroer is used to check whether an object is zero to
421// determine whether it should be omitted when marshaling
422// with the omitempty flag. One notable implementation
423// is time.Time.
424type IsZeroer interface {
425 IsZero() bool
426}
427
428func isZero(v reflect.Value) bool {
429 kind := v.Kind()
430 if z, ok := v.Interface().(IsZeroer); ok {
431 if (kind == reflect.Ptr || kind == reflect.Interface) && v.IsNil() {
432 return true
433 }
434 return z.IsZero()
435 }
436 switch kind {
437 case reflect.String:
438 return len(v.String()) == 0
439 case reflect.Interface, reflect.Ptr:
440 return v.IsNil()
441 case reflect.Slice:
442 return v.Len() == 0
443 case reflect.Map:
444 return v.Len() == 0
445 case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
446 return v.Int() == 0
447 case reflect.Float32, reflect.Float64:
448 return v.Float() == 0
449 case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
450 return v.Uint() == 0
451 case reflect.Bool:
452 return !v.Bool()
453 case reflect.Struct:
454 vt := v.Type()
455 for i := v.NumField() - 1; i >= 0; i-- {
456 if vt.Field(i).PkgPath != "" {
457 continue // Private field
458 }
459 if !isZero(v.Field(i)) {
460 return false
461 }
462 }
463 return true
464 }
465 return false
466}
David K. Bainbridge06631892021-08-19 13:07:00 +0000467
468// FutureLineWrap globally disables line wrapping when encoding long strings.
469// This is a temporary and thus deprecated method introduced to faciliate
470// migration towards v3, which offers more control of line lengths on
471// individual encodings, and has a default matching the behavior introduced
472// by this function.
473//
474// The default formatting of v2 was erroneously changed in v2.3.0 and reverted
475// in v2.4.0, at which point this function was introduced to help migration.
476func FutureLineWrap() {
477 disableLineWrapping = true
478}