0884f89431
* start pulling out + replacing urfave and config * replace many many instances of config * move more stuff => viper * properly remove urfave * move some flags to root command * add testrig commands to root * alias config file keys * start adding cli parsing tests * reorder viper init * remove config path alias * fmt * change config file keys to non-nested * we're more or less in business now * tidy up the common func * go fmt * get tests passing again * add note about the cliparsing tests * reorganize * update docs with changes * structure cmd dir better * rename + move some files around * fix dangling comma
5.1 KiB
go-toml
Go library for the TOML format.
This library supports TOML version v1.0.0-rc.3
Development status
ℹ️ Consider go-toml v2!
The next version of go-toml is in active development, and nearing completion.
Though technically in beta, v2 is already more tested, fixes bugs, and much faster. If you only need reading and writing TOML documents (majority of cases), those features are implemented and the API unlikely to change.
The remaining features (Document structure editing and tooling) will be added shortly. While pull-requests are welcome on v1, no active development is expected on it. When v2.0.0 is released, v1 will be deprecated.
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
- Syntax errors contain line and column numbers
Import
import "github.com/pelletier/go-toml"
Usage example
Read a TOML document:
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:
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:
// 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.
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 available as a Docker image from
dockerhub. 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. Any feedback would be much appreciated!
Run tests
go test ./...
Fuzzing
The script ./fuzz.sh is available to
run go-fuzz on go-toml.
Versioning
Go-toml follows Semantic Versioning. The supported version of TOML is indicated at the beginning of this document. The last two major versions of Go are supported (see Go Release Policy).
License
The MIT License (MIT) + Apache 2.0. Read LICENSE.