• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..15-Feb-2020-

.gitignoreH A D15-Feb-202047 65

.travis.ymlH A D15-Feb-2020209 1615

COMPATIBLEH A D15-Feb-2020113 42

COPYINGH A D15-Feb-20201.1 KiB2217

MakefileH A D15-Feb-2020289 2014

README.mdH A D15-Feb-20204.2 KiB219167

decode.goH A D15-Feb-202014.1 KiB510371

decode_meta.goH A D15-Feb-20203.1 KiB12275

doc.goH A D15-Feb-20201.1 KiB281

encode.goH A D15-Feb-202014.6 KiB569453

encoding_types.goH A D15-Feb-2020541 206

encoding_types_1.1.goH A D15-Feb-2020507 197

lex.goH A D15-Feb-202021.7 KiB954804

parse.goH A D15-Feb-202015.3 KiB593461

session.vimH A D15-Feb-202055 21

type_check.goH A D15-Feb-20202.4 KiB9265

type_fields.goH A D15-Feb-20206.3 KiB243162

README.md

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