gtsocial-umbx

Unnamed repository; edit this file 'description' to name the repository.
Log | Files | Refs | README | LICENSE

README.md (3453B)

      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