README.md
1# YAML support for the Go language
2
3Introduction
4------------
5
6The yaml package enables Go programs to comfortably encode and decode YAML
7values. It was developed within [Canonical](https://www.canonical.com) as
8part of the [juju](https://juju.ubuntu.com) project, and is based on a
9pure Go port of the well-known [libyaml](http://pyyaml.org/wiki/LibYAML)
10C library to parse and generate YAML data quickly and reliably.
11
12Compatibility
13-------------
14
15The yaml package supports most of YAML 1.1 and 1.2, including support for
16anchors, tags, map merging, etc. Multi-document unmarshalling is not yet
17implemented, and base-60 floats from YAML 1.1 are purposefully not
18supported since they're a poor design and are gone in YAML 1.2.
19
20Installation and usage
21----------------------
22
23The import path for the package is *gopkg.in/yaml.v2*.
24
25To install it, run:
26
27 go get gopkg.in/yaml.v2
28
29API documentation
30-----------------
31
32If opened in a browser, the import path itself leads to the API documentation:
33
34 * [https://gopkg.in/yaml.v2](https://gopkg.in/yaml.v2)
35
36API stability
37-------------
38
39The package API for yaml v2 will remain stable as described in [gopkg.in](https://gopkg.in).
40
41
42License
43-------
44
45The yaml package is licensed under the Apache License 2.0. Please see the LICENSE file for details.
46
47
48Example
49-------
50
51Some more examples can be found in the "examples" folder.
52
53```Go
54package main
55
56import (
57 "fmt"
58 "log"
59
60 "gopkg.in/yaml.v2"
61)
62
63var data = `
64a: Easy!
65b:
66 c: 2
67 d: [3, 4]
68`
69
70// Note: struct fields must be public in order for unmarshal to
71// correctly populate the data.
72type T struct {
73 A string
74 B struct {
75 RenamedC int `yaml:"c"`
76 D []int `yaml:",flow"`
77 }
78}
79
80func main() {
81 t := T{}
82
83 err := yaml.Unmarshal([]byte(data), &t)
84 if err != nil {
85 log.Fatalf("error: %v", err)
86 }
87 fmt.Printf("--- t:\n%v\n\n", t)
88
89 d, err := yaml.Marshal(&t)
90 if err != nil {
91 log.Fatalf("error: %v", err)
92 }
93 fmt.Printf("--- t dump:\n%s\n\n", string(d))
94
95 m := make(map[interface{}]interface{})
96
97 err = yaml.Unmarshal([]byte(data), &m)
98 if err != nil {
99 log.Fatalf("error: %v", err)
100 }
101 fmt.Printf("--- m:\n%v\n\n", m)
102
103 d, err = yaml.Marshal(&m)
104 if err != nil {
105 log.Fatalf("error: %v", err)
106 }
107 fmt.Printf("--- m dump:\n%s\n\n", string(d))
108}
109```
110
111This example will generate the following output:
112
113```
114--- t:
115{Easy! {2 [3 4]}}
116
117--- t dump:
118a: Easy!
119b:
120 c: 2
121 d: [3, 4]
122
123
124--- m:
125map[a:Easy! b:map[c:2 d:[3 4]]]
126
127--- m dump:
128a: Easy!
129b:
130 c: 2
131 d:
132 - 3
133 - 4
134```
135
136