README.md (2729B)
1 TOML stands for Tom's Obvious, Minimal Language. This Go package provides a 2 reflection interface similar to Go's standard library `json` and `xml` packages. 3 4 Compatible with TOML version [v1.0.0](https://toml.io/en/v1.0.0). 5 6 Documentation: https://godocs.io/github.com/BurntSushi/toml 7 8 See the [releases page](https://github.com/BurntSushi/toml/releases) for a 9 changelog; this information is also in the git tag annotations (e.g. `git show 10 v0.4.0`). 11 12 This library requires Go 1.18 or newer; add it to your go.mod with: 13 14 % go get github.com/BurntSushi/toml@latest 15 16 It also comes with a TOML validator CLI tool: 17 18 % go install github.com/BurntSushi/toml/cmd/tomlv@latest 19 % tomlv some-toml-file.toml 20 21 ### Examples 22 For the simplest example, consider some TOML file as just a list of keys and 23 values: 24 25 ```toml 26 Age = 25 27 Cats = [ "Cauchy", "Plato" ] 28 Pi = 3.14 29 Perfection = [ 6, 28, 496, 8128 ] 30 DOB = 1987-07-05T05:45:00Z 31 ``` 32 33 Which can be decoded with: 34 35 ```go 36 type Config struct { 37 Age int 38 Cats []string 39 Pi float64 40 Perfection []int 41 DOB time.Time 42 } 43 44 var conf Config 45 _, err := toml.Decode(tomlData, &conf) 46 ``` 47 48 You can also use struct tags if your struct field name doesn't map to a TOML key 49 value directly: 50 51 ```toml 52 some_key_NAME = "wat" 53 ``` 54 55 ```go 56 type TOML struct { 57 ObscureKey string `toml:"some_key_NAME"` 58 } 59 ``` 60 61 Beware that like other decoders **only exported fields** are considered when 62 encoding and decoding; private fields are silently ignored. 63 64 ### Using the `Marshaler` and `encoding.TextUnmarshaler` interfaces 65 Here's an example that automatically parses values in a `mail.Address`: 66 67 ```toml 68 contacts = [ 69 "Donald Duck <donald@duckburg.com>", 70 "Scrooge McDuck <scrooge@duckburg.com>", 71 ] 72 ``` 73 74 Can be decoded with: 75 76 ```go 77 // Create address type which satisfies the encoding.TextUnmarshaler interface. 78 type address struct { 79 *mail.Address 80 } 81 82 func (a *address) UnmarshalText(text []byte) error { 83 var err error 84 a.Address, err = mail.ParseAddress(string(text)) 85 return err 86 } 87 88 // Decode it. 89 func decode() { 90 blob := ` 91 contacts = [ 92 "Donald Duck <donald@duckburg.com>", 93 "Scrooge McDuck <scrooge@duckburg.com>", 94 ] 95 ` 96 97 var contacts struct { 98 Contacts []address 99 } 100 101 _, err := toml.Decode(blob, &contacts) 102 if err != nil { 103 log.Fatal(err) 104 } 105 106 for _, c := range contacts.Contacts { 107 fmt.Printf("%#v\n", c.Address) 108 } 109 110 // Output: 111 // &mail.Address{Name:"Donald Duck", Address:"donald@duckburg.com"} 112 // &mail.Address{Name:"Scrooge McDuck", Address:"scrooge@duckburg.com"} 113 } 114 ``` 115 116 To target TOML specifically you can implement `UnmarshalTOML` TOML interface in 117 a similar way. 118 119 ### More complex usage 120 See the [`_example/`](/_example) directory for a more complex example.