toml

type Decoder ¶ added in v0.4.1

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

Decoder decodes TOML data.

TOML tables correspond to Go structs or maps; they can be used interchangeably, but structs offer better type safety.

TOML table arrays correspond to either a slice of structs or a slice of maps.

TOML datetimes correspond to time.Time. Local datetimes are parsed in the local timezone.

time.Duration types are treated as nanoseconds if the TOML value is an integer, or they're parsed with time.ParseDuration() if they're strings.

All other TOML types (float, string, int, bool and array) correspond to the obvious Go types.

An exception to the above rules is if a type implements the TextUnmarshaler interface, in which case any primitive TOML value (floats, strings, integers, booleans, datetimes) will be converted to a []byte and given to the value's UnmarshalText method. See the Unmarshaler example for a demonstration with email addresses.

Key mapping ¶

TOML keys can map to either keys in a Go map or field names in a Go struct. The special `toml` struct tag can be used to map TOML keys to struct fields that don't match the key name exactly (see the example). A case insensitive match to struct names will be tried if an exact match can't be found.

The mapping between TOML values and Go values is loose. That is, there may exist TOML values that cannot be placed into your representation, and there may be parts of your representation that do not correspond to TOML values. This loose mapping can be made stricter by using the IsDefined and/or Undecoded methods on the MetaData returned.

This decoder does not handle cyclic types. Decode will not terminate if a cyclic type is passed.

func NewDecoder(r io.Reader) *Decoder

func (dec *Decoder) Decode(v interface{}) (MetaData, error)

type Encoder ¶

type Encoder struct {
	// String to use for a single indentation level; default is two spaces.
	Indent string
	// contains filtered or unexported fields
}

Encoder encodes a Go to a TOML document.

The mapping between Go values and TOML values should be precisely the same as for Decode.

time.Time is encoded as a RFC 3339 string, and time.Duration as its string representation.

The Marshaler and encoding.TextMarshaler interfaces are supported to encoding the value as custom TOML.

If you want to write arbitrary binary data then you will need to use something like base64 since TOML does not have any binary types.

When encoding TOML hashes (Go maps or structs), keys without any sub-hashes are encoded first.

Go maps will be sorted alphabetically by key for deterministic output.

The toml struct tag can be used to provide the key name; if omitted the struct field name will be used. If the "omitempty" option is present the following value will be skipped:

• arrays, slices, maps, and string with len of 0
• struct with all zero values
• bool false

If omitzero is given all int and float types with a value of 0 will be skipped.

Encoding Go values without a corresponding TOML representation will return an error. Examples of this includes maps with non-string keys, slices with nil elements, embedded non-struct types, and nested slices containing maps or structs. (e.g. [][]map[string]string is not allowed but []map[string]string is okay, as is []map[string][]string).

NOTE: only exported keys are encoded due to the use of reflection. Unexported keys are silently discarded.

func NewEncoder(w io.Writer) *Encoder

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

package main

import (
	"bytes"
	"fmt"
	"log"
	"time"

	"github.com/BurntSushi/toml"
)

