|
1 | 1 | # YAML support for the Go language
|
2 | 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 *github.com/zillow/go-yaml.v3*. |
40 |
| - |
41 |
| -To install it, run: |
42 |
| - |
43 |
| - go get github.com/zillow/go-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://github.com/zillow/go-yaml.v3](https://github.com/zillow/go-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 |
| - "github.com/zillow/go-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 |
| - |
| 3 | +Forked from https://github.com/go-yaml/yaml |
0 commit comments