dnscrypt-proxy/vendor/github.com/BurntSushi/toml
Frank Denis 4f3ce0cbae Update deps 2023-06-18 04:19:52 +02:00
..
internal Update toml dependency 2021-08-08 10:21:25 +02:00
.gitignore Update toml dep 2022-07-21 19:02:28 +02:00
COPYING Update deps for Go 1.11 2018-10-02 18:06:43 +02:00
README.md Update toml dep 2022-07-21 19:02:28 +02:00
decode.go Update deps 2023-06-18 04:19:52 +02:00
decode_go116.go Update deps 2022-10-24 10:20:25 +02:00
deprecated.go Update quic-go to fix a regression 2023-06-01 11:32:10 +02:00
doc.go Update deps 2022-10-24 10:20:25 +02:00
encode.go Update deps 2023-06-18 04:19:52 +02:00
error.go Update quic-go to fix a regression 2023-06-01 11:32:10 +02:00
lex.go Update deps 2023-06-18 04:19:52 +02:00
meta.go Update deps 2023-06-18 04:19:52 +02:00
parse.go Update deps 2023-06-18 04:19:52 +02:00
type_fields.go Update BurntSushi/toml 2022-01-13 09:22:22 +01:00
type_toml.go Update BurntSushi/toml 2022-01-13 09:22:22 +01:00

README.md

TOML stands for Tom's Obvious, Minimal Language. This Go package provides a reflection interface similar to Go's standard library json and xml packages.

Compatible with TOML version v1.0.0.

Documentation: https://godocs.io/github.com/BurntSushi/toml

See the releases page for a changelog; this information is also in the git tag annotations (e.g. git show v0.4.0).

This library requires Go 1.13 or newer; add it to your go.mod with:

% go get github.com/BurntSushi/toml@latest

It also comes with a TOML validator CLI tool:

% go install github.com/BurntSushi/toml/cmd/tomlv@latest
% tomlv some-toml-file.toml

Examples

For the simplest example, consider some TOML file as just a list of keys and values:

Age = 25
Cats = [ "Cauchy", "Plato" ]
Pi = 3.14
Perfection = [ 6, 28, 496, 8128 ]
DOB = 1987-07-05T05:45:00Z

Which can be decoded with:

type Config struct {
	Age        int
	Cats       []string
	Pi         float64
	Perfection []int
	DOB        time.Time
}

var conf Config
_, err := toml.Decode(tomlData, &conf)

You can also use struct tags if your struct field name doesn't map to a TOML key value directly:

some_key_NAME = "wat"
type TOML struct {
    ObscureKey string `toml:"some_key_NAME"`
}

Beware that like other decoders only exported fields are considered when encoding and decoding; private fields are silently ignored.

Using the Marshaler and encoding.TextUnmarshaler interfaces

Here's an example that automatically parses values in a mail.Address:

contacts = [
    "Donald Duck <donald@duckburg.com>",
    "Scrooge McDuck <scrooge@duckburg.com>",
]

Can be decoded with:

// Create address type which satisfies the encoding.TextUnmarshaler interface.
type address struct {
	*mail.Address
}

func (a *address) UnmarshalText(text []byte) error {
	var err error
	a.Address, err = mail.ParseAddress(string(text))
	return err
}

// Decode it.
func decode() {
	blob := `
		contacts = [
			"Donald Duck <donald@duckburg.com>",
			"Scrooge McDuck <scrooge@duckburg.com>",
		]
	`

	var contacts struct {
		Contacts []address
	}

	_, err := toml.Decode(blob, &contacts)
	if err != nil {
		log.Fatal(err)
	}

	for _, c := range contacts.Contacts {
		fmt.Printf("%#v\n", c.Address)
	}

	// Output:
	// &mail.Address{Name:"Donald Duck", Address:"donald@duckburg.com"}
	// &mail.Address{Name:"Scrooge McDuck", Address:"scrooge@duckburg.com"}
}

To target TOML specifically you can implement UnmarshalTOML TOML interface in a similar way.

More complex usage

See the _example/ directory for a more complex example.