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