README

TOML parser and encoder library for Golang Build Status

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]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 Config
    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)
}

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 the encoding.TextUnmarshaler interface

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
}
Using the toml.UnmarshalerRec interface

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.

Using the toml.Unmarshaler interface

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 the Unmarshaler example.

API documentation

See Godoc.

License

MIT

Expand ▾ Collapse ▴

Documentation

Overview

    Package toml encodes and decodes the TOML configuration format using reflection.

    This library is compatible with TOML version v0.4.0.

    Example
    Output:
    
    IP of server 'alpha': 10.0.0.1
    
    Example (TextUnmarshaler)
    Output:
    
    Unmarshaled:
    {Servers:[192.0.2.10 198.51.100.3]}
    
    Marshaled:
    servers = ["192.0.2.10", "198.51.100.3"]
    
    Example (TextUnmarshalerError)
    Output:
    
    Unmarshal error:
    line 2: (toml_test.Config.Servers) invalid IP address: 198.51.100.500
    

    Index

    Examples

    Constants

    This section is empty.

    Variables

    View Source
    var DefaultConfig = Config{
    	NormFieldName: defaultNormFieldName,
    	FieldToKey:    snakeCase,
    }

      DefaultConfig contains the default options for encoding and decoding. Snake case (i.e. 'foo_bar') is used for key names.

      Functions

      func Marshal

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

        Marshal returns the TOML encoding of v. It is shorthand for DefaultConfig.Marshal(v).

        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. It is shorthand for DefaultConfig.Unmarshal(data, v).

            func UnmarshalTable

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

              UnmarshalTable applies the contents of an ast.Table to the value pointed at by v. It is shorthand for DefaultConfig.UnmarshalTable(t, v).

              Types

              type Config

              type Config struct {
              	// NormFieldName is used to match TOML keys to struct fields. The function runs for
              	// both input keys and struct field names and should return a string that makes the
              	// two match. You must set this field to use the decoder.
              	//
              	// Example: The function in the default config removes _ and lowercases all keys. This
              	// allows a key called 'api_key' to match the struct field 'APIKey' because both are
              	// normalized to 'apikey'.
              	//
              	// Note that NormFieldName is not used for fields which define a TOML
              	// key through the struct tag.
              	NormFieldName func(typ reflect.Type, keyOrField string) string
              
              	// FieldToKey determines the TOML key of a struct field when encoding.
              	// You must set this field to use the encoder.
              	//
              	// Note that FieldToKey is not used for fields which define a TOML
              	// key through the struct tag.
              	FieldToKey func(typ reflect.Type, field string) string
              
              	// MissingField, if non-nil, is called when the decoder encounters a key for which no
              	// matching struct field exists. The default behavior is to return an error.
              	MissingField func(typ reflect.Type, key string) error
              }

                Config contains options for encoding and decoding.

                func (*Config) Marshal

                func (cfg *Config) 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 (*Config) NewDecoder

                  func (cfg *Config) 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 (*Config) NewEncoder

                    func (cfg *Config) NewEncoder(w io.Writer) *Encoder

                      NewEncoder returns a new Encoder that writes to w.

                      func (*Config) Unmarshal

                      func (cfg *Config) 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
                        TOML tables to struct or map
                        TOML array tables to slice of struct or map
                        

                        func (*Config) UnmarshalTable

                        func (cfg *Config) UnmarshalTable(t *ast.Table, v interface{}) 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
                          TOML tables to struct or map
                          TOML array tables to slice of struct or map
                          

                          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. It is shorthand for DefaultConfig.NewDecoder(r).

                              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. It is shorthand for DefaultConfig.NewEncoder(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 LineError

                                      type LineError struct {
                                      	Line        int
                                      	StructField string
                                      	Err         error
                                      }

                                        LineError is returned by Unmarshal, UnmarshalTable and Parse if the error is local to a line.

                                        func (*LineError) Error

                                        func (err *LineError) Error() string

                                        type Marshaler

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

                                          Marshaler can be implemented to override the encoding of TOML values. The returned text must be a simple TOML value (i.e. not a table) and is inserted into marshaler output.

                                          This interface exists for backwards-compatibility reasons. You probably want to implement encoding.TextMarshaler or MarshalerRec instead.

                                          type MarshalerRec

                                          type MarshalerRec interface {
                                          	MarshalTOML() (interface{}, error)
                                          }

                                            MarshalerRec can be implemented to override the TOML encoding of a type. The returned value is marshaled in place of the receiver.

                                            type Unmarshaler

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

                                              Unmarshaler can be used to capture and process raw TOML source of a table or value. UnmarshalTOML must copy the input if it wishes to retain it after returning.

                                              Note: this interface is retained for backwards compatibility. You probably want to implement encoding.TextUnmarshaler or UnmarshalerRec instead.

                                              Example
                                              Output:
                                              
                                              config.Foo = 1
                                              config.Servers =
                                                [[servers]]
                                                addr = "198.51.100.3:80" # a comment
                                                [[servers]]
                                                addr = "192.0.2.10:8080"
                                                timeout = "30s"
                                              

                                              type UnmarshalerRec

                                              type UnmarshalerRec interface {
                                              	UnmarshalTOML(fn func(interface{}) error) error
                                              }

                                                UnmarshalerRec may be implemented by types to customize their behavior when being unmarshaled from TOML. You can use it to implement custom validation or to set unexported fields.

                                                UnmarshalTOML receives a function that can be called to unmarshal the original TOML value into a field or variable. It is safe to call the function more than once if necessary.

                                                Example
                                                Output:
                                                
                                                Unmarshaled:
                                                {Servers:[{Addr:198.51.100.3:80 Timeout:10s} {Addr:192.0.2.10:8080 Timeout:30s}]}
                                                

                                                Directories

                                                Path Synopsis