blob: 8cec6da48d3ec4d8858ca622383c75e359faee1f [file] [log] [blame]
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +00001//
2// Copyright (c) 2011-2019 Canonical Ltd
3//
4// Licensed under the Apache License, Version 2.0 (the "License");
5// you may not use this file except in compliance with the License.
6// You may obtain a copy of the License at
7//
8// http://www.apache.org/licenses/LICENSE-2.0
9//
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15
16// Package yaml implements YAML support for the Go language.
17//
18// Source code and other details for the project are available at GitHub:
19//
20// https://github.com/go-yaml/yaml
21//
22package yaml
23
24import (
25 "errors"
26 "fmt"
27 "io"
28 "reflect"
29 "strings"
30 "sync"
31 "unicode/utf8"
32)
33
34// The Unmarshaler interface may be implemented by types to customize their
35// behavior when being unmarshaled from a YAML document.
36type Unmarshaler interface {
37 UnmarshalYAML(value *Node) error
38}
39
40type obsoleteUnmarshaler interface {
41 UnmarshalYAML(unmarshal func(interface{}) error) error
42}
43
44// The Marshaler interface may be implemented by types to customize their
45// behavior when being marshaled into a YAML document. The returned value
46// is marshaled in place of the original value implementing Marshaler.
47//
48// If an error is returned by MarshalYAML, the marshaling procedure stops
49// and returns with the provided error.
50type Marshaler interface {
51 MarshalYAML() (interface{}, error)
52}
53
54// Unmarshal decodes the first document found within the in byte slice
55// and assigns decoded values into the out value.
56//
57// Maps and pointers (to a struct, string, int, etc) are accepted as out
58// values. If an internal pointer within a struct is not initialized,
59// the yaml package will initialize it if necessary for unmarshalling
60// the provided data. The out parameter must not be nil.
61//
62// The type of the decoded values should be compatible with the respective
63// values in out. If one or more values cannot be decoded due to a type
64// mismatches, decoding continues partially until the end of the YAML
65// content, and a *yaml.TypeError is returned with details for all
66// missed values.
67//
68// Struct fields are only unmarshalled if they are exported (have an
69// upper case first letter), and are unmarshalled using the field name
70// lowercased as the default key. Custom keys may be defined via the
71// "yaml" name in the field tag: the content preceding the first comma
72// is used as the key, and the following comma-separated options are
73// used to tweak the marshalling process (see Marshal).
74// Conflicting names result in a runtime error.
75//
76// For example:
77//
78// type T struct {
79// F int `yaml:"a,omitempty"`
80// B int
81// }
82// var t T
83// yaml.Unmarshal([]byte("a: 1\nb: 2"), &t)
84//
85// See the documentation of Marshal for the format of tags and a list of
86// supported tag options.
87//
88func Unmarshal(in []byte, out interface{}) (err error) {
89 return unmarshal(in, out, false)
90}
91
92// A Decoder reads and decodes YAML values from an input stream.
93type Decoder struct {
94 parser *parser
95 knownFields bool
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// KnownFields ensures that the keys in decoded mappings to
109// exist as fields in the struct being decoded into.
110func (dec *Decoder) KnownFields(enable bool) {
111 dec.knownFields = enable
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()
121 d.knownFields = dec.knownFields
122 defer handleErr(&err)
123 node := dec.parser.parse()
124 if node == nil {
125 return io.EOF
126 }
127 out := reflect.ValueOf(v)
128 if out.Kind() == reflect.Ptr && !out.IsNil() {
129 out = out.Elem()
130 }
131 d.unmarshal(node, out)
132 if len(d.terrors) > 0 {
133 return &TypeError{d.terrors}
134 }
135 return nil
136}
137
138// Decode decodes the node and stores its data into the value pointed to by v.
139//
140// See the documentation for Unmarshal for details about the
141// conversion of YAML into a Go value.
142func (n *Node) Decode(v interface{}) (err error) {
143 d := newDecoder()
144 defer handleErr(&err)
145 out := reflect.ValueOf(v)
146 if out.Kind() == reflect.Ptr && !out.IsNil() {
147 out = out.Elem()
148 }
149 d.unmarshal(n, out)
150 if len(d.terrors) > 0 {
151 return &TypeError{d.terrors}
152 }
153 return nil
154}
155
156func unmarshal(in []byte, out interface{}, strict bool) (err error) {
157 defer handleErr(&err)
158 d := newDecoder()
159 p := newParser(in)
160 defer p.destroy()
161 node := p.parse()
162 if node != nil {
163 v := reflect.ValueOf(out)
164 if v.Kind() == reflect.Ptr && !v.IsNil() {
165 v = v.Elem()
166 }
167 d.unmarshal(node, v)
168 }
169 if len(d.terrors) > 0 {
170 return &TypeError{d.terrors}
171 }
172 return nil
173}
174
175// Marshal serializes the value provided into a YAML document. The structure
176// of the generated document will reflect the structure of the value itself.
177// Maps and pointers (to struct, string, int, etc) are accepted as the in value.
178//
179// Struct fields are only marshalled if they are exported (have an upper case
180// first letter), and are marshalled using the field name lowercased as the
181// default key. Custom keys may be defined via the "yaml" name in the field
182// tag: the content preceding the first comma is used as the key, and the
183// following comma-separated options are used to tweak the marshalling process.
184// Conflicting names result in a runtime error.
185//
186// The field tag format accepted is:
187//
188// `(...) yaml:"[<key>][,<flag1>[,<flag2>]]" (...)`
189//
190// The following flags are currently supported:
191//
192// omitempty Only include the field if it's not set to the zero
193// value for the type or to empty slices or maps.
194// Zero valued structs will be omitted if all their public
195// fields are zero, unless they implement an IsZero
196// method (see the IsZeroer interface type), in which
197// case the field will be excluded if IsZero returns true.
198//
199// flow Marshal using a flow style (useful for structs,
200// sequences and maps).
201//
202// inline Inline the field, which must be a struct or a map,
203// causing all of its fields or keys to be processed as if
204// they were part of the outer struct. For maps, keys must
205// not conflict with the yaml keys of other struct fields.
206//
207// In addition, if the key is "-", the field is ignored.
208//
209// For example:
210//
211// type T struct {
212// F int `yaml:"a,omitempty"`
213// B int
214// }
215// yaml.Marshal(&T{B: 2}) // Returns "b: 2\n"
216// yaml.Marshal(&T{F: 1}} // Returns "a: 1\nb: 0\n"
217//
218func Marshal(in interface{}) (out []byte, err error) {
219 defer handleErr(&err)
220 e := newEncoder()
221 defer e.destroy()
222 e.marshalDoc("", reflect.ValueOf(in))
223 e.finish()
224 out = e.out
225 return
226}
227
228// An Encoder writes YAML values to an output stream.
229type Encoder struct {
230 encoder *encoder
231}
232
233// NewEncoder returns a new encoder that writes to w.
234// The Encoder should be closed after use to flush all data
235// to w.
236func NewEncoder(w io.Writer) *Encoder {
237 return &Encoder{
238 encoder: newEncoderWithWriter(w),
239 }
240}
241
242// Encode writes the YAML encoding of v to the stream.
243// If multiple items are encoded to the stream, the
244// second and subsequent document will be preceded
245// with a "---" document separator, but the first will not.
246//
247// See the documentation for Marshal for details about the conversion of Go
248// values to YAML.
249func (e *Encoder) Encode(v interface{}) (err error) {
250 defer handleErr(&err)
251 e.encoder.marshalDoc("", reflect.ValueOf(v))
252 return nil
253}
254
255// Encode encodes value v and stores its representation in n.
256//
257// See the documentation for Marshal for details about the
258// conversion of Go values into YAML.
259func (n *Node) Encode(v interface{}) (err error) {
260 defer handleErr(&err)
261 e := newEncoder()
262 defer e.destroy()
263 e.marshalDoc("", reflect.ValueOf(v))
264 e.finish()
265 p := newParser(e.out)
266 p.textless = true
267 defer p.destroy()
268 doc := p.parse()
269 *n = *doc.Content[0]
270 return nil
271}
272
273// SetIndent changes the used indentation used when encoding.
274func (e *Encoder) SetIndent(spaces int) {
275 if spaces < 0 {
276 panic("yaml: cannot indent to a negative number of spaces")
277 }
278 e.encoder.indent = spaces
279}
280
281// Close closes the encoder by writing any remaining data.
282// It does not write a stream terminating string "...".
283func (e *Encoder) Close() (err error) {
284 defer handleErr(&err)
285 e.encoder.finish()
286 return nil
287}
288
289func handleErr(err *error) {
290 if v := recover(); v != nil {
291 if e, ok := v.(yamlError); ok {
292 *err = e.err
293 } else {
294 panic(v)
295 }
296 }
297}
298
299type yamlError struct {
300 err error
301}
302
303func fail(err error) {
304 panic(yamlError{err})
305}
306
307func failf(format string, args ...interface{}) {
308 panic(yamlError{fmt.Errorf("yaml: "+format, args...)})
309}
310
311// A TypeError is returned by Unmarshal when one or more fields in
312// the YAML document cannot be properly decoded into the requested
313// types. When this error is returned, the value is still
314// unmarshaled partially.
315type TypeError struct {
316 Errors []string
317}
318
319func (e *TypeError) Error() string {
320 return fmt.Sprintf("yaml: unmarshal errors:\n %s", strings.Join(e.Errors, "\n "))
321}
322
323type Kind uint32
324
325const (
326 DocumentNode Kind = 1 << iota
327 SequenceNode
328 MappingNode
329 ScalarNode
330 AliasNode
331)
332
333type Style uint32
334
335const (
336 TaggedStyle Style = 1 << iota
337 DoubleQuotedStyle
338 SingleQuotedStyle
339 LiteralStyle
340 FoldedStyle
341 FlowStyle
342)
343
344// Node represents an element in the YAML document hierarchy. While documents
345// are typically encoded and decoded into higher level types, such as structs
346// and maps, Node is an intermediate representation that allows detailed
347// control over the content being decoded or encoded.
348//
349// It's worth noting that although Node offers access into details such as
350// line numbers, colums, and comments, the content when re-encoded will not
351// have its original textual representation preserved. An effort is made to
352// render the data plesantly, and to preserve comments near the data they
353// describe, though.
354//
355// Values that make use of the Node type interact with the yaml package in the
356// same way any other type would do, by encoding and decoding yaml data
357// directly or indirectly into them.
358//
359// For example:
360//
361// var person struct {
362// Name string
363// Address yaml.Node
364// }
365// err := yaml.Unmarshal(data, &person)
366//
367// Or by itself:
368//
369// var person Node
370// err := yaml.Unmarshal(data, &person)
371//
372type Node struct {
373 // Kind defines whether the node is a document, a mapping, a sequence,
374 // a scalar value, or an alias to another node. The specific data type of
375 // scalar nodes may be obtained via the ShortTag and LongTag methods.
376 Kind Kind
377
378 // Style allows customizing the apperance of the node in the tree.
379 Style Style
380
381 // Tag holds the YAML tag defining the data type for the value.
382 // When decoding, this field will always be set to the resolved tag,
383 // even when it wasn't explicitly provided in the YAML content.
384 // When encoding, if this field is unset the value type will be
385 // implied from the node properties, and if it is set, it will only
386 // be serialized into the representation if TaggedStyle is used or
387 // the implicit tag diverges from the provided one.
388 Tag string
389
390 // Value holds the unescaped and unquoted represenation of the value.
391 Value string
392
393 // Anchor holds the anchor name for this node, which allows aliases to point to it.
394 Anchor string
395
396 // Alias holds the node that this alias points to. Only valid when Kind is AliasNode.
397 Alias *Node
398
399 // Content holds contained nodes for documents, mappings, and sequences.
400 Content []*Node
401
402 // HeadComment holds any comments in the lines preceding the node and
403 // not separated by an empty line.
404 HeadComment string
405
406 // LineComment holds any comments at the end of the line where the node is in.
407 LineComment string
408
409 // FootComment holds any comments following the node and before empty lines.
410 FootComment string
411
412 // Line and Column hold the node position in the decoded YAML text.
413 // These fields are not respected when encoding the node.
414 Line int
415 Column int
416}
417
418// IsZero returns whether the node has all of its fields unset.
419func (n *Node) IsZero() bool {
420 return n.Kind == 0 && n.Style == 0 && n.Tag == "" && n.Value == "" && n.Anchor == "" && n.Alias == nil && n.Content == nil &&
421 n.HeadComment == "" && n.LineComment == "" && n.FootComment == "" && n.Line == 0 && n.Column == 0
422}
423
424
425// LongTag returns the long form of the tag that indicates the data type for
426// the node. If the Tag field isn't explicitly defined, one will be computed
427// based on the node properties.
428func (n *Node) LongTag() string {
429 return longTag(n.ShortTag())
430}
431
432// ShortTag returns the short form of the YAML tag that indicates data type for
433// the node. If the Tag field isn't explicitly defined, one will be computed
434// based on the node properties.
435func (n *Node) ShortTag() string {
436 if n.indicatedString() {
437 return strTag
438 }
439 if n.Tag == "" || n.Tag == "!" {
440 switch n.Kind {
441 case MappingNode:
442 return mapTag
443 case SequenceNode:
444 return seqTag
445 case AliasNode:
446 if n.Alias != nil {
447 return n.Alias.ShortTag()
448 }
449 case ScalarNode:
450 tag, _ := resolve("", n.Value)
451 return tag
452 case 0:
453 // Special case to make the zero value convenient.
454 if n.IsZero() {
455 return nullTag
456 }
457 }
458 return ""
459 }
460 return shortTag(n.Tag)
461}
462
463func (n *Node) indicatedString() bool {
464 return n.Kind == ScalarNode &&
465 (shortTag(n.Tag) == strTag ||
466 (n.Tag == "" || n.Tag == "!") && n.Style&(SingleQuotedStyle|DoubleQuotedStyle|LiteralStyle|FoldedStyle) != 0)
467}
468
469// SetString is a convenience function that sets the node to a string value
470// and defines its style in a pleasant way depending on its content.
471func (n *Node) SetString(s string) {
472 n.Kind = ScalarNode
473 if utf8.ValidString(s) {
474 n.Value = s
475 n.Tag = strTag
476 } else {
477 n.Value = encodeBase64(s)
478 n.Tag = binaryTag
479 }
480 if strings.Contains(n.Value, "\n") {
481 n.Style = LiteralStyle
482 }
483}
484
485// --------------------------------------------------------------------------
486// Maintain a mapping of keys to structure field indexes
487
488// The code in this section was copied from mgo/bson.
489
490// structInfo holds details for the serialization of fields of
491// a given struct.
492type structInfo struct {
493 FieldsMap map[string]fieldInfo
494 FieldsList []fieldInfo
495
496 // InlineMap is the number of the field in the struct that
497 // contains an ,inline map, or -1 if there's none.
498 InlineMap int
499
500 // InlineUnmarshalers holds indexes to inlined fields that
501 // contain unmarshaler values.
502 InlineUnmarshalers [][]int
503}
504
505type fieldInfo struct {
506 Key string
507 Num int
508 OmitEmpty bool
509 Flow bool
510 // Id holds the unique field identifier, so we can cheaply
511 // check for field duplicates without maintaining an extra map.
512 Id int
513
514 // Inline holds the field index if the field is part of an inlined struct.
515 Inline []int
516}
517
518var structMap = make(map[reflect.Type]*structInfo)
519var fieldMapMutex sync.RWMutex
520var unmarshalerType reflect.Type
521
522func init() {
523 var v Unmarshaler
524 unmarshalerType = reflect.ValueOf(&v).Elem().Type()
525}
526
527func getStructInfo(st reflect.Type) (*structInfo, error) {
528 fieldMapMutex.RLock()
529 sinfo, found := structMap[st]
530 fieldMapMutex.RUnlock()
531 if found {
532 return sinfo, nil
533 }
534
535 n := st.NumField()
536 fieldsMap := make(map[string]fieldInfo)
537 fieldsList := make([]fieldInfo, 0, n)
538 inlineMap := -1
539 inlineUnmarshalers := [][]int(nil)
540 for i := 0; i != n; i++ {
541 field := st.Field(i)
542 if field.PkgPath != "" && !field.Anonymous {
543 continue // Private field
544 }
545
546 info := fieldInfo{Num: i}
547
548 tag := field.Tag.Get("yaml")
549 if tag == "" && strings.Index(string(field.Tag), ":") < 0 {
550 tag = string(field.Tag)
551 }
552 if tag == "-" {
553 continue
554 }
555
556 inline := false
557 fields := strings.Split(tag, ",")
558 if len(fields) > 1 {
559 for _, flag := range fields[1:] {
560 switch flag {
561 case "omitempty":
562 info.OmitEmpty = true
563 case "flow":
564 info.Flow = true
565 case "inline":
566 inline = true
567 default:
568 return nil, errors.New(fmt.Sprintf("unsupported flag %q in tag %q of type %s", flag, tag, st))
569 }
570 }
571 tag = fields[0]
572 }
573
574 if inline {
575 switch field.Type.Kind() {
576 case reflect.Map:
577 if inlineMap >= 0 {
578 return nil, errors.New("multiple ,inline maps in struct " + st.String())
579 }
580 if field.Type.Key() != reflect.TypeOf("") {
581 return nil, errors.New("option ,inline needs a map with string keys in struct " + st.String())
582 }
583 inlineMap = info.Num
584 case reflect.Struct, reflect.Ptr:
585 ftype := field.Type
586 for ftype.Kind() == reflect.Ptr {
587 ftype = ftype.Elem()
588 }
589 if ftype.Kind() != reflect.Struct {
590 return nil, errors.New("option ,inline may only be used on a struct or map field")
591 }
592 if reflect.PtrTo(ftype).Implements(unmarshalerType) {
593 inlineUnmarshalers = append(inlineUnmarshalers, []int{i})
594 } else {
595 sinfo, err := getStructInfo(ftype)
596 if err != nil {
597 return nil, err
598 }
599 for _, index := range sinfo.InlineUnmarshalers {
600 inlineUnmarshalers = append(inlineUnmarshalers, append([]int{i}, index...))
601 }
602 for _, finfo := range sinfo.FieldsList {
603 if _, found := fieldsMap[finfo.Key]; found {
604 msg := "duplicated key '" + finfo.Key + "' in struct " + st.String()
605 return nil, errors.New(msg)
606 }
607 if finfo.Inline == nil {
608 finfo.Inline = []int{i, finfo.Num}
609 } else {
610 finfo.Inline = append([]int{i}, finfo.Inline...)
611 }
612 finfo.Id = len(fieldsList)
613 fieldsMap[finfo.Key] = finfo
614 fieldsList = append(fieldsList, finfo)
615 }
616 }
617 default:
618 return nil, errors.New("option ,inline may only be used on a struct or map field")
619 }
620 continue
621 }
622
623 if tag != "" {
624 info.Key = tag
625 } else {
626 info.Key = strings.ToLower(field.Name)
627 }
628
629 if _, found = fieldsMap[info.Key]; found {
630 msg := "duplicated key '" + info.Key + "' in struct " + st.String()
631 return nil, errors.New(msg)
632 }
633
634 info.Id = len(fieldsList)
635 fieldsList = append(fieldsList, info)
636 fieldsMap[info.Key] = info
637 }
638
639 sinfo = &structInfo{
640 FieldsMap: fieldsMap,
641 FieldsList: fieldsList,
642 InlineMap: inlineMap,
643 InlineUnmarshalers: inlineUnmarshalers,
644 }
645
646 fieldMapMutex.Lock()
647 structMap[st] = sinfo
648 fieldMapMutex.Unlock()
649 return sinfo, nil
650}
651
652// IsZeroer is used to check whether an object is zero to
653// determine whether it should be omitted when marshaling
654// with the omitempty flag. One notable implementation
655// is time.Time.
656type IsZeroer interface {
657 IsZero() bool
658}
659
660func isZero(v reflect.Value) bool {
661 kind := v.Kind()
662 if z, ok := v.Interface().(IsZeroer); ok {
663 if (kind == reflect.Ptr || kind == reflect.Interface) && v.IsNil() {
664 return true
665 }
666 return z.IsZero()
667 }
668 switch kind {
669 case reflect.String:
670 return len(v.String()) == 0
671 case reflect.Interface, reflect.Ptr:
672 return v.IsNil()
673 case reflect.Slice:
674 return v.Len() == 0
675 case reflect.Map:
676 return v.Len() == 0
677 case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
678 return v.Int() == 0
679 case reflect.Float32, reflect.Float64:
680 return v.Float() == 0
681 case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
682 return v.Uint() == 0
683 case reflect.Bool:
684 return !v.Bool()
685 case reflect.Struct:
686 vt := v.Type()
687 for i := v.NumField() - 1; i >= 0; i-- {
688 if vt.Field(i).PkgPath != "" {
689 continue // Private field
690 }
691 if !isZero(v.Field(i)) {
692 return false
693 }
694 }
695 return true
696 }
697 return false
698}