1
//
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
//
22
package yaml
23

24
import (
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.
36
type Unmarshaler interface {
37
	UnmarshalYAML(value *Node) error
38
}
39

40
type 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.
50
type 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
//
88
func 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.
93
type 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.
102
func 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.
110
func (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.
119
func (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.
142
func (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

156
func 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
//
218
func 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.
229
type 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.
236
func 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.
249
func (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.
259
func (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.
274
func (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 "...".
283
func (e *Encoder) Close() (err error) {
284
	defer handleErr(&err)
285
	e.encoder.finish()
286
	return nil
287
}
288

289
func 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

299
type yamlError struct {
300
	err error
301
}
302

303
func fail(err error) {
304
	panic(yamlError{err})
305
}
306

307
func 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.
315
type TypeError struct {
316
	Errors []string
317
}
318

319
func (e *TypeError) Error() string {
320
	return fmt.Sprintf("yaml: unmarshal errors:\n  %s", strings.Join(e.Errors, "\n  "))
321
}
322

323
type Kind uint32
324

325
const (
326
	DocumentNode Kind = 1 << iota
327
	SequenceNode
328
	MappingNode
329
	ScalarNode
330
	AliasNode
331
)
332

333
type Style uint32
334

335
const (
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
//
372
type 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.
419
func (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.
428
func (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.
435
func (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

463
func (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.
471
func (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.
492
type 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

505
type 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

518
var structMap = make(map[reflect.Type]*structInfo)
519
var fieldMapMutex sync.RWMutex
520
var unmarshalerType reflect.Type
521

522
func init() {
523
	var v Unmarshaler
524
	unmarshalerType = reflect.ValueOf(&v).Elem().Type()
525
}
526

527
func 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.
656
type IsZeroer interface {
657
	IsZero() bool
658
}
659

660
func 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
}
699

700