1 ## TOML parser and encoder for Go with reflection
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.)
9 Spec: https://github.com/toml-lang/toml
11 Compatible with TOML version
12 [v0.4.0](https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.4.0.md)
14 Documentation: https://godoc.org/github.com/BurntSushi/toml
19 go get github.com/BurntSushi/toml
22 Try the toml validator:
25 go get github.com/BurntSushi/toml/cmd/tomlv
26 tomlv some-toml-file.toml
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)
33 This package passes all tests in
34 [toml-test](https://github.com/BurntSushi/toml-test) for both the decoder
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.
42 For the simplest example, consider some TOML file as just a list of keys
47 Cats = [ "Cauchy", "Plato" ]
49 Perfection = [ 6, 28, 496, 8128 ]
50 DOB = 1987-07-05T05:45:00Z
53 Which could be defined in Go as:
61 DOB time.Time // requires `import time`
65 And then decoded with:
69 if _, err := toml.Decode(tomlData, &conf); err != nil {
74 You can also use struct tags if your struct field name doesn't map to a TOML
83 ObscureKey string `toml:"some_key_NAME"`
87 ### Using the `encoding.TextUnmarshaler` interface
89 Here's an example that automatically parses duration strings into
90 `time.Duration` values:
98 name = "Stairway to Heaven"
102 Which can be decoded with:
113 if _, err := toml.Decode(blob, &favorites); err != nil {
117 for _, s := range favorites.Song {
118 fmt.Printf("%s (%s)\n", s.Name, s.Duration)
122 And you'll also need a `duration` type that satisfies the
123 `encoding.TextUnmarshaler` interface:
126 type duration struct {
130 func (d *duration) UnmarshalText(text []byte) error {
132 d.Duration, err = time.ParseDuration(string(text))
137 ### More complex usage
139 Here's an example of how to load the example from the official spec page:
142 # This is a TOML document. Boom.
144 title = "TOML Example"
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?
153 server = "192.168.1.1"
154 ports = [ 8001, 8001, 8002 ]
155 connection_max = 5000
160 # You can indent as you please. Tabs or spaces. TOML don't care.
170 data = [ ["gamma", "delta"], [1, 2] ] # just an update to make sure parsers support it
172 # Line breaks are OK when inside arrays
179 And the corresponding Go types are:
182 type tomlConfig struct {
185 DB database `toml:"database"`
186 Servers map[string]server
190 type ownerInfo struct {
192 Org string `toml:"organization"`
197 type database struct {
200 ConnMax int `toml:"connection_max"`
209 type clients struct {
215 Note that a case insensitive match will be tried if an exact match can't be
218 A working example of the above can be found in `_examples/example.{go,toml}`.