niki/vendor/gopkg.in/yaml.v3/yaml.go

//

// Copyright (c) 2011-2019 Canonical Ltd

//

// Licensed under the Apache License, Version 2.0 (the "License");

// you may not use this file except in compliance with the License.

// You may obtain a copy of the License at

//

//     http://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing, software

// distributed under the License is distributed on an "AS IS" BASIS,

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

// See the License for the specific language governing permissions and

// limitations under the License.

// Package yaml implements YAML support for the Go language.

//

// Source code and other details for the project are available at GitHub:

//

//	https://github.com/go-yaml/yaml

package yaml

import (
	"errors"
	"fmt"
	"io"
	"reflect"
	"strings"
	"sync"
	"unicode/utf8"
)

// The Unmarshaler interface may be implemented by types to customize their

// behavior when being unmarshaled from a YAML document.

type Unmarshaler interface {
	UnmarshalYAML(value *Node) error
}

type obsoleteUnmarshaler interface {
	UnmarshalYAML(unmarshal func(interface{}) error) error
}

// The Marshaler interface may be implemented by types to customize their

// behavior when being marshaled into a YAML document. The returned value

// is marshaled in place of the original value implementing Marshaler.

//

// If an error is returned by MarshalYAML, the marshaling procedure stops

// and returns with the provided error.

type Marshaler interface {
	MarshalYAML() (interface{}, error)
}

// Unmarshal decodes the first document found within the in byte slice

// and assigns decoded values into the out value.

//

// Maps and pointers (to a struct, string, int, etc) are accepted as out

// values. If an internal pointer within a struct is not initialized,

// the yaml package will initialize it if necessary for unmarshalling

// the provided data. The out parameter must not be nil.

//

// The type of the decoded values should be compatible with the respective

// values in out. If one or more values cannot be decoded due to a type

// mismatches, decoding continues partially until the end of the YAML

// content, and a *yaml.TypeError is returned with details for all

// missed values.

//

// Struct fields are only unmarshalled if they are exported (have an

// upper case first letter), and are unmarshalled using the field name

// lowercased as the default key. Custom keys may be defined via the

// "yaml" name in the field tag: the content preceding the first comma

// is used as the key, and the following comma-separated options are

// used to tweak the marshalling process (see Marshal).

// Conflicting names result in a runtime error.

//

// For example:

//

//	type T struct {

//	    F int `yaml:"a,omitempty"`

//	    B int

//	}

//	var t T

//	yaml.Unmarshal([]byte("a: 1\nb: 2"), &t)

//

// See the documentation of Marshal for the format of tags and a list of

// supported tag options.

func Unmarshal(in []byte, out interface{}) (err error) {

	return unmarshal(in, out, false)

}

// A Decoder reads and decodes YAML values from an input stream.

type Decoder struct {
	parser *parser

	knownFields bool
}

// NewDecoder returns a new decoder that reads from r.

//

// The decoder introduces its own buffering and may read

// data from r beyond the YAML values requested.

func NewDecoder(r io.Reader) *Decoder {

	return &Decoder{

		parser: newParserFromReader(r),
	}

}

// KnownFields ensures that the keys in decoded mappings to

// exist as fields in the struct being decoded into.

func (dec *Decoder) KnownFields(enable bool) {

	dec.knownFields = enable

}

// Decode reads the next YAML-encoded value from its input

// and stores it in the value pointed to by v.

//

// See the documentation for Unmarshal for details about the

// conversion of YAML into a Go value.

func (dec *Decoder) Decode(v interface{}) (err error) {

	d := newDecoder()

	d.knownFields = dec.knownFields

	defer handleErr(&err)

	node := dec.parser.parse()

	if node == nil {

		return io.EOF

	}

	out := reflect.ValueOf(v)

	if out.Kind() == reflect.Ptr && !out.IsNil() {

		out = out.Elem()

	}

	d.unmarshal(node, out)

	if len(d.terrors) > 0 {

		return &TypeError{d.terrors}

	}

	return nil

}

// Decode decodes the node and stores its data into the value pointed to by v.

//

// See the documentation for Unmarshal for details about the

