|
66
|
1 // 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 //
|
|
|
7 package yaml
|
|
|
8
|
|
|
9 import (
|
|
|
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.
|
|
|
20 type MapSlice []MapItem
|
|
|
21
|
|
|
22 // MapItem is an item in a MapSlice.
|
|
|
23 type 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.
|
|
|
32 type 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.
|
|
|
42 type 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 //
|
|
|
80 func 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.
|
|
|
88 func 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.
|
|
|
93 type 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.
|
|
|
102 func 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.
|
|
|
110 func (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.
|
|
|
119 func (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
|
|
|
137 func 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
|
|
|
178 // case the field will be excluded if IsZero returns true.
|
|
|
179 //
|
|
|
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 //
|
|
|
199 func 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.
|
|
|
210 type 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.
|
|
|
217 func 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.
|
|
|
230 func (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 "...".
|
|
|
238 func (e *Encoder) Close() (err error) {
|
|
|
239 defer handleErr(&err)
|
|
|
240 e.encoder.finish()
|
|
|
241 return nil
|
|
|
242 }
|
|
|
243
|
|
|
244 func 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
|
|
|
254 type yamlError struct {
|
|
|
255 err error
|
|
|
256 }
|
|
|
257
|
|
|
258 func fail(err error) {
|
|
|
259 panic(yamlError{err})
|
|
|
260 }
|
|
|
261
|
|
|
262 func 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.
|
|
|
270 type TypeError struct {
|
|
|
271 Errors []string
|
|
|
272 }
|
|
|
273
|
|
|
274 func (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.
|
|
|
285 type 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
|
|
|
294 type 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
|
|
|
307 var structMap = make(map[reflect.Type]*structInfo)
|
|
|
308 var fieldMapMutex sync.RWMutex
|
|
|
309
|
|
|
310 func 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.
|
|
|
424 type IsZeroer interface {
|
|
|
425 IsZero() bool
|
|
|
426 }
|
|
|
427
|
|
|
428 func 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 }
|
|
|
467
|
|
|
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.
|
|
|
476 func FutureLineWrap() {
|
|
|
477 disableLineWrapping = true
|
|
|
478 }
|
