# TOML parser and encoder library for Golang [![Build Status](https://travis-ci.org/naoina/toml.png?branch=master)](https://travis-ci.org/naoina/toml) [TOML](https://github.com/toml-lang/toml) parser and encoder library for [Golang](http://golang.org/). This library is compatible with TOML version [v0.4.0](https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.4.0.md). ## Installation go get -u github.com/naoina/toml ## Usage The following TOML save as `example.toml`. ```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`. ```go package main import ( "io/ioutil" "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]Server Clients struct { Data [][]interface{} Hosts []string } } type Server struct { IP string DC string } func main() { f, err := os.Open("example.toml") if err != nil { panic(err) } defer f.Close() buf, err := ioutil.ReadAll(f) if err != nil { panic(err) } var config tomlConfig if err := toml.Unmarshal(buf, &config); err != nil { panic(err) } // then to use the unmarshaled config... } ``` ## Mappings 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: #### Exact matching ```toml timeout_seconds = 256 ``` ```go type Config struct { Timeout_seconds int } ``` #### Camelcase matching ```toml server_name = "srv1" ``` ```go type Config struct { ServerName string } ``` #### Uppercase matching ```toml ip = "10.0.0.1" ``` ```go type Config struct { IP string } ``` See the following examples for the value mappings. ### String ```toml val = "string" ``` ```go type Config struct { Val string } ``` ### Integer ```toml val = 100 ``` ```go type Config struct { Val int } ``` All types that can be used are following: * int8 (from `-128` to `127`) * int16 (from `-32768` to `32767`) * int32 (from `-2147483648` to `2147483647`) * int64 (from `-9223372036854775808` to `9223372036854775807`) * int (same as `int32` on 32bit environment, or `int64` on 64bit environment) * uint8 (from `0` to `255`) * uint16 (from `0` to `65535`) * uint32 (from `0` to `4294967295`) * uint64 (from `0` to `18446744073709551615`) * uint (same as `uint` on 32bit environment, or `uint64` on 64bit environment) ### Float ```toml val = 3.1415 ``` ```go type Config struct { Val float32 } ``` All types that can be used are following: * float32 * float64 ### Boolean ```toml val = true ``` ```go type Config struct { Val bool } ``` ### Datetime ```toml val = 2014-09-28T21:27:39Z ``` ```go type Config struct { Val time.Time } ``` ### Array ```toml val = ["a", "b", "c"] ``` ```go type Config struct { Val []string } ``` Also following examples all can be mapped: ```toml val1 = [1, 2, 3] val2 = [["a", "b"], ["c", "d"]] val3 = [[1, 2, 3], ["a", "b", "c"]] val4 = [[1, 2, 3], [["a", "b"], [true, false]]] ``` ```go type Config struct { Val1 []int Val2 [][]string Val3 [][]interface{} Val4 [][]interface{} } ``` ### Table ```toml [server] type = "app" [server.development] ip = "10.0.0.1" [server.production] ip = "10.0.0.2" ``` ```go type Config struct { Server map[string]Server } type Server struct { IP string } ``` You can also use the following struct instead of map of struct. ```go type Config struct { Server struct { Development Server Production Server } } type Server struct { IP string } ``` ### Array of Tables ```toml [[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" ``` ```go type Config struct { Fruit []struct { Name string Physical struct { Color string Shape string } Variety []struct { Name string } } } ``` ### Using `toml.UnmarshalTOML` interface ```toml duration = "10s" ``` ```go import time type Config struct { Duration Duration } type Duration struct { time.Duration } func (d *Duration) UnmarshalTOML(data []byte) error { d.Duration, err := time.ParseDuration(string(data)) return err } ``` ## API documentation See [Godoc](http://godoc.org/github.com/naoina/toml). ## License MIT