annotate vendor/gopkg.in/yaml.v2/README.md @ 71:7819959ac6ca draft

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