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.v1*.
24
25To install it, run:
26
27 go get gopkg.in/yaml.v1
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.v1](https://gopkg.in/yaml.v1)
35
36API stability
37-------------
38
39The package API for yaml v1 will remain stable as described in [gopkg.in](https://gopkg.in).
40
41
42License
43-------
44
45The yaml package is licensed under the LGPL with an exception that allows it to be linked statically. Please see the LICENSE file for details.
46
47
48Example
49-------
50
51```Go
52package main
53
54import (
55 "fmt"
56 "log"
57
58 "gopkg.in/yaml.v1"
59)
60
61var data = `
62a: Easy!
63b:
64 c: 2
65 d: [3, 4]
66`
67
68type T struct {
69 A string
70 B struct{C int; D []int ",flow"}
71}
72
73func main() {
74 t := T{}
75
76 err := yaml.Unmarshal([]byte(data), &t)
77 if err != nil {
78 log.Fatalf("error: %v", err)
79 }
80 fmt.Printf("--- t:\n%v\n\n", t)
81
82 d, err := yaml.Marshal(&t)
83 if err != nil {
84 log.Fatalf("error: %v", err)
85 }
86 fmt.Printf("--- t dump:\n%s\n\n", string(d))
87
88 m := make(map[interface{}]interface{})
89
90 err = yaml.Unmarshal([]byte(data), &m)
91 if err != nil {
92 log.Fatalf("error: %v", err)
93 }
94 fmt.Printf("--- m:\n%v\n\n", m)
95
96 d, err = yaml.Marshal(&m)
97 if err != nil {
98 log.Fatalf("error: %v", err)
99 }
100 fmt.Printf("--- m dump:\n%s\n\n", string(d))
101}
102```
103
104This example will generate the following output:
105
106```
107--- t:
108{Easy! {2 [3 4]}}
109
110--- t dump:
111a: Easy!
112b:
113 c: 2
114 d: [3, 4]
115
116
117--- m:
118map[a:Easy! b:map[c:2 d:[3 4]]]
119
120--- m dump:
121a: Easy!
122b:
123 c: 2
124 d:
125 - 3
126 - 4
127```
128
129