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.2, but preserves some behavior 16from 1.1 for backwards compatibility. 17 18Specifically, 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 29and offers backwards 30compatibility with YAML 1.1 in some cases. 311.2, including support for 32anchors, tags, map merging, etc. Multi-document unmarshalling is not yet 33implemented, and base-60 floats from YAML 1.1 are purposefully not 34supported since they're a poor design and are gone in YAML 1.2. 35 36Installation and usage 37---------------------- 38 39The import path for the package is *gopkg.in/yaml.v3*. 40 41To install it, run: 42 43 go get gopkg.in/yaml.v3 44 45API documentation 46----------------- 47 48If 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 52API stability 53------------- 54 55The package API for yaml v3 will remain stable as described in [gopkg.in](https://gopkg.in). 56 57 58License 59------- 60 61The yaml package is licensed under the MIT and Apache License 2.0 licenses. 62Please see the LICENSE file for details. 63 64 65Example 66------- 67 68```Go 69package main 70 71import ( 72 "fmt" 73 "log" 74 75 "gopkg.in/yaml.v3" 76) 77 78var data = ` 79a: Easy! 80b: 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. 87type T struct { 88 A string 89 B struct { 90 RenamedC int `yaml:"c"` 91 D []int `yaml:",flow"` 92 } 93} 94 95func 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 126This example will generate the following output: 127 128``` 129--- t: 130{Easy! {2 [3 4]}} 131 132--- t dump: 133a: Easy! 134b: 135 c: 2 136 d: [3, 4] 137 138 139--- m: 140map[a:Easy! b:map[c:2 d:[3 4]]] 141 142--- m dump: 143a: Easy! 144b: 145 c: 2 146 d: 147 - 3 148 - 4 149``` 150 151