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