goyaml

Documentation

Overview

Package goyaml implements YAML support for the Go language.

Index

• func Marshal(in interface{}) (out []byte, err error)
• func Unmarshal(in []byte, out interface{}) (err error)
• type Getter
• type Setter

Functions

func Marshal

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

Marshal serializes the value provided into a YAML document. The structure of the generated document will reflect the structure of the value itself. Maps, pointers to structs and ints, etc, may all be used as the in value.

In the case of struct values, only exported fields will be serialized. The lowercased field name is used as the key for each exported field, but this behavior may be changed using the respective field tag. The tag may also contain flags to tweak the marshalling behavior for the field. Conflicting names result in a runtime error. The 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.
             Does not apply to zero valued structs.

flow         Marshal using a flow style (useful for structs,
             sequences and maps.

inline       Inline the struct it's applied to, so its fields
             are processed as if they were part of the outer
             struct.

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

For example:

type T struct {
    F int "a,omitempty"
    B int
}
goyaml.Marshal(&T{B: 2}) // Returns "b: 2\n"
goyaml.Marshal(&T{F: 1}} // Returns "a: 1\nb: 0\n"

func Unmarshal

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

Unmarshal decodes the first document found within the in byte slice and assigns decoded values into the object pointed by out.

Maps, pointers to structs and ints, etc, may all be used as out values. If an internal pointer within a struct is not initialized, goyaml will initialize it if necessary for unmarshalling the provided data, but the struct provided as out must not be a nil pointer.

The type of the decoded values and the type of out will be considered, and Unmarshal() will do the best possible job to unmarshal values appropriately. It is NOT considered an error, though, to skip values because they are not available in the decoded YAML, or if they are not compatible with the out value. To ensure something was properly unmarshaled use a map or compare against the previous value for the field (usually the zero value).

Struct fields are only unmarshalled if they are exported (have an upper case first letter), and will be unmarshalled using the field name lowercased by default. When custom field names are desired, the tag value may be used to tweak the name. Everything before the first comma in the field tag will be used as the name. The values following the comma 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
goyaml.Unmarshal([]byte("a: 1\nb: 2"), &t)

See the documentation of Marshal for the format of tags and a list of supported tag options.

Types

type Getter

type Getter interface {
	GetYAML() (tag string, value interface{})
}

Objects implementing the goyaml.Getter interface will get the GetYAML() method called when goyaml is requested to marshal the given value, and the result of this method will be marshaled in place of the actual object.

type Setter

type Setter interface {
	SetYAML(tag string, value interface{}) bool
}

Objects implementing the goyaml.Setter interface will receive the YAML tag and value via the SetYAML method during unmarshaling, rather than being implicitly assigned by the goyaml machinery. If setting the value works, the method should return true. If it returns false, the given value will be omitted from maps and slices.