cmd/bpa-operator/vendor/sigs.k8s.io/yaml/README.md

   1 # YAML marshaling and unmarshaling support for Go
   2
   3 [![Build Status](https://travis-ci.org/ghodss/yaml.svg)](https://travis-ci.org/ghodss/yaml)
   4
   5 ## Introduction
   6
   7 A wrapper around [go-yaml](https://github.com/go-yaml/yaml) designed to enable a better way of handling YAML when marshaling to and from structs.
   8
   9 In short, this library first converts YAML to JSON using go-yaml and then uses `json.Marshal` and `json.Unmarshal` to convert to or from the struct. This means that it effectively reuses the JSON struct tags as well as the custom JSON methods `MarshalJSON` and `UnmarshalJSON` unlike go-yaml. For a detailed overview of the rationale behind this method, [see this blog post](http://ghodss.com/2014/the-right-way-to-handle-yaml-in-golang/).
  10
  11 ## Compatibility
  12
  13 This package uses [go-yaml](https://github.com/go-yaml/yaml) and therefore supports [everything go-yaml supports](https://github.com/go-yaml/yaml#compatibility).
  14
  15 ## Caveats
  16
  17 **Caveat #1:** When using `yaml.Marshal` and `yaml.Unmarshal`, binary data should NOT be preceded with the `!!binary` YAML tag. If you do, go-yaml will convert the binary data from base64 to native binary data, which is not compatible with JSON. You can still use binary in your YAML files though - just store them without the `!!binary` tag and decode the base64 in your code (e.g. in the custom JSON methods `MarshalJSON` and `UnmarshalJSON`). This also has the benefit that your YAML and your JSON binary data will be decoded exactly the same way. As an example:
  18
  19 ```
  20 BAD:
  21         exampleKey: !!binary gIGC
  22
  23 GOOD:
  24         exampleKey: gIGC
  25 ... and decode the base64 data in your code.
  26 ```
  27
  28 **Caveat #2:** When using `YAMLToJSON` directly, maps with keys that are maps will result in an error since this is not supported by JSON. This error will occur in `Unmarshal` as well since you can't unmarshal map keys anyways since struct fields can't be keys.
  29
  30 ## Installation and usage
  31
  32 To install, run:
  33
  34 ```
  35 $ go get github.com/ghodss/yaml
  36 ```
  37
  38 And import using:
  39
  40 ```
  41 import "github.com/ghodss/yaml"
  42 ```
  43
  44 Usage is very similar to the JSON library:
  45
  46 ```go
  47 package main
  48
  49 import (
  50         "fmt"
  51
  52         "github.com/ghodss/yaml"
  53 )
  54
  55 type Person struct {
  56         Name string `json:"name"` // Affects YAML field names too.
  57         Age  int    `json:"age"`
  58 }
  59
  60 func main() {
  61         // Marshal a Person struct to YAML.
  62         p := Person{"John", 30}
  63         y, err := yaml.Marshal(p)
  64         if err != nil {
  65                 fmt.Printf("err: %v\n", err)
  66                 return
  67         }
  68         fmt.Println(string(y))
  69         /* Output:
  70         age: 30
  71         name: John
  72         */
  73
  74         // Unmarshal the YAML back into a Person struct.
  75         var p2 Person
  76         err = yaml.Unmarshal(y, &p2)
  77         if err != nil {
  78                 fmt.Printf("err: %v\n", err)
  79                 return
  80         }
  81         fmt.Println(p2)
  82         /* Output:
  83         {John 30}
  84         */
  85 }
  86 ```
  87
  88 `yaml.YAMLToJSON` and `yaml.JSONToYAML` methods are also available:
  89
  90 ```go
  91 package main
  92
  93 import (
  94         "fmt"
  95
  96         "github.com/ghodss/yaml"
  97 )
  98
  99 func main() {
 100         j := []byte(`{"name": "John", "age": 30}`)
 101         y, err := yaml.JSONToYAML(j)
 102         if err != nil {
 103                 fmt.Printf("err: %v\n", err)
 104                 return
 105         }
 106         fmt.Println(string(y))
 107         /* Output:
 108         name: John
 109         age: 30
 110         */
 111         j2, err := yaml.YAMLToJSON(y)
 112         if err != nil {
 113                 fmt.Printf("err: %v\n", err)
 114                 return
 115         }
 116         fmt.Println(string(j2))
 117         /* Output:
 118         {"age":30,"name":"John"}
 119         */
 120 }
 121 ```