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 51```Go 52package main 53 54import ( 55 "fmt" 56 "log" 57 58 "gopkg.in/yaml.v2" 59) 60 61var data = ` 62a: Easy! 63b: 64 c: 2 65 d: [3, 4] 66` 67 68// Note: struct fields must be public in order for unmarshal to 69// correctly populate the data. 70type T struct { 71 A string 72 B struct { 73 RenamedC int `yaml:"c"` 74 D []int `yaml:",flow"` 75 } 76} 77 78func main() { 79 t := T{} 80 81 err := yaml.Unmarshal([]byte(data), &t) 82 if err != nil { 83 log.Fatalf("error: %v", err) 84 } 85 fmt.Printf("--- t:\n%v\n\n", t) 86 87 d, err := yaml.Marshal(&t) 88 if err != nil { 89 log.Fatalf("error: %v", err) 90 } 91 fmt.Printf("--- t dump:\n%s\n\n", string(d)) 92 93 m := make(map[interface{}]interface{}) 94 95 err = yaml.Unmarshal([]byte(data), &m) 96 if err != nil { 97 log.Fatalf("error: %v", err) 98 } 99 fmt.Printf("--- m:\n%v\n\n", m) 100 101 d, err = yaml.Marshal(&m) 102 if err != nil { 103 log.Fatalf("error: %v", err) 104 } 105 fmt.Printf("--- m dump:\n%s\n\n", string(d)) 106} 107``` 108 109This example will generate the following output: 110 111``` 112--- t: 113{Easy! {2 [3 4]}} 114 115--- t dump: 116a: Easy! 117b: 118 c: 2 119 d: [3, 4] 120 121 122--- m: 123map[a:Easy! b:map[c:2 d:[3 4]]] 124 125--- m dump: 126a: Easy! 127b: 128 c: 2 129 d: 130 - 3 131 - 4 132``` 133 134