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