diff options
Diffstat (limited to 'vendor/github.com/BurntSushi/toml/README.md')
| -rw-r--r-- | vendor/github.com/BurntSushi/toml/README.md | 74 |
1 files changed, 38 insertions, 36 deletions
diff --git a/vendor/github.com/BurntSushi/toml/README.md b/vendor/github.com/BurntSushi/toml/README.md index 7c1b37ecc..64410cf75 100644 --- a/vendor/github.com/BurntSushi/toml/README.md +++ b/vendor/github.com/BurntSushi/toml/README.md @@ -6,27 +6,22 @@ packages. This package also supports the `encoding.TextUnmarshaler` and `encoding.TextMarshaler` interfaces so that you can define custom data representations. (There is an example of this below.) -Spec: https://github.com/toml-lang/toml +Compatible with TOML version [v1.0.0](https://toml.io/en/v1.0.0). -Compatible with TOML version -[v0.4.0](https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.4.0.md) +Documentation: https://godocs.io/github.com/BurntSushi/toml -Documentation: https://godoc.org/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`). -Installation: +This library requires Go 1.13 or newer; install it with: -```bash -go get github.com/BurntSushi/toml -``` - -Try the toml validator: + $ go get github.com/BurntSushi/toml -```bash -go get github.com/BurntSushi/toml/cmd/tomlv -tomlv some-toml-file.toml -``` +It also comes with a TOML validator CLI tool: -[](https://travis-ci.org/BurntSushi/toml) [](https://godoc.org/github.com/BurntSushi/toml) + $ go get github.com/BurntSushi/toml/cmd/tomlv + $ tomlv some-toml-file.toml ### Testing @@ -36,8 +31,8 @@ and the encoder. ### Examples -This package works similarly to how the Go standard library handles `XML` -and `JSON`. Namely, data is loaded into Go values via reflection. +This package works similarly to how the Go standard library handles XML and +JSON. Namely, data is loaded into Go values via reflection. For the simplest example, consider some TOML file as just a list of keys and values: @@ -54,11 +49,11 @@ Which could be defined in Go as: ```go type Config struct { - Age int - Cats []string - Pi float64 - Perfection []int - DOB time.Time // requires `import time` + Age int + Cats []string + Pi float64 + Perfection []int + DOB time.Time // requires `import time` } ``` @@ -84,6 +79,9 @@ type TOML struct { } ``` +Beware that like other most other decoders **only exported fields** are +considered when encoding and decoding; private fields are silently ignored. + ### Using the `encoding.TextUnmarshaler` interface Here's an example that automatically parses duration strings into @@ -103,19 +101,19 @@ Which can be decoded with: ```go type song struct { - Name string - Duration duration + Name string + Duration duration } type songs struct { - Song []song + Song []song } var favorites songs if _, err := toml.Decode(blob, &favorites); err != nil { - log.Fatal(err) + log.Fatal(err) } for _, s := range favorites.Song { - fmt.Printf("%s (%s)\n", s.Name, s.Duration) + fmt.Printf("%s (%s)\n", s.Name, s.Duration) } ``` @@ -134,6 +132,9 @@ func (d *duration) UnmarshalText(text []byte) error { } ``` +To target TOML specifically you can implement `UnmarshalTOML` TOML interface in +a similar way. + ### More complex usage Here's an example of how to load the example from the official spec page: @@ -180,23 +181,23 @@ And the corresponding Go types are: ```go type tomlConfig struct { - Title string - Owner ownerInfo - DB database `toml:"database"` + Title string + Owner ownerInfo + DB database `toml:"database"` Servers map[string]server Clients clients } type ownerInfo struct { Name string - Org string `toml:"organization"` - Bio string - DOB time.Time + Org string `toml:"organization"` + Bio string + DOB time.Time } type database struct { - Server string - Ports []int + Server string + Ports []int ConnMax int `toml:"connection_max"` Enabled bool } @@ -207,7 +208,7 @@ type server struct { } type clients struct { - Data [][]interface{} + Data [][]interface{} Hosts []string } ``` @@ -216,3 +217,4 @@ Note that a case insensitive match will be tried if an exact match can't be found. A working example of the above can be found in `_examples/example.{go,toml}`. + |