github.com/mdaxf/iac@v0.0.0-20240519030858-58a061660378/vendor_skip/gopkg.in/yaml.v3/README.md (about)

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