func main() {
	var (
		date, _ = time.Parse(time.RFC822, "14 Mar 10 18:00 UTC")
		buf     = new(bytes.Buffer)
	)
	err := toml.NewEncoder(buf).Encode(map[string]interface{}{
		"date":   date,
		"counts": []int{1, 1, 2, 3, 5, 8},
		"hash": map[string]string{
			"key1": "val1",
			"key2": "val2",
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(buf.String())

}

Output:

counts = [1, 1, 2, 3, 5, 8]
date = 2010-03-14T18:00:00Z

[hash]
  key1 = "val1"
  key2 = "val2"

type Key ¶

type Key []string

Key represents any TOML key, including key groups. Use MetaData.Keys to get values of this type.

func (k Key) String() string

type Marshaler ¶ added in v1.0.0

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

Marshaler is the interface implemented by types that can marshal themselves into valid TOML.

type MetaData ¶

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

MetaData allows access to meta information about TOML data that's not accessible otherwise.

It allows checking if a key is defined in the TOML data, whether any keys were undecoded, and the TOML type of a key.

func Decode(data string, v interface{}) (MetaData, error)

package main

import (
	"fmt"
	"log"
	"time"

	"github.com/BurntSushi/toml"
)

func main() {
	tomlBlob := `
		# Some comments.
		[alpha]
		ip = "10.0.0.1"

			[alpha.config]
			Ports = [ 8001, 8002 ]
			Location = "Toronto"
			Created = 1987-07-05T05:45:00Z

		[beta]
		ip = "10.0.0.2"

			[beta.config]
			Ports = [ 9001, 9002 ]
			Location = "New Jersey"
			Created = 1887-01-05T05:55:00Z
	`

	type (
		serverConfig struct {
			Ports    []int
			Location string
			Created  time.Time
		}
		server struct {
			IP     string       `toml:"ip,omitempty"`
			Config serverConfig `toml:"config"`
		}
		servers map[string]server
	)

	var config servers
	_, err := toml.Decode(tomlBlob, &config)
	if err != nil {
		log.Fatal(err)
	}

	for _, name := range []string{"alpha", "beta"} {
		s := config[name]
		fmt.Printf("Server: %s (ip: %s) in %s created on %s\n",
			name, s.IP, s.Config.Location,
			s.Config.Created.Format("2006-01-02"))
		fmt.Printf("Ports: %v\n", s.Config.Ports)
	}

}

Output:

Server: alpha (ip: 10.0.0.1) in Toronto created on 1987-07-05
Ports: [8001 8002]
Server: beta (ip: 10.0.0.2) in New Jersey created on 1887-01-05
Ports: [9001 9002]

func DecodeFS(fsys fs.FS, path string, v interface{}) (MetaData, error)

func DecodeFile(path string, v interface{}) (MetaData, error)

func DecodeReader(r io.Reader, v interface{}) (MetaData, error)

func (md *MetaData) IsDefined(key ...string) bool

func (md *MetaData) Keys() []Key

func (md *MetaData) PrimitiveDecode(primValue Primitive, v interface{}) error

package main

import (
	"fmt"
	"log"

	"github.com/BurntSushi/toml"
)

func main() {
	tomlBlob := `
		ranking = ["Springsteen", "J Geils"]

		[bands.Springsteen]
		started = 1973
		albums = ["Greetings", "WIESS", "Born to Run", "Darkness"]

		[bands."J Geils"]
		started = 1970
		albums = ["The J. Geils Band", "Full House", "Blow Your Face Out"]
		`

	type (
		band struct {
			Started int
			Albums  []string
		}
		classics struct {
			Ranking []string
			Bands   map[string]toml.Primitive
		}
	)

	// Do the initial decode; reflection is delayed on Primitive values.
	var music classics
	md, err := toml.Decode(tomlBlob, &music)
	if err != nil {
		log.Fatal(err)
	}

	// MetaData still includes information on Primitive values.
	fmt.Printf("Is `bands.Springsteen` defined? %v\n",
		md.IsDefined("bands", "Springsteen"))

	// Decode primitive data into Go values.
	for _, artist := range music.Ranking {
		// A band is a primitive value, so we need to decode it to get a real
		// `band` value.
		primValue := music.Bands[artist]

		var aBand band
		err = md.PrimitiveDecode(primValue, &aBand)
		if err != nil {
			log.Fatal(err)
		}
		fmt.Printf("%s started in %d.\n", artist, aBand.Started)
	}

	// Check to see if there were any fields left undecoded. Note that this
	// won't be empty before decoding the Primitive value!
	fmt.Printf("Undecoded: %q\n", md.Undecoded())

}

Output:

Is `bands.Springsteen` defined? true
Springsteen started in 1973.
J Geils started in 1970.
Undecoded: []

func (md *MetaData) Type(key ...string) string

func (md *MetaData) Undecoded() []Key

type ParseError ¶ added in v0.4.1

type ParseError struct {
	Message  string   // Short technical message.
	Usage    string   // Longer message with usage guidance; may be blank.
	Position Position // Position of the error
	LastKey  string   // Last parsed key, may be blank.

	// Line the error occurred.
	//
	// Deprecated: use [Position].
	Line int
	// contains filtered or unexported fields
}

ParseError is returned when there is an error parsing the TOML syntax such as invalid syntax, duplicate keys, etc.

In addition to the error message itself, you can also print detailed location information with context by using [ErrorWithPosition]:

toml: error: Key 'fruit' was already created and cannot be used as an array.

At line 4, column 2-7:

      2 | fruit = []
      3 |
      4 | [[fruit]] # Not allowed
            ^^^^^

[ErrorWithUsage] can be used to print the above with some more detailed usage guidance:

toml: error: newlines not allowed within inline tables

At line 1, column 18:

      1 | x = [{ key = 42 #
                           ^

Error help:

  Inline tables must always be on a single line:

      table = {key = 42, second = 43}

  It is invalid to split them over multiple lines like so:

      # INVALID
      table = {
          key    = 42,
          second = 43
      }

  Use regular for this:

      [table]
      key    = 42
      second = 43

func (pe ParseError) Error() string

func (pe ParseError) ErrorWithPosition() string

func (pe ParseError) ErrorWithUsage() string

type Position ¶ added in v1.0.0

type Position struct {
	Line  int // Line number, starting at 1.
	Start int // Start of error, as byte offset starting at 0.
	Len   int // Lenght in bytes.
}

Position of an error.

func (p Position) String() string

type Primitive ¶

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

Primitive is a TOML value that hasn't been decoded into a Go value.

This type can be used for any value, which will cause decoding to be delayed. You can use PrimitiveDecode to "manually" decode these values.

NOTE: The underlying representation of a `Primitive` value is subject to change. Do not rely on it.

NOTE: Primitive values are still parsed, so using them will only avoid the overhead of reflection. They can be useful when you don't know the exact type of TOML data until runtime.

type Unmarshaler ¶

type Unmarshaler interface {
	UnmarshalTOML(interface{}) error
}

Unmarshaler is the interface implemented by objects that can unmarshal a TOML description of themselves.