.config/coc/extensions/coc-go-data/tools/pkg/mod/github.com/!burnt!sushi/toml@v0.3.1/README.md

   1 ## TOML parser and encoder for Go with reflection
   2
   3 TOML stands for Tom's Obvious, Minimal Language. This Go package provides a
   4 reflection interface similar to Go's standard library `json` and `xml`
   5 packages. This package also supports the `encoding.TextUnmarshaler` and
   6 `encoding.TextMarshaler` interfaces so that you can define custom data
   7 representations. (There is an example of this below.)
   8
   9 Spec: https://github.com/toml-lang/toml
  10
  11 Compatible with TOML version
  12 [v0.4.0](https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.4.0.md)
  13
  14 Documentation: https://godoc.org/github.com/BurntSushi/toml
  15
  16 Installation:
  17
  18 ```bash
  19 go get github.com/BurntSushi/toml
  20 ```
  21
  22 Try the toml validator:
  23
  24 ```bash
  25 go get github.com/BurntSushi/toml/cmd/tomlv
  26 tomlv some-toml-file.toml
  27 ```
  28
  29 [![Build Status](https://travis-ci.org/BurntSushi/toml.svg?branch=master)](https://travis-ci.org/BurntSushi/toml) [![GoDoc](https://godoc.org/github.com/BurntSushi/toml?status.svg)](https://godoc.org/github.com/BurntSushi/toml)
  30
  31 ### Testing
  32
  33 This package passes all tests in
  34 [toml-test](https://github.com/BurntSushi/toml-test) for both the decoder
  35 and the encoder.
  36
  37 ### Examples
  38
  39 This package works similarly to how the Go standard library handles `XML`
  40 and `JSON`. Namely, data is loaded into Go values via reflection.
  41
  42 For the simplest example, consider some TOML file as just a list of keys
  43 and values:
  44
  45 ```toml
  46 Age = 25
  47 Cats = [ "Cauchy", "Plato" ]
  48 Pi = 3.14
  49 Perfection = [ 6, 28, 496, 8128 ]
  50 DOB = 1987-07-05T05:45:00Z
  51 ```
  52
  53 Which could be defined in Go as:
  54
  55 ```go
  56 type Config struct {
  57   Age int
  58   Cats []string
  59   Pi float64
  60   Perfection []int
  61   DOB time.Time // requires `import time`
  62 }
  63 ```
  64
  65 And then decoded with:
  66
  67 ```go
  68 var conf Config
  69 if _, err := toml.Decode(tomlData, &conf); err != nil {
  70   // handle error
  71 }
  72 ```
  73
  74 You can also use struct tags if your struct field name doesn't map to a TOML
  75 key value directly:
  76
  77 ```toml
  78 some_key_NAME = "wat"
  79 ```
  80
  81 ```go
  82 type TOML struct {
  83   ObscureKey string `toml:"some_key_NAME"`
  84 }
  85 ```
  86
  87 ### Using the `encoding.TextUnmarshaler` interface
  88
  89 Here's an example that automatically parses duration strings into
  90 `time.Duration` values:
  91
  92 ```toml
  93 [[song]]
  94 name = "Thunder Road"
  95 duration = "4m49s"
  96
  97 [[song]]
  98 name = "Stairway to Heaven"
  99 duration = "8m03s"
 100 ```
 101
 102 Which can be decoded with:
 103
 104 ```go
 105 type song struct {
 106   Name     string
 107   Duration duration
 108 }
 109 type songs struct {
 110   Song []song
 111 }
 112 var favorites songs
 113 if _, err := toml.Decode(blob, &favorites); err != nil {
 114   log.Fatal(err)
 115 }
 116
 117 for _, s := range favorites.Song {
 118   fmt.Printf("%s (%s)\n", s.Name, s.Duration)
 119 }
 120 ```
 121
 122 And you'll also need a `duration` type that satisfies the
 123 `encoding.TextUnmarshaler` interface:
 124
 125 ```go
 126 type duration struct {
 127         time.Duration
 128 }
 129
 130 func (d *duration) UnmarshalText(text []byte) error {
 131         var err error
 132         d.Duration, err = time.ParseDuration(string(text))
 133         return err
 134 }
 135 ```
 136
 137 ### More complex usage
 138
 139 Here's an example of how to load the example from the official spec page:
 140
 141 ```toml
 142 # This is a TOML document. Boom.
 143
 144 title = "TOML Example"
 145
 146 [owner]
 147 name = "Tom Preston-Werner"
 148 organization = "GitHub"
 149 bio = "GitHub Cofounder & CEO\nLikes tater tots and beer."
 150 dob = 1979-05-27T07:32:00Z # First class dates? Why not?
 151
 152 [database]
 153 server = "192.168.1.1"
 154 ports = [ 8001, 8001, 8002 ]
 155 connection_max = 5000
 156 enabled = true
 157
 158 [servers]
 159
 160   # You can indent as you please. Tabs or spaces. TOML don't care.
 161   [servers.alpha]
 162   ip = "10.0.0.1"
 163   dc = "eqdc10"
 164
 165   [servers.beta]
 166   ip = "10.0.0.2"
 167   dc = "eqdc10"
 168
 169 [clients]
 170 data = [ ["gamma", "delta"], [1, 2] ] # just an update to make sure parsers support it
 171
 172 # Line breaks are OK when inside arrays
 173 hosts = [
 174   "alpha",
 175   "omega"
 176 ]
 177 ```
 178
 179 And the corresponding Go types are:
 180
 181 ```go
 182 type tomlConfig struct {
 183         Title string
 184         Owner ownerInfo
 185         DB database `toml:"database"`
 186         Servers map[string]server
 187         Clients clients
 188 }
 189
 190 type ownerInfo struct {
 191         Name string
 192         Org string `toml:"organization"`
 193         Bio string
 194         DOB time.Time
 195 }
 196
 197 type database struct {
 198         Server string
 199         Ports []int
 200         ConnMax int `toml:"connection_max"`
 201         Enabled bool
 202 }
 203
 204 type server struct {
 205         IP string
 206         DC string
 207 }
 208
 209 type clients struct {
 210         Data [][]interface{}
 211         Hosts []string
 212 }
 213 ```
 214
 215 Note that a case insensitive match will be tried if an exact match can't be
 216 found.
 217
 218 A working example of the above can be found in `_examples/example.{go,toml}`.