// conversion of YAML into a Go value.

func (n *Node) Decode(v interface{}) (err error) {

	d := newDecoder()

	defer handleErr(&err)

	out := reflect.ValueOf(v)

	if out.Kind() == reflect.Ptr && !out.IsNil() {

		out = out.Elem()

	}

	d.unmarshal(n, out)

	if len(d.terrors) > 0 {

		return &TypeError{d.terrors}

	}

	return nil

}

func unmarshal(in []byte, out interface{}, strict bool) (err error) {

	defer handleErr(&err)

	d := newDecoder()

	p := newParser(in)

	defer p.destroy()

	node := p.parse()

	if node != nil {

		v := reflect.ValueOf(out)

		if v.Kind() == reflect.Ptr && !v.IsNil() {

			v = v.Elem()

		}

		d.unmarshal(node, v)

	}

	if len(d.terrors) > 0 {

		return &TypeError{d.terrors}

	}

	return nil

}

// Marshal serializes the value provided into a YAML document. The structure

// of the generated document will reflect the structure of the value itself.

// Maps and pointers (to struct, string, int, etc) are accepted as the in value.

//

// Struct fields are only marshalled if they are exported (have an upper case

// first letter), and are marshalled using the field name lowercased as the

// default key. Custom keys may be defined via the "yaml" name in the field

// tag: the content preceding the first comma is used as the key, and the

// following comma-separated options are used to tweak the marshalling process.

// Conflicting names result in a runtime error.

//

// The field tag format accepted is:

//

//	`(...) yaml:"[<key>][,<flag1>[,<flag2>]]" (...)`

//

// The following flags are currently supported:

//

//	omitempty    Only include the field if it's not set to the zero

//	             value for the type or to empty slices or maps.

//	             Zero valued structs will be omitted if all their public

//	             fields are zero, unless they implement an IsZero

//	             method (see the IsZeroer interface type), in which

//	             case the field will be excluded if IsZero returns true.

//

//	flow         Marshal using a flow style (useful for structs,

//	             sequences and maps).

//

//	inline       Inline the field, which must be a struct or a map,

//	             causing all of its fields or keys to be processed as if

//	             they were part of the outer struct. For maps, keys must

//	             not conflict with the yaml keys of other struct fields.

//

// In addition, if the key is "-", the field is ignored.

//

// For example:

//

//	type T struct {

//	    F int `yaml:"a,omitempty"`

//	    B int

//	}

//	yaml.Marshal(&T{B: 2}) // Returns "b: 2\n"

//	yaml.Marshal(&T{F: 1}} // Returns "a: 1\nb: 0\n"

func Marshal(in interface{}) (out []byte, err error) {

	defer handleErr(&err)

	e := newEncoder()

	defer e.destroy()

	e.marshalDoc("", reflect.ValueOf(in))

	e.finish()

	out = e.out

	return

}

// An Encoder writes YAML values to an output stream.

type Encoder struct {
	encoder *encoder
}

// NewEncoder returns a new encoder that writes to w.

// The Encoder should be closed after use to flush all data

// to w.

func NewEncoder(w io.Writer) *Encoder {

	return &Encoder{

		encoder: newEncoderWithWriter(w),
	}

}

// Encode writes the YAML encoding of v to the stream.

// If multiple items are encoded to the stream, the

// second and subsequent document will be preceded

// with a "---" document separator, but the first will not.

//

// See the documentation for Marshal for details about the conversion of Go

// values to YAML.

func (e *Encoder) Encode(v interface{}) (err error) {

	defer handleErr(&err)

	e.encoder.marshalDoc("", reflect.ValueOf(v))

	return nil

}

// Encode encodes value v and stores its representation in n.

//

// See the documentation for Marshal for details about the

// conversion of Go values into YAML.

func (n *Node) Encode(v interface{}) (err error) {

	defer handleErr(&err)

	e := newEncoder()

	defer e.destroy()

	e.marshalDoc("", reflect.ValueOf(v))

	e.finish()

	p := newParser(e.out)

	p.textless = true

	defer p.destroy()

	doc := p.parse()

	*n = *doc.Content[0]

	return nil

}

