Thomas Pelletier
23f644976a
Move all the query system to its own package. The reason is to avoid it to rely on unexported methods and structures, and move it out of the main package since this is really not a core feature. It is still tied to the toml.TomlTree and toml.Position structures for now. * Move query mechanism to its own subpackage * Rename QueryResult to Result to avoid stutter * Add query.CompileAndExecute Fixes #116
121 lines
3.6 KiB
Markdown
121 lines
3.6 KiB
Markdown
# go-toml
|
|
|
|
Go library for the [TOML](https://github.com/mojombo/toml) format.
|
|
|
|
This library supports TOML version
|
|
[v0.4.0](https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.4.0.md)
|
|
|
|
[](http://godoc.org/github.com/pelletier/go-toml)
|
|
[](https://github.com/pelletier/go-toml/blob/master/LICENSE)
|
|
[](https://travis-ci.org/pelletier/go-toml)
|
|
[](https://coveralls.io/github/pelletier/go-toml?branch=master)
|
|
[](https://goreportcard.com/report/github.com/pelletier/go-toml)
|
|
|
|
## 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 TomlTree
|
|
* Line & column position data for all parsed elements
|
|
* [Query support similar to JSON-Path](query/)
|
|
* Syntax errors contain line and column numbers
|
|
|
|
Go-toml is designed to help cover use-cases not covered by reflection-based TOML parsing:
|
|
|
|
* Semantic evaluation of parsed TOML
|
|
* Informing a user of mistakes in the source document, after it has been parsed
|
|
* Programatic handling of default values on a case-by-case basis
|
|
* Using a TOML document as a flexible data-store
|
|
|
|
## Import
|
|
|
|
import "github.com/pelletier/go-toml"
|
|
|
|
## Usage
|
|
|
|
### Example
|
|
|
|
Say you have a TOML file that looks like this:
|
|
|
|
```toml
|
|
[postgres]
|
|
user = "pelletier"
|
|
password = "mypassword"
|
|
```
|
|
|
|
Read the username and password like this:
|
|
|
|
```go
|
|
import (
|
|
"fmt"
|
|
"github.com/pelletier/go-toml"
|
|
)
|
|
|
|
config, err := toml.LoadFile("config.toml")
|
|
if err != nil {
|
|
fmt.Println("Error ", err.Error())
|
|
} else {
|
|
// retrieve data directly
|
|
user := config.Get("postgres.user").(string)
|
|
password := config.Get("postgres.password").(string)
|
|
|
|
// or using an intermediate object
|
|
configTree := config.Get("postgres").(*toml.TomlTree)
|
|
user = configTree.Get("user").(string)
|
|
password = configTree.Get("password").(string)
|
|
fmt.Println("User is ", user, ". Password is ", password)
|
|
|
|
// show where elements are in the file
|
|
fmt.Println("User position: %v", configTree.GetPosition("user"))
|
|
fmt.Println("Password position: %v", configTree.GetPosition("password"))
|
|
|
|
// use a query to gather elements without walking the tree
|
|
results, _ := config.Query("$..[user,password]")
|
|
for ii, item := range results.Values() {
|
|
fmt.Println("Query result %d: %v", ii, item)
|
|
}
|
|
}
|
|
```
|
|
|
|
## Documentation
|
|
|
|
The documentation and additional examples are available at
|
|
[godoc.org](http://godoc.org/github.com/pelletier/go-toml).
|
|
|
|
## Tools
|
|
|
|
Go-toml provides two handy command line tools:
|
|
|
|
* `tomll`: Reads TOML files and lint 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
|
|
```
|
|
|
|
## 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
|
|
|
|
You have to make sure two kind of tests run:
|
|
|
|
1. The Go unit tests
|
|
2. The TOML examples base
|
|
|
|
You can run both of them using `./test.sh`.
|
|
|
|
## License
|
|
|
|
The MIT License (MIT). Read [LICENSE](LICENSE).
|