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 Some more examples can be found in the "examples" folder.
  52
  53 ```Go
  54 package main
  55
  56 import (
  57         "fmt"
  58         "log"
  59
  60         "gopkg.in/yaml.v2"
  61 )
  62
  63 var data = `
  64 a: Easy!
  65 b:
  66   c: 2
  67   d: [3, 4]
  68 `
  69
  70 type T struct {
  71         A string
  72         B struct {
  73                 RenamedC int   `yaml:"c"`
  74                 D        []int `yaml:",flow"`
  75         }
  76 }
  77
  78 func 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
 109 This example will generate the following output:
 110
 111 ```
 112 --- t:
 113 {Easy! {2 [3 4]}}
 114
 115 --- t dump:
 116 a: Easy!
 117 b:
 118   c: 2
 119   d: [3, 4]
 120
 121
 122 --- m:
 123 map[a:Easy! b:map[c:2 d:[3 4]]]
 124
 125 --- m dump:
 126 a: Easy!
 127 b:
 128   c: 2
 129   d:
 130   - 3
 131   - 4
 132 ```
 133