vendor/gopkg.in/yaml.v2/README.md

   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.1 and 1.2, including support for
  16 anchors, tags, map merging, etc. Multi-document unmarshalling is not yet
  17 implemented, and base-60 floats from YAML 1.1 are purposefully not
  18 supported since they're a poor design and are gone in YAML 1.2.
  19
  20 Installation and usage
  21 ----------------------
  22
  23 The import path for the package is *gopkg.in/yaml.v2*.
  24
  25 To install it, run:
  26
  27     go get gopkg.in/yaml.v2
  28
  29 API documentation
  30 -----------------
  31
  32 If 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
  36 API stability
  37 -------------
  38
  39 The package API for yaml v2 will remain stable as described in [gopkg.in](https://gopkg.in).
  40
  41
  42 License
  43 -------
  44
  45 The yaml package is licensed under the Apache License 2.0. Please see the LICENSE file for details.
  46
  47
  48 Example
  49 -------
  50
  51 ```Go
  52 package main
  53
  54 import (
  55         "fmt"
  56         "log"
  57
  58         "gopkg.in/yaml.v2"
  59 )
  60
  61 var data = `
  62 a: Easy!
  63 b:
  64   c: 2
  65   d: [3, 4]
  66 `
  67
  68 type T struct {
  69         A string
  70         B struct {
  71                 RenamedC int   `yaml:"c"`
  72                 D        []int `yaml:",flow"`
  73         }
  74 }
  75
  76 func main() {
  77         t := T{}
  78
  79         err := yaml.Unmarshal([]byte(data), &t)
  80         if err != nil {
  81                 log.Fatalf("error: %v", err)
  82         }
  83         fmt.Printf("--- t:\n%v\n\n", t)
  84
  85         d, err := yaml.Marshal(&t)
  86         if err != nil {
  87                 log.Fatalf("error: %v", err)
  88         }
  89         fmt.Printf("--- t dump:\n%s\n\n", string(d))
  90
  91         m := make(map[interface{}]interface{})
  92
  93         err = yaml.Unmarshal([]byte(data), &m)
  94         if err != nil {
  95                 log.Fatalf("error: %v", err)
  96         }
  97         fmt.Printf("--- m:\n%v\n\n", m)
  98
  99         d, err = yaml.Marshal(&m)
 100         if err != nil {
 101                 log.Fatalf("error: %v", err)
 102         }
 103         fmt.Printf("--- m dump:\n%s\n\n", string(d))
 104 }
 105 ```
 106
 107 This example will generate the following output:
 108
 109 ```
 110 --- t:
 111 {Easy! {2 [3 4]}}
 112
 113 --- t dump:
 114 a: Easy!
 115 b:
 116   c: 2
 117   d: [3, 4]
 118
 119
 120 --- m:
 121 map[a:Easy! b:map[c:2 d:[3 4]]]
 122
 123 --- m dump:
 124 a: Easy!
 125 b:
 126   c: 2
 127   d:
 128   - 3
 129   - 4
 130 ```
 131