// SetIndent changes the used indentation used when encoding.

func (e *Encoder) SetIndent(spaces int) {

	if spaces < 0 {

		panic("yaml: cannot indent to a negative number of spaces")

	}

	e.encoder.indent = spaces

}

// Close closes the encoder by writing any remaining data.

// It does not write a stream terminating string "...".

func (e *Encoder) Close() (err error) {

	defer handleErr(&err)

	e.encoder.finish()

	return nil

}

func handleErr(err *error) {

	if v := recover(); v != nil {

		if e, ok := v.(yamlError); ok {

			*err = e.err

		} else {

			panic(v)

		}

	}

}

type yamlError struct {
	err error
}

func fail(err error) {

	panic(yamlError{err})

}

func failf(format string, args ...interface{}) {

	panic(yamlError{fmt.Errorf("yaml: "+format, args...)})

}

// A TypeError is returned by Unmarshal when one or more fields in

// the YAML document cannot be properly decoded into the requested

// types. When this error is returned, the value is still

// unmarshaled partially.

type TypeError struct {
	Errors []string
}

func (e *TypeError) Error() string {

	return fmt.Sprintf("yaml: unmarshal errors:\n  %s", strings.Join(e.Errors, "\n  "))

}

type Kind uint32

const (
	DocumentNode Kind = 1 << iota

	SequenceNode

	MappingNode

	ScalarNode

	AliasNode
)

type Style uint32

const (
	TaggedStyle Style = 1 << iota

	DoubleQuotedStyle

	SingleQuotedStyle

	LiteralStyle

	FoldedStyle

	FlowStyle
)

// Node represents an element in the YAML document hierarchy. While documents

// are typically encoded and decoded into higher level types, such as structs

// and maps, Node is an intermediate representation that allows detailed

// control over the content being decoded or encoded.

//

// It's worth noting that although Node offers access into details such as

// line numbers, colums, and comments, the content when re-encoded will not

// have its original textual representation preserved. An effort is made to

// render the data plesantly, and to preserve comments near the data they

// describe, though.

//

// Values that make use of the Node type interact with the yaml package in the

// same way any other type would do, by encoding and decoding yaml data

// directly or indirectly into them.

//

// For example:

//

//	var person struct {

//	        Name    string

//	        Address yaml.Node

//	}

//	err := yaml.Unmarshal(data, &person)

//

// Or by itself:

//

//	var person Node

//	err := yaml.Unmarshal(data, &person)

type Node struct {

	// Kind defines whether the node is a document, a mapping, a sequence,

	// a scalar value, or an alias to another node. The specific data type of

	// scalar nodes may be obtained via the ShortTag and LongTag methods.

	Kind Kind

	// Style allows customizing the apperance of the node in the tree.

	Style Style

	// Tag holds the YAML tag defining the data type for the value.

	// When decoding, this field will always be set to the resolved tag,

	// even when it wasn't explicitly provided in the YAML content.

	// When encoding, if this field is unset the value type will be

	// implied from the node properties, and if it is set, it will only

	// be serialized into the representation if TaggedStyle is used or

	// the implicit tag diverges from the provided one.

	Tag string

	// Value holds the unescaped and unquoted represenation of the value.

	Value string

	// Anchor holds the anchor name for this node, which allows aliases to point to it.

	Anchor string

	// Alias holds the node that this alias points to. Only valid when Kind is AliasNode.

	Alias *Node

	// Content holds contained nodes for documents, mappings, and sequences.

	Content []*Node

	// HeadComment holds any comments in the lines preceding the node and

	// not separated by an empty line.

	HeadComment string

	// LineComment holds any comments at the end of the line where the node is in.

	LineComment string

	// FootComment holds any comments following the node and before empty lines.

	FootComment string

	// Line and Column hold the node position in the decoded YAML text.

	// These fields are not respected when encoding the node.

	Line int

	Column int
}

// IsZero returns whether the node has all of its fields unset.

