summaryrefslogtreecommitdiff
path: root/vendor/github.com/BurntSushi/toml/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/github.com/BurntSushi/toml/README.md')
-rw-r--r--vendor/github.com/BurntSushi/toml/README.md74
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:
-[![Build Status](https://travis-ci.org/BurntSushi/toml.svg?branch=master)](https://travis-ci.org/BurntSushi/toml) [![GoDoc](https://godoc.org/github.com/BurntSushi/toml?status.svg)](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}`.
+