Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/BurntSushi/toml

TOML parser for Golang with reflection.
https://github.com/BurntSushi/toml

Last synced: about 1 month ago
JSON representation

TOML parser for Golang with reflection.

Lists

README 

        
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](https://toml.io/en/v1.0.0).



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



See the [releases page](https://github.com/BurntSushi/toml/releases) 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:



```toml

Age = 25

Cats = [ "Cauchy", "Plato" ]

Pi = 3.14

Perfection = [ 6, 28, 496, 8128 ]

DOB = 1987-07-05T05:45:00Z

```



Which can be decoded with:



```go

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:



```toml

some_key_NAME = "wat"

```



```go

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`:



```toml

contacts = [

    "Donald Duck ",

    "Scrooge McDuck ",

]

```



Can be decoded with:



```go

// 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 ",

			"Scrooge McDuck ",

		]

	`



	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:"[email protected]"}

	// &mail.Address{Name:"Scrooge McDuck", Address:"[email protected]"}

}

```



To target TOML specifically you can implement `UnmarshalTOML` TOML interface in

a similar way.



### More complex usage

See the [`_example/`](/_example) directory for a more complex example.