gopkg.in/yaml.v3/README.md

# YAML support for the Go language

Introduction
------------

The yaml package enables Go programs to comfortably encode and decode YAML
values. It was developed within [Canonical](https://www.canonical.com) as
part of the [juju](https://juju.ubuntu.com) project, and is based on a
pure Go port of the well-known [libyaml](http://pyyaml.org/wiki/LibYAML)
C library to parse and generate YAML data quickly and reliably.

Compatibility
-------------

The yaml package supports most of YAML 1.2, but preserves some behavior
from 1.1 for backwards compatibility.

Specifically, as of v3 of the yaml package:

 - YAML 1.1 bools (_yes/no, on/off_) are supported as long as they are being
   decoded into a typed bool value. Otherwise they behave as a string. Booleans
   in YAML 1.2 are _true/false_ only.
 - Octals encode and decode as _0777_ per YAML 1.1, rather than _0o777_
   as specified in YAML 1.2, because most parsers still use the old format.
   Octals in the  _0o777_ format are supported though, so new files work.
 - Does not support base-60 floats. These are gone from YAML 1.2, and were
   actually never supported by this package as it's clearly a poor choice.

and offers backwards
compatibility with YAML 1.1 in some cases.
1.2, including support for
anchors, tags, map merging, etc. Multi-document unmarshalling is not yet
implemented, and base-60 floats from YAML 1.1 are purposefully not
supported since they're a poor design and are gone in YAML 1.2.

Installation and usage
----------------------

The import path for the package is *gopkg.in/yaml.v3*.

To install it, run:

    go get gopkg.in/yaml.v3

API documentation
-----------------

If opened in a browser, the import path itself leads to the API documentation:

  - [https://gopkg.in/yaml.v3](https://gopkg.in/yaml.v3)

API stability
-------------

The package API for yaml v3 will remain stable as described in [gopkg.in](https://gopkg.in).


License
-------

The yaml package is licensed under the MIT and Apache License 2.0 licenses.
Please see the LICENSE file for details.


Example
-------

```Go
package main

import (
        "fmt"
        "log"

        "gopkg.in/yaml.v3"
)

var data = `
a: Easy!
b:
  c: 2
  d: [3, 4]
`

// Note: struct fields must be public in order for unmarshal to
// correctly populate the data.
type T struct {
        A string
        B struct {
                RenamedC int   `yaml:"c"`
                D        []int `yaml:",flow"`
        }
}

func main() {
        t := T{}
    
        err := yaml.Unmarshal([]byte(data), &t)
        if err != nil {
                log.Fatalf("error: %v", err)
        }
        fmt.Printf("--- t:\n%v\n\n", t)
    
        d, err := yaml.Marshal(&t)
        if err != nil {
                log.Fatalf("error: %v", err)
        }
        fmt.Printf("--- t dump:\n%s\n\n", string(d))
    
        m := make(map[interface{}]interface{})
    
        err = yaml.Unmarshal([]byte(data), &m)
        if err != nil {
                log.Fatalf("error: %v", err)
        }
        fmt.Printf("--- m:\n%v\n\n", m)
    
        d, err = yaml.Marshal(&m)
        if err != nil {
                log.Fatalf("error: %v", err)
        }
        fmt.Printf("--- m dump:\n%s\n\n", string(d))
}
```

This example will generate the following output:

```
--- t:
{Easy! {2 [3 4]}}

--- t dump:
a: Easy!
b:
  c: 2
  d: [3, 4]


--- m:
map[a:Easy! b:map[c:2 d:[3 4]]]

--- m dump:
a: Easy!
b:
  c: 2
  d:
  - 3
  - 4
```

Revision:	1.1
Committed:	Mon Sep 30 00:42:06 2024 UTC (6 weeks, 4 days ago) by yakumo_izuru
Branch:	MAIN
CVS Tags:	HEAD
Log Message:	Mirrored from https://git.chaotic.ninja/git/yakumo_izuru/aya
#	User	Rev	Content
1	yakumo_izuru	1.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