encoding: github.com/gopkg/encoding/yaml Index | Examples | Files

package yaml

import "github.com/gopkg/encoding/yaml"

Package yaml implements YAML support.

Examples:

func main() {
	var m map[interface{}]interface{}
	err := yaml.Unmarshal([]byte(`... yaml data ...`), &m)
	if err != nil {
		log.Fatalf("error: %v", err)
	}
	d, err := yaml.Marshal(m)
	if err != nil {
		log.Fatalf("error: %v", err)
	}
}

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

https://github.com/chai2010/yaml

Index

Examples

Package Files

apic.go decode.go doc.go emitterc.go encode.go parserc.go readerc.go resolve.go scannerc.go sorter.go writerc.go yaml.go yamlh.go yamlprivateh.go

func Marshal Uses

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 and pointers (to struct, string, int, etc) are accepted as the in value.

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. 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.
             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
}
yaml.Marshal(&T{B: 2}) // Returns "b: 2\n"
yaml.Marshal(&T{F: 1}) // Returns "a: 1\nb: 0\n"

Code:

type T struct {
    A   string
    B   struct {
        C   int
        D   []int ",flow"
    }
}

var t T
t.A = "Easy!"
t.B.C = 2
t.B.D = []int{3, 4}

d, err := yaml.Marshal(t)
if err != nil {
    log.Fatalf("error: %v", err)
}
fmt.Printf("%s", string(d))

Output:

a: Easy!
b:
  c: 2
  d: [3, 4]

Code:

m := map[interface{}]interface{}{
    "a": "Easy!",
    "b": map[interface{}]interface{}{
        "c": 2,
        "d": []int{3, 4},
    },
}

d, err := yaml.Marshal(m)
if err != nil {
    log.Fatalf("error: %v", err)
}
fmt.Printf("%s", string(d))

Output:

a: Easy!
b:
  c: 2
  d:
  - 3
  - 4

func Unmarshal Uses

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 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 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 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.

Code:

const data = `
a: Easy!
b:
  c: 2
  d: [3, 4]
`

var t struct {
    A   string
    B   struct {
        C   int
        D   []int ",flow"
    }
}
err := yaml.Unmarshal([]byte(data), &t)
if err != nil {
    log.Fatalf("error: %v", err)
}
fmt.Printf("%v", t)

Output:

{Easy! {2 [3 4]}}

Code:

const data = `
a: Easy!
b:
  c: 2
  d: [3, 4]
`

var m map[interface{}]interface{}
err := yaml.Unmarshal([]byte(data), &m)
if err != nil {
    log.Fatalf("error: %v", err)
}
fmt.Printf("a: %v\n", m["a"])
fmt.Printf("b/c: %v\n", m["b"].(map[interface{}]interface{})["c"])
fmt.Printf("b/d: %v\n", m["b"].(map[interface{}]interface{})["d"])

Output:

a: Easy!
b/c: 2
b/d: [3 4]

type Getter Uses

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

The Getter interface is implemented by types to do their own custom marshalling into a YAML tag and value.

type Setter Uses

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

The Setter interface may be implemented by types to do their own custom unmarshalling of YAML values, rather than being implicitly assigned by the yaml package machinery. If setting the value works, the method should return true. If it returns false, the value is considered unsupported and is omitted from maps and slices.

Package yaml imports 14 packages (graph). Updated 2016-07-16. Refresh now. Tools for package owners. This is an inactive package (no imports and no commits in at least two years).