func (n *Node) IsZero() bool {

	return n.Kind == 0 && n.Style == 0 && n.Tag == "" && n.Value == "" && n.Anchor == "" && n.Alias == nil && n.Content == nil &&

		n.HeadComment == "" && n.LineComment == "" && n.FootComment == "" && n.Line == 0 && n.Column == 0

}

// LongTag returns the long form of the tag that indicates the data type for

// the node. If the Tag field isn't explicitly defined, one will be computed

// based on the node properties.

func (n *Node) LongTag() string {

	return longTag(n.ShortTag())

}

// ShortTag returns the short form of the YAML tag that indicates data type for

// the node. If the Tag field isn't explicitly defined, one will be computed

// based on the node properties.

func (n *Node) ShortTag() string {

	if n.indicatedString() {

		return strTag

	}

	if n.Tag == "" || n.Tag == "!" {

		switch n.Kind {

		case MappingNode:

			return mapTag

		case SequenceNode:

			return seqTag

		case AliasNode:

			if n.Alias != nil {

				return n.Alias.ShortTag()

			}

		case ScalarNode:

			tag, _ := resolve("", n.Value)

			return tag

		case 0:

			// Special case to make the zero value convenient.

			if n.IsZero() {

				return nullTag

			}

		}

		return ""

	}

	return shortTag(n.Tag)

}

func (n *Node) indicatedString() bool {

	return n.Kind == ScalarNode &&

		(shortTag(n.Tag) == strTag ||

			(n.Tag == "" || n.Tag == "!") && n.Style&(SingleQuotedStyle|DoubleQuotedStyle|LiteralStyle|FoldedStyle) != 0)

}

// SetString is a convenience function that sets the node to a string value

// and defines its style in a pleasant way depending on its content.

func (n *Node) SetString(s string) {

	n.Kind = ScalarNode

	if utf8.ValidString(s) {

		n.Value = s

		n.Tag = strTag

	} else {

		n.Value = encodeBase64(s)

		n.Tag = binaryTag

	}

	if strings.Contains(n.Value, "\n") {

		n.Style = LiteralStyle

	}

}

// --------------------------------------------------------------------------

// Maintain a mapping of keys to structure field indexes

// The code in this section was copied from mgo/bson.

// structInfo holds details for the serialization of fields of

// a given struct.

type structInfo struct {
	FieldsMap map[string]fieldInfo

	FieldsList []fieldInfo

	// InlineMap is the number of the field in the struct that

	// contains an ,inline map, or -1 if there's none.

	InlineMap int

	// InlineUnmarshalers holds indexes to inlined fields that

	// contain unmarshaler values.

	InlineUnmarshalers [][]int
}

type fieldInfo struct {
	Key string

	Num int

	OmitEmpty bool

	Flow bool

	// Id holds the unique field identifier, so we can cheaply

	// check for field duplicates without maintaining an extra map.

	Id int

	// Inline holds the field index if the field is part of an inlined struct.

	Inline []int
}

var structMap = make(map[reflect.Type]*structInfo)

var fieldMapMutex sync.RWMutex

var unmarshalerType reflect.Type

func init() {

	var v Unmarshaler

	unmarshalerType = reflect.ValueOf(&v).Elem().Type()

}

