toml

README

TOML parser and encoder library for Golang

TOML parser and encoder library for Golang.

This library is compatible with TOML version v0.4.0.

Installation

go get -u github.com/naoina/toml

Usage

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 (
    "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

timeout_seconds = 256

type Config struct {
	Timeout_seconds int
}

Camelcase matching

server_name = "srv1"

type Config struct {
	ServerName string
}

Uppercase matching

ip = "10.0.0.1"

type Config struct {
	IP string
}

See the following examples for the value mappings.

String

val = "string"

type Config struct {
	Val string
}

Integer

val = 100

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

val = 3.1415

type Config struct {
	Val float32
}

All types that can be used are following:

• float32
• float64

Boolean

val = true

type Config struct {
	Val bool
}

Datetime

val = 2014-09-28T21:27:39Z

type Config struct {
	Val time.Time
}

Array

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{}
}

Table

[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
}

Array of Tables

[[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
		}
	}
}

Using toml.UnmarshalTOML interface

duration = "10s"

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.

License

MIT

Documentation

Index

• func Marshal(v interface{}) ([]byte, error)
• func Parse(data []byte) (*ast.Table, error)
• func Unmarshal(data []byte, v interface{}) error
• func UnmarshalTable(t *ast.Table, v interface{}) (err error)
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (d *Decoder) Decode(v interface{}) error
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (e *Encoder) Encode(v interface{}) error
• type Marshaler
• type Unmarshaler

Functions

func Marshal

func Marshal(v interface{}) ([]byte, error)

Marshal returns the TOML encoding of v.

Struct values encode as TOML. Each exported struct field becomes a field of the TOML structure unless

• the field's tag is "-", or
• the field is empty and its tag specifies the "omitempty" option.

The "toml" key in the struct field's tag value is the key name, followed by an optional comma and options. Examples:

// Field is ignored by this package.
Field int `toml:"-"`

// Field appears in TOML as key "myName".
Field int `toml:"myName"`

// Field appears in TOML as key "myName" and the field is omitted from the
// result of encoding if its value is empty.
Field int `toml:"myName,omitempty"`

// Field appears in TOML as key "field", but the field is skipped if
// empty.
// Note the leading comma.
Field int `toml:",omitempty"`

func Parse

func Parse(data []byte) (*ast.Table, error)

Parse returns an AST representation of TOML. The toplevel is represented by a table.

func Unmarshal

func Unmarshal(data []byte, v interface{}) error

Unmarshal parses the TOML data and stores the result in the value pointed to by v.

Unmarshal will mapped to v that according to following rules:

TOML strings to string
TOML integers to any int type
TOML floats to float32 or float64
TOML booleans to bool
TOML datetimes to time.Time
TOML arrays to any type of slice or []interface{}
TOML tables to struct
TOML array of tables to slice of struct

func UnmarshalTable

func UnmarshalTable(t *ast.Table, v interface{}) (err error)

UnmarshalTable applies the contents of an ast.Table to the value pointed at by v.

UnmarshalTable will mapped to v that according to following rules:

TOML strings to string
TOML integers to any int type
TOML floats to float32 or float64
TOML booleans to bool
TOML datetimes to time.Time
TOML arrays to any type of slice or []interface{}
TOML tables to struct
TOML array of tables to slice of struct

Types

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

A Decoder reads and decodes TOML from an input stream.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new Decoder that reads from r. Note that it reads all from r before parsing it.

func (*Decoder) Decode

func (d *Decoder) Decode(v interface{}) error

Decode parses the TOML data from its input and stores it in the value pointed to by v. See the documentation for Unmarshal for details about the conversion of TOML into a Go value.

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

A Encoder writes TOML to an output stream.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new Encoder that writes to w.

func (*Encoder) Encode

func (e *Encoder) Encode(v interface{}) error

Encode writes the TOML of v to the stream. See the documentation for Marshal for details about the conversion of Go values to TOML.

type Marshaler

type Marshaler interface {
	MarshalTOML() ([]byte, error)
}

Marshaler is the interface implemented by objects that can marshal themshelves into valid TOML.

type Unmarshaler

type Unmarshaler interface {
	UnmarshalTOML([]byte) error
}

Unmarshaler is the interface implemented by objects that can unmarshal a TOML description of themselves. The input can be assumed to be a valid encoding of a TOML value. UnmarshalJSON must copy the TOML data if it wishes to retain the data after returning.