1TOML stands for Tom's Obvious, Minimal Language. This Go package provides a
2reflection interface similar to Go's standard library `json` and `xml` packages.
3
4Compatible with TOML version [v1.0.0](https://toml.io/en/v1.0.0).
5
6Documentation: https://godocs.io/github.com/BurntSushi/toml
7
8See the [releases page](https://github.com/BurntSushi/toml/releases) for a
9changelog; this information is also in the git tag annotations (e.g. `git show
10v0.4.0`).
11
12This library requires Go 1.13 or newer; add it to your go.mod with:
13
14 % go get github.com/BurntSushi/toml@latest
15
16It also comes with a TOML validator CLI tool:
17
18 % go install github.com/BurntSushi/toml/cmd/tomlv@latest
19 % tomlv some-toml-file.toml
20
21### Examples
22For the simplest example, consider some TOML file as just a list of keys and
23values:
24
25```toml
26Age = 25
27Cats = [ "Cauchy", "Plato" ]
28Pi = 3.14
29Perfection = [ 6, 28, 496, 8128 ]
30DOB = 1987-07-05T05:45:00Z
31```
32
33Which can be decoded with:
34
35```go
36type Config struct {
37 Age int
38 Cats []string
39 Pi float64
40 Perfection []int
41 DOB time.Time
42}
43
44var conf Config
45_, err := toml.Decode(tomlData, &conf)
46```
47
48You can also use struct tags if your struct field name doesn't map to a TOML key
49value directly:
50
51```toml
52some_key_NAME = "wat"
53```
54
55```go
56type TOML struct {
57 ObscureKey string `toml:"some_key_NAME"`
58}
59```
60
61Beware that like other decoders **only exported fields** are considered when
62encoding and decoding; private fields are silently ignored.
63
64### Using the `Marshaler` and `encoding.TextUnmarshaler` interfaces
65Here's an example that automatically parses values in a `mail.Address`:
66
67```toml
68contacts = [
69 "Donald Duck <donald@duckburg.com>",
70 "Scrooge McDuck <scrooge@duckburg.com>",
71]
72```
73
74Can be decoded with:
75
76```go
77// Create address type which satisfies the encoding.TextUnmarshaler interface.
78type address struct {
79 *mail.Address
80}
81
82func (a *address) UnmarshalText(text []byte) error {
83 var err error
84 a.Address, err = mail.ParseAddress(string(text))
85 return err
86}
87
88// Decode it.
89func decode() {
90 blob := `
91 contacts = [
92 "Donald Duck <donald@duckburg.com>",
93 "Scrooge McDuck <scrooge@duckburg.com>",
94 ]
95 `
96
97 var contacts struct {
98 Contacts []address
99 }
100
101 _, err := toml.Decode(blob, &contacts)
102 if err != nil {
103 log.Fatal(err)
104 }
105
106 for _, c := range contacts.Contacts {
107 fmt.Printf("%#v\n", c.Address)
108 }
109
110 // Output:
111 // &mail.Address{Name:"Donald Duck", Address:"donald@duckburg.com"}
112 // &mail.Address{Name:"Scrooge McDuck", Address:"scrooge@duckburg.com"}
113}
114```
115
116To target TOML specifically you can implement `UnmarshalTOML` TOML interface in
117a similar way.
118
119### More complex usage
120See the [`_example/`](/_example) directory for a more complex example.
View as plain text