func getStructInfo(st reflect.Type) (*structInfo, error) {

	fieldMapMutex.RLock()

	sinfo, found := structMap[st]

	fieldMapMutex.RUnlock()

	if found {

		return sinfo, nil

	}

	n := st.NumField()

	fieldsMap := make(map[string]fieldInfo)

	fieldsList := make([]fieldInfo, 0, n)

	inlineMap := -1

	inlineUnmarshalers := [][]int(nil)

	for i := 0; i != n; i++ {

		field := st.Field(i)

		if field.PkgPath != "" && !field.Anonymous {

			continue // Private field

		}

		info := fieldInfo{Num: i}

		tag := field.Tag.Get("yaml")

		if tag == "" && strings.Index(string(field.Tag), ":") < 0 {

			tag = string(field.Tag)

		}

		if tag == "-" {

			continue

		}

		inline := false

		fields := strings.Split(tag, ",")

		if len(fields) > 1 {

			for _, flag := range fields[1:] {

				switch flag {

				case "omitempty":

					info.OmitEmpty = true

				case "flow":

					info.Flow = true

				case "inline":

					inline = true

				default:

					return nil, errors.New(fmt.Sprintf("unsupported flag %q in tag %q of type %s", flag, tag, st))

				}

			}

			tag = fields[0]

		}

		if inline {

			switch field.Type.Kind() {

			case reflect.Map:

				if inlineMap >= 0 {

					return nil, errors.New("multiple ,inline maps in struct " + st.String())

				}

				if field.Type.Key() != reflect.TypeOf("") {

					return nil, errors.New("option ,inline needs a map with string keys in struct " + st.String())

				}

				inlineMap = info.Num

			case reflect.Struct, reflect.Ptr:

				ftype := field.Type

				for ftype.Kind() == reflect.Ptr {

					ftype = ftype.Elem()

				}

				if ftype.Kind() != reflect.Struct {

					return nil, errors.New("option ,inline may only be used on a struct or map field")

				}

				if reflect.PtrTo(ftype).Implements(unmarshalerType) {

					inlineUnmarshalers = append(inlineUnmarshalers, []int{i})

				} else {

					sinfo, err := getStructInfo(ftype)

					if err != nil {

						return nil, err

					}

					for _, index := range sinfo.InlineUnmarshalers {

						inlineUnmarshalers = append(inlineUnmarshalers, append([]int{i}, index...))

					}

					for _, finfo := range sinfo.FieldsList {

						if _, found := fieldsMap[finfo.Key]; found {

							msg := "duplicated key '" + finfo.Key + "' in struct " + st.String()

							return nil, errors.New(msg)

						}

						if finfo.Inline == nil {

							finfo.Inline = []int{i, finfo.Num}

						} else {

							finfo.Inline = append([]int{i}, finfo.Inline...)

						}

						finfo.Id = len(fieldsList)

						fieldsMap[finfo.Key] = finfo

						fieldsList = append(fieldsList, finfo)

					}

				}

			default:

				return nil, errors.New("option ,inline may only be used on a struct or map field")

			}

			continue

		}

		if tag != "" {

			info.Key = tag

		} else {

			info.Key = strings.ToLower(field.Name)

		}

		if _, found = fieldsMap[info.Key]; found {

			msg := "duplicated key '" + info.Key + "' in struct " + st.String()

			return nil, errors.New(msg)

		}

		info.Id = len(fieldsList)

		fieldsList = append(fieldsList, info)

		fieldsMap[info.Key] = info

	}

	sinfo = &structInfo{

		FieldsMap: fieldsMap,

		FieldsList: fieldsList,

		InlineMap: inlineMap,

		InlineUnmarshalers: inlineUnmarshalers,
	}

	fieldMapMutex.Lock()

	structMap[st] = sinfo

	fieldMapMutex.Unlock()

	return sinfo, nil

}

// IsZeroer is used to check whether an object is zero to

// determine whether it should be omitted when marshaling

// with the omitempty flag. One notable implementation

// is time.Time.

type IsZeroer interface {
	IsZero() bool
}

func isZero(v reflect.Value) bool {

	kind := v.Kind()

	if z, ok := v.Interface().(IsZeroer); ok {

		if (kind == reflect.Ptr || kind == reflect.Interface) && v.IsNil() {

			return true

		}

		return z.IsZero()

	}

	switch kind {

	case reflect.String:

		return len(v.String()) == 0

	case reflect.Interface, reflect.Ptr:

		return v.IsNil()

	case reflect.Slice:

		return v.Len() == 0

	case reflect.Map:

		return v.Len() == 0

	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:

		return v.Int() == 0

	case reflect.Float32, reflect.Float64:

		return v.Float() == 0

	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:

		return v.Uint() == 0

	case reflect.Bool:

		return !v.Bool()

	case reflect.Struct:

		vt := v.Type()

		for i := v.NumField() - 1; i >= 0; i-- {

			if vt.Field(i).PkgPath != "" {

				continue // Private field

			}

			if !isZero(v.Field(i)) {

				return false

			}

		}

		return true

	}

	return false

}