Back to godoc.org
github.com/naoina/toml

package toml

v0.1.1
Latest Go to latest
Published: Apr 28, 2017 | License: MIT | Module: github.com/naoina/toml

Overview

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

This library is compatible with TOML version v0.4.0.

Example

Code:

package toml_test

import (
	"fmt"
	"net"
	"os"
	"time"

	"github.com/naoina/toml"
)

type Config struct {
	Title string
	Owner struct {
		Name string
		Org  string `toml:"organization"`
		Bio  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 Example() {
	f, err := os.Open("testdata/example.toml")
	if err != nil {
		panic(err)
	}
	defer f.Close()
	var config Config
	if err := toml.NewDecoder(f).Decode(&config); err != nil {
		panic(err)
	}

	fmt.Println("IP of server 'alpha':", config.Servers["alpha"].IP)
	// Output: IP of server 'alpha': 10.0.0.1
}

Output:

IP of server 'alpha': 10.0.0.1
Example (TextUnmarshaler)

Code:

type Config struct {
	Servers []net.IP
}

input := []byte(`
servers = ["192.0.2.10", "198.51.100.3"]
`)

var config Config
toml.Unmarshal(input, &config)
fmt.Printf("Unmarshaled:\n%+v\n\n", config)

output, _ := toml.Marshal(&config)
fmt.Printf("Marshaled:\n%s", output)

Output:

Unmarshaled:
{Servers:[192.0.2.10 198.51.100.3]}

Marshaled:
servers = ["192.0.2.10", "198.51.100.3"]
Example (TextUnmarshalerError)

Code:

type Config struct {
	Servers []net.IP
}

input := []byte(`
servers = ["192.0.2.10", "198.51.100.500"]
`)

var config Config
err := toml.Unmarshal(input, &config)
fmt.Printf("Unmarshal error:\n%v", err)

Output:

Unmarshal error:
line 2: (toml_test.Config.Servers) invalid IP address: 198.51.100.500

Index

Examples

Variables

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.

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).

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

Code:

package toml_test

import (
	"fmt"

	"github.com/naoina/toml"
)

// This example shows how the Unmarshaler interface can be used to access the TOML source
// input during decoding.

// RawTOML stores the raw TOML syntax that was passed to UnmarshalTOML.
type RawTOML []byte

func (r *RawTOML) UnmarshalTOML(input []byte) error {
	cpy := make([]byte, len(input))
	copy(cpy, input)
	*r = cpy
	return nil
}

func ExampleUnmarshaler() {
	input := []byte(`
foo = 1

[[servers]]
addr = "198.51.100.3:80" # a comment

[[servers]]
addr = "192.0.2.10:8080"
timeout = "30s"
`)
	var config struct {
		Foo     int
		Servers RawTOML
	}
	toml.Unmarshal(input, &config)
	fmt.Printf("config.Foo = %d\n", config.Foo)
	fmt.Printf("config.Servers =\n%s\n", indent(config.Servers, 2))

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

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

Code:

package toml_test

import (
	"errors"
	"fmt"
	"net"
	"time"

	"github.com/naoina/toml"
)

// This example shows how the UnmarshalerRec interface can be used to apply field
// validations and default values.

type Server struct {
	Addr    string        // "<host>:<port>"
	Timeout time.Duration // defaults to 10s
}

// UnmarshalTOML implements toml.Unmarshaler.
func (s *Server) UnmarshalTOML(decode func(interface{}) error) error {
	// Parse the input into type tomlServer, which defines the
	// expected format of Server in TOML.
	type tomlServer struct {
		Addr    string
		Timeout string
	}
	var dec tomlServer
	if err := decode(&dec); err != nil {
		return err
	}

	// Validate the address.
	if dec.Addr == "" {
		return errors.New("missing server address")
	}
	_, _, err := net.SplitHostPort(dec.Addr)
	if err != nil {
		return fmt.Errorf("invalid server address %q: %v", dec.Addr, err)
	}
	// Validate the timeout and apply the default value.
	var timeout time.Duration
	if dec.Timeout == "" {
		timeout = 10 * time.Second
	} else if timeout, err = time.ParseDuration(dec.Timeout); err != nil {
		return fmt.Errorf("invalid server timeout %q: %v", dec.Timeout, err)
	}

	// Assign the decoded value.
	*s = Server{Addr: dec.Addr, Timeout: timeout}
	return nil
}

func ExampleUnmarshalerRec() {
	input := []byte(`
[[servers]]
addr = "198.51.100.3:80"

[[servers]]
addr = "192.0.2.10:8080"
timeout = "30s"
`)
	var config struct {
		Servers []Server
	}
	toml.Unmarshal(input, &config)
	fmt.Printf("Unmarshaled:\n%+v\n\n", config)

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

Output:

Unmarshaled:
{Servers:[{Addr:198.51.100.3:80 Timeout:10s} {Addr:192.0.2.10:8080 Timeout:30s}]}
Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier