792b4dba2c
* update github.com/blevesearch/bleve v2.0.2 -> v2.0.3 * github.com/denisenkom/go-mssqldb v0.9.0 -> v0.10.0 * github.com/editorconfig/editorconfig-core-go v2.4.1 -> v2.4.2 * github.com/go-chi/cors v1.1.1 -> v1.2.0 * github.com/go-git/go-billy v5.0.0 -> v5.1.0 * github.com/go-git/go-git v5.2.0 -> v5.3.0 * github.com/go-ldap/ldap v3.2.4 -> v3.3.0 * github.com/go-redis/redis v8.6.0 -> v8.8.2 * github.com/go-sql-driver/mysql v1.5.0 -> v1.6.0 * github.com/go-swagger/go-swagger v0.26.1 -> v0.27.0 * github.com/lib/pq v1.9.0 -> v1.10.1 * github.com/mattn/go-sqlite3 v1.14.6 -> v1.14.7 * github.com/go-testfixtures/testfixtures v3.5.0 -> v3.6.0 * github.com/issue9/identicon v1.0.1 -> v1.2.0 * github.com/klauspost/compress v1.11.8 -> v1.12.1 * github.com/mgechev/revive v1.0.3 -> v1.0.6 * github.com/microcosm-cc/bluemonday v1.0.7 -> v1.0.8 * github.com/niklasfasching/go-org v1.4.0 -> v1.5.0 * github.com/olivere/elastic v7.0.22 -> v7.0.24 * github.com/pelletier/go-toml v1.8.1 -> v1.9.0 * github.com/prometheus/client_golang v1.9.0 -> v1.10.0 * github.com/xanzy/go-gitlab v0.44.0 -> v0.48.0 * github.com/yuin/goldmark v1.3.3 -> v1.3.5 * github.com/6543/go-version v1.2.4 -> v1.3.1 * do github.com/lib/pq v1.10.0 -> v1.10.1 again ...
152 lines
4.1 KiB
Markdown
Vendored
152 lines
4.1 KiB
Markdown
Vendored
# go-toml
|
|
|
|
Go library for the [TOML](https://toml.io/) format.
|
|
|
|
This library supports TOML version
|
|
[v1.0.0-rc.3](https://toml.io/en/v1.0.0-rc.3)
|
|
|
|
[](https://pkg.go.dev/github.com/pelletier/go-toml)
|
|
[](https://github.com/pelletier/go-toml/blob/master/LICENSE)
|
|
[](https://dev.azure.com/pelletierthomas/go-toml-ci/_build/latest?definitionId=1&branchName=master)
|
|
[](https://codecov.io/gh/pelletier/go-toml)
|
|
[](https://goreportcard.com/report/github.com/pelletier/go-toml)
|
|
[](https://app.fossa.io/projects/git%2Bgithub.com%2Fpelletier%2Fgo-toml?ref=badge_shield)
|
|
|
|
## Features
|
|
|
|
Go-toml provides the following features for using data parsed from TOML documents:
|
|
|
|
* Load TOML documents from files and string data
|
|
* Easily navigate TOML structure using Tree
|
|
* Marshaling and unmarshaling to and from data structures
|
|
* Line & column position data for all parsed elements
|
|
* [Query support similar to JSON-Path](query/)
|
|
* Syntax errors contain line and column numbers
|
|
|
|
## Import
|
|
|
|
```go
|
|
import "github.com/pelletier/go-toml"
|
|
```
|
|
|
|
## Usage example
|
|
|
|
Read a TOML document:
|
|
|
|
```go
|
|
config, _ := toml.Load(`
|
|
[postgres]
|
|
user = "pelletier"
|
|
password = "mypassword"`)
|
|
// retrieve data directly
|
|
user := config.Get("postgres.user").(string)
|
|
|
|
// or using an intermediate object
|
|
postgresConfig := config.Get("postgres").(*toml.Tree)
|
|
password := postgresConfig.Get("password").(string)
|
|
```
|
|
|
|
Or use Unmarshal:
|
|
|
|
```go
|
|
type Postgres struct {
|
|
User string
|
|
Password string
|
|
}
|
|
type Config struct {
|
|
Postgres Postgres
|
|
}
|
|
|
|
doc := []byte(`
|
|
[Postgres]
|
|
User = "pelletier"
|
|
Password = "mypassword"`)
|
|
|
|
config := Config{}
|
|
toml.Unmarshal(doc, &config)
|
|
fmt.Println("user=", config.Postgres.User)
|
|
```
|
|
|
|
Or use a query:
|
|
|
|
```go
|
|
// use a query to gather elements without walking the tree
|
|
q, _ := query.Compile("$..[user,password]")
|
|
results := q.Execute(config)
|
|
for ii, item := range results.Values() {
|
|
fmt.Printf("Query result %d: %v\n", ii, item)
|
|
}
|
|
```
|
|
|
|
## Documentation
|
|
|
|
The documentation and additional examples are available at
|
|
[pkg.go.dev](https://pkg.go.dev/github.com/pelletier/go-toml).
|
|
|
|
## Tools
|
|
|
|
Go-toml provides three handy command line tools:
|
|
|
|
* `tomll`: Reads TOML files and lints them.
|
|
|
|
```
|
|
go install github.com/pelletier/go-toml/cmd/tomll
|
|
tomll --help
|
|
```
|
|
* `tomljson`: Reads a TOML file and outputs its JSON representation.
|
|
|
|
```
|
|
go install github.com/pelletier/go-toml/cmd/tomljson
|
|
tomljson --help
|
|
```
|
|
|
|
* `jsontoml`: Reads a JSON file and outputs a TOML representation.
|
|
|
|
```
|
|
go install github.com/pelletier/go-toml/cmd/jsontoml
|
|
jsontoml --help
|
|
```
|
|
|
|
### Docker image
|
|
|
|
Those tools are also availble as a Docker image from
|
|
[dockerhub](https://hub.docker.com/r/pelletier/go-toml). For example, to
|
|
use `tomljson`:
|
|
|
|
```
|
|
docker run -v $PWD:/workdir pelletier/go-toml tomljson /workdir/example.toml
|
|
```
|
|
|
|
Only master (`latest`) and tagged versions are published to dockerhub. You
|
|
can build your own image as usual:
|
|
|
|
```
|
|
docker build -t go-toml .
|
|
```
|
|
|
|
## Contribute
|
|
|
|
Feel free to report bugs and patches using GitHub's pull requests system on
|
|
[pelletier/go-toml](https://github.com/pelletier/go-toml). Any feedback would be
|
|
much appreciated!
|
|
|
|
### Run tests
|
|
|
|
`go test ./...`
|
|
|
|
### Fuzzing
|
|
|
|
The script `./fuzz.sh` is available to
|
|
run [go-fuzz](https://github.com/dvyukov/go-fuzz) on go-toml.
|
|
|
|
## Versioning
|
|
|
|
Go-toml follows [Semantic Versioning](http://semver.org/). The supported version
|
|
of [TOML](https://github.com/toml-lang/toml) is indicated at the beginning of
|
|
this document. The last two major versions of Go are supported
|
|
(see [Go Release Policy](https://golang.org/doc/devel/release.html#policy)).
|
|
|
|
## License
|
|
|
|
The MIT License (MIT). Read [LICENSE](LICENSE).
|