Mercurial > yakumo_izuru > aya

comparison vendor/gopkg.in/yaml.v3/README.md @ 74:d8727551f403 draft

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
The Empress (III) * Change the way how versions are handled in version.go (to ease `go install`) * Upgrade yaml.v2 to yaml.v3 Signed-off-by: Izuru Yakumo <yakumo.izuru@chaotic.ninja>
author yakumo.izuru
date Mon, 04 Dec 2023 00:54:29 +0000
parents
children
comparison
equal deleted inserted replaced
73:8533d875a2bb 74:d8727551f403
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