TOML parser and encoder library for Golang.
This library is compatible with TOML version v0.4.0.
go get -u github.com/naoina/toml
The following TOML save as example.toml.
# This is a TOML document. Boom.
title = "TOML Example"
[owner]
name = "Lance Uppercut"
dob = 1979-05-27T07:32:00-08:00 # First class dates? Why not?
[database]
server = "192.168.1.1"
ports = [ 8001, 8001, 8002 ]
connection_max = 5000
enabled = true
[servers]
# You can indent as you please. Tabs or spaces. TOML don't care.
[servers.alpha]
ip = "10.0.0.1"
dc = "eqdc10"
[servers.beta]
ip = "10.0.0.2"
dc = "eqdc10"
[clients]
data = [ ["gamma", "delta"], [1, 2] ]
# Line breaks are OK when inside arrays
hosts = [
"alpha",
"omega"
]Then above TOML will mapping to tomlConfig struct using toml.Unmarshal.
package main
import (
"os"
"time"
"github.com/naoina/toml"
)
type tomlConfig struct {
Title string
Owner struct {
Name string
Dob time.Time
}
Database struct {
Server string
Ports []int
ConnectionMax uint
Enabled bool
}
Servers map[string]ServerInfo
Clients struct {
Data [][]interface{}
Hosts []string
}
}
type ServerInfo struct {
IP net.IP
DC string
}
func main() {
f, err := os.Open("example.toml")
if err != nil {
panic(err)
}
defer f.Close()
var config tomlConfig
if err := toml.NewDecoder(f).Decode(&config); err != nil {
panic(err)
}
// then to use the unmarshaled config...
fmt.Println("IP of server 'alpha':", config.Servers["alpha"].IP)
}A key and value of TOML will map to the corresponding field. The fields of struct for mapping must be exported.
The rules of the mapping of key are following:
timeout_seconds = 256type Config struct {
Timeout_seconds int
}server_name = "srv1"type Config struct {
ServerName string
}ip = "10.0.0.1"type Config struct {
IP string
}See the following examples for the value mappings.
val = "string"type Config struct {
Val string
}val = 100type Config struct {
Val int
}All types that can be used are following:
- int8 (from
-128to127) - int16 (from
-32768to32767) - int32 (from
-2147483648to2147483647) - int64 (from
-9223372036854775808to9223372036854775807) - int (same as
int32on 32bit environment, orint64on 64bit environment) - uint8 (from
0to255) - uint16 (from
0to65535) - uint32 (from
0to4294967295) - uint64 (from
0to18446744073709551615) - uint (same as
uint32on 32bit environment, oruint64on 64bit environment)
val = 3.1415type Config struct {
Val float32
}All types that can be used are following:
- float32
- float64
val = truetype Config struct {
Val bool
}val = 2014-09-28T21:27:39Ztype Config struct {
Val time.Time
}val = ["a", "b", "c"]type Config struct {
Val []string
}Also following examples all can be mapped:
val1 = [1, 2, 3]
val2 = [["a", "b"], ["c", "d"]]
val3 = [[1, 2, 3], ["a", "b", "c"]]
val4 = [[1, 2, 3], [["a", "b"], [true, false]]]type Config struct {
Val1 []int
Val2 [][]string
Val3 [][]interface{}
Val4 [][]interface{}
}[server]
type = "app"
[server.development]
ip = "10.0.0.1"
[server.production]
ip = "10.0.0.2"type Config struct {
Server map[string]Server
}
type Server struct {
IP string
}You can also use the following struct instead of map of struct.
type Config struct {
Server struct {
Development Server
Production Server
}
}
type Server struct {
IP string
}[[fruit]]
name = "apple"
[fruit.physical]
color = "red"
shape = "round"
[[fruit.variety]]
name = "red delicious"
[[fruit.variety]]
name = "granny smith"
[[fruit]]
name = "banana"
[[fruit.variety]]
name = "plantain"type Config struct {
Fruit []struct {
Name string
Physical struct {
Color string
Shape string
}
Variety []struct {
Name string
}
}
}Package toml supports encoding.TextUnmarshaler (and encoding.TextMarshaler). You can
use it to apply custom marshaling rules for certain types. The UnmarshalText method is
called with the value text found in the TOML input. TOML strings are passed unquoted.
duration = "10s"import time
type Duration time.Duration
// UnmarshalText implements encoding.TextUnmarshaler
func (d *Duration) UnmarshalText(data []byte) error {
duration, err := time.ParseDuration(string(data))
if err == nil {
*d = Duration(duration)
}
return err
}
// MarshalText implements encoding.TextMarshaler
func (d Duration) MarshalText() ([]byte, error) {
return []byte(time.Duration(d).String()), nil
}
type ConfigWithDuration struct {
Duration Duration
}You can also override marshaling rules specifically for TOML using the UnmarshalerRec
and MarshalerRec interfaces. These are useful if you want to control how structs or
arrays are handled. You can apply additional validation or set unexported struct fields.
Note: encoding.TextUnmarshaler and encoding.TextMarshaler should be preferred for
simple (scalar) values because they're also compatible with other formats like JSON or
YAML.
See the UnmarshalerRec example.
If you want to deal with raw TOML syntax, use the Unmarshaler and Marshaler
interfaces. Their input and output is raw TOML syntax. As such, these interfaces are
useful if you want to handle TOML at the syntax level.
See Godoc.
MIT