README.md
1# TOML parser and encoder library for Golang [![Build Status](https://travis-ci.org/naoina/toml.png?branch=master)](https://travis-ci.org/naoina/toml)
2
3[TOML](https://github.com/toml-lang/toml) parser and encoder library for [Golang](http://golang.org/).
4
5This library is compatible with TOML version [v0.4.0](https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.4.0.md).
6
7## Installation
8
9 go get -u github.com/naoina/toml
10
11## Usage
12
13The following TOML save as `example.toml`.
14
15```toml
16# This is a TOML document. Boom.
17
18title = "TOML Example"
19
20[owner]
21name = "Lance Uppercut"
22dob = 1979-05-27T07:32:00-08:00 # First class dates? Why not?
23
24[database]
25server = "192.168.1.1"
26ports = [ 8001, 8001, 8002 ]
27connection_max = 5000
28enabled = true
29
30[servers]
31
32 # You can indent as you please. Tabs or spaces. TOML don't care.
33 [servers.alpha]
34 ip = "10.0.0.1"
35 dc = "eqdc10"
36
37 [servers.beta]
38 ip = "10.0.0.2"
39 dc = "eqdc10"
40
41[clients]
42data = [ ["gamma", "delta"], [1, 2] ]
43
44# Line breaks are OK when inside arrays
45hosts = [
46 "alpha",
47 "omega"
48]
49```
50
51Then above TOML will mapping to `tomlConfig` struct using `toml.Unmarshal`.
52
53```go
54package main
55
56import (
57 "io/ioutil"
58 "os"
59 "time"
60
61 "github.com/naoina/toml"
62)
63
64type tomlConfig struct {
65 Title string
66 Owner struct {
67 Name string
68 Dob time.Time
69 }
70 Database struct {
71 Server string
72 Ports []int
73 ConnectionMax uint
74 Enabled bool
75 }
76 Servers map[string]ServerInfo
77 Clients struct {
78 Data [][]interface{}
79 Hosts []string
80 }
81}
82
83type ServerInfo struct {
84 IP net.IP
85 DC string
86}
87
88func main() {
89 f, err := os.Open("example.toml")
90 if err != nil {
91 panic(err)
92 }
93 defer f.Close()
94 var config Config
95 if err := toml.NewDecoder(f).Decode(&config); err != nil {
96 panic(err)
97 }
98
99 // then to use the unmarshaled config...
100 fmt.Println("IP of server 'alpha':", config.Servers["alpha"].IP)
101}
102```
103
104## Mappings
105
106A key and value of TOML will map to the corresponding field.
107The fields of struct for mapping must be exported.
108
109The rules of the mapping of key are following:
110
111#### Exact matching
112
113```toml
114timeout_seconds = 256
115```
116
117```go
118type Config struct {
119 Timeout_seconds int
120}
121```
122
123#### Camelcase matching
124
125```toml
126server_name = "srv1"
127```
128
129```go
130type Config struct {
131 ServerName string
132}
133```
134
135#### Uppercase matching
136
137```toml
138ip = "10.0.0.1"
139```
140
141```go
142type Config struct {
143 IP string
144}
145```
146
147See the following examples for the value mappings.
148
149### String
150
151```toml
152val = "string"
153```
154
155```go
156type Config struct {
157 Val string
158}
159```
160
161### Integer
162
163```toml
164val = 100
165```
166
167```go
168type Config struct {
169 Val int
170}
171```
172
173All types that can be used are following:
174
175* int8 (from `-128` to `127`)
176* int16 (from `-32768` to `32767`)
177* int32 (from `-2147483648` to `2147483647`)
178* int64 (from `-9223372036854775808` to `9223372036854775807`)
179* int (same as `int32` on 32bit environment, or `int64` on 64bit environment)
180* uint8 (from `0` to `255`)
181* uint16 (from `0` to `65535`)
182* uint32 (from `0` to `4294967295`)
183* uint64 (from `0` to `18446744073709551615`)
184* uint (same as `uint` on 32bit environment, or `uint64` on 64bit environment)
185
186### Float
187
188```toml
189val = 3.1415
190```
191
192```go
193type Config struct {
194 Val float32
195}
196```
197
198All types that can be used are following:
199
200* float32
201* float64
202
203### Boolean
204
205```toml
206val = true
207```
208
209```go
210type Config struct {
211 Val bool
212}
213```
214
215### Datetime
216
217```toml
218val = 2014-09-28T21:27:39Z
219```
220
221```go
222type Config struct {
223 Val time.Time
224}
225```
226
227### Array
228
229```toml
230val = ["a", "b", "c"]
231```
232
233```go
234type Config struct {
235 Val []string
236}
237```
238
239Also following examples all can be mapped:
240
241```toml
242val1 = [1, 2, 3]
243val2 = [["a", "b"], ["c", "d"]]
244val3 = [[1, 2, 3], ["a", "b", "c"]]
245val4 = [[1, 2, 3], [["a", "b"], [true, false]]]
246```
247
248```go
249type Config struct {
250 Val1 []int
251 Val2 [][]string
252 Val3 [][]interface{}
253 Val4 [][]interface{}
254}
255```
256
257### Table
258
259```toml
260[server]
261type = "app"
262
263 [server.development]
264 ip = "10.0.0.1"
265
266 [server.production]
267 ip = "10.0.0.2"
268```
269
270```go
271type Config struct {
272 Server map[string]Server
273}
274
275type Server struct {
276 IP string
277}
278```
279
280You can also use the following struct instead of map of struct.
281
282```go
283type Config struct {
284 Server struct {
285 Development Server
286 Production Server
287 }
288}
289
290type Server struct {
291 IP string
292}
293```
294
295### Array of Tables
296
297```toml
298[[fruit]]
299 name = "apple"
300
301 [fruit.physical]
302 color = "red"
303 shape = "round"
304
305 [[fruit.variety]]
306 name = "red delicious"
307
308 [[fruit.variety]]
309 name = "granny smith"
310
311[[fruit]]
312 name = "banana"
313
314 [[fruit.variety]]
315 name = "plantain"
316```
317
318```go
319type Config struct {
320 Fruit []struct {
321 Name string
322 Physical struct {
323 Color string
324 Shape string
325 }
326 Variety []struct {
327 Name string
328 }
329 }
330}
331```
332
333### Using the `encoding.TextUnmarshaler` interface
334
335Package toml supports `encoding.TextUnmarshaler` (and `encoding.TextMarshaler`). You can
336use it to apply custom marshaling rules for certain types. The `UnmarshalText` method is
337called with the value text found in the TOML input. TOML strings are passed unquoted.
338
339```toml
340duration = "10s"
341```
342
343```go
344import time
345
346type Duration time.Duration
347
348// UnmarshalText implements encoding.TextUnmarshaler
349func (d *Duration) UnmarshalText(data []byte) error {
350 duration, err := time.ParseDuration(string(data))
351 if err == nil {
352 *d = Duration(duration)
353 }
354 return err
355}
356
357// MarshalText implements encoding.TextMarshaler
358func (d Duration) MarshalText() ([]byte, error) {
359 return []byte(time.Duration(d).String()), nil
360}
361
362type ConfigWithDuration struct {
363 Duration Duration
364}
365```
366### Using the `toml.UnmarshalerRec` interface
367
368You can also override marshaling rules specifically for TOML using the `UnmarshalerRec`
369and `MarshalerRec` interfaces. These are useful if you want to control how structs or
370arrays are handled. You can apply additional validation or set unexported struct fields.
371
372Note: `encoding.TextUnmarshaler` and `encoding.TextMarshaler` should be preferred for
373simple (scalar) values because they're also compatible with other formats like JSON or
374YAML.
375
376[See the UnmarshalerRec example](https://godoc.org/github.com/naoina/toml/#example_UnmarshalerRec).
377
378### Using the `toml.Unmarshaler` interface
379
380If you want to deal with raw TOML syntax, use the `Unmarshaler` and `Marshaler`
381interfaces. Their input and output is raw TOML syntax. As such, these interfaces are
382useful if you want to handle TOML at the syntax level.
383
384[See the Unmarshaler example](https://godoc.org/github.com/naoina/toml/#example_Unmarshaler).
385
386## API documentation
387
388See [Godoc](http://godoc.org/github.com/naoina/toml).
389
390## License
391
392MIT
393