1# go-toml 2 3Go library for the [TOML](https://toml.io/) format. 4 5This library supports TOML version 6[v1.0.0-rc.3](https://toml.io/en/v1.0.0-rc.3) 7 8[![Go Reference](https://pkg.go.dev/badge/github.com/pelletier/go-toml.svg)](https://pkg.go.dev/github.com/pelletier/go-toml) 9[![license](https://img.shields.io/github/license/pelletier/go-toml.svg)](https://github.com/pelletier/go-toml/blob/master/LICENSE) 10[![Build Status](https://dev.azure.com/pelletierthomas/go-toml-ci/_apis/build/status/pelletier.go-toml?branchName=master)](https://dev.azure.com/pelletierthomas/go-toml-ci/_build/latest?definitionId=1&branchName=master) 11[![codecov](https://codecov.io/gh/pelletier/go-toml/branch/master/graph/badge.svg)](https://codecov.io/gh/pelletier/go-toml) 12[![Go Report Card](https://goreportcard.com/badge/github.com/pelletier/go-toml)](https://goreportcard.com/report/github.com/pelletier/go-toml) 13[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fpelletier%2Fgo-toml.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fpelletier%2Fgo-toml?ref=badge_shield) 14 15 16## Development status 17 18**ℹ️ Consider go-toml v2!** 19 20The next version of go-toml is in [active development][v2-dev], and 21[nearing completion][v2-map]. 22 23Though technically in beta, v2 is already more tested, [fixes bugs][v1-bugs], 24and [much faster][v2-bench]. If you only need reading and writing TOML documents 25(majority of cases), those features are implemented and the API unlikely to 26change. 27 28The remaining features (Document structure editing and tooling) will be added 29shortly. While pull-requests are welcome on v1, no active development is 30expected on it. When v2.0.0 is released, v1 will be deprecated. 31 32 [go-toml v2][v2] 33 34[v2]: https://github.com/pelletier/go-toml/tree/v2 35[v2-map]: https://github.com/pelletier/go-toml/discussions/506 36[v2-dev]: https://github.com/pelletier/go-toml/tree/v2 37[v1-bugs]: https://github.com/pelletier/go-toml/issues?q=is%3Aissue+is%3Aopen+label%3Av2-fixed 38[v2-bench]: https://github.com/pelletier/go-toml/tree/v2#benchmarks 39 40## Features 41 42Go-toml provides the following features for using data parsed from TOML documents: 43 44* Load TOML documents from files and string data 45* Easily navigate TOML structure using Tree 46* Marshaling and unmarshaling to and from data structures 47* Line & column position data for all parsed elements 48* [Query support similar to JSON-Path](query/) 49* Syntax errors contain line and column numbers 50 51## Import 52 53```go 54import "github.com/pelletier/go-toml" 55``` 56 57## Usage example 58 59Read a TOML document: 60 61```go 62config, _ := toml.Load(` 63[postgres] 64user = "pelletier" 65password = "mypassword"`) 66// retrieve data directly 67user := config.Get("postgres.user").(string) 68 69// or using an intermediate object 70postgresConfig := config.Get("postgres").(*toml.Tree) 71password := postgresConfig.Get("password").(string) 72``` 73 74Or use Unmarshal: 75 76```go 77type Postgres struct { 78 User string 79 Password string 80} 81type Config struct { 82 Postgres Postgres 83} 84 85doc := []byte(` 86[Postgres] 87User = "pelletier" 88Password = "mypassword"`) 89 90config := Config{} 91toml.Unmarshal(doc, &config) 92fmt.Println("user=", config.Postgres.User) 93``` 94 95Or use a query: 96 97```go 98// use a query to gather elements without walking the tree 99q, _ := query.Compile("$..[user,password]") 100results := q.Execute(config) 101for ii, item := range results.Values() { 102 fmt.Printf("Query result %d: %v\n", ii, item) 103} 104``` 105 106## Documentation 107 108The documentation and additional examples are available at 109[pkg.go.dev](https://pkg.go.dev/github.com/pelletier/go-toml). 110 111## Tools 112 113Go-toml provides three handy command line tools: 114 115* `tomll`: Reads TOML files and lints them. 116 117 ``` 118 go install github.com/pelletier/go-toml/cmd/tomll 119 tomll --help 120 ``` 121* `tomljson`: Reads a TOML file and outputs its JSON representation. 122 123 ``` 124 go install github.com/pelletier/go-toml/cmd/tomljson 125 tomljson --help 126 ``` 127 128 * `jsontoml`: Reads a JSON file and outputs a TOML representation. 129 130 ``` 131 go install github.com/pelletier/go-toml/cmd/jsontoml 132 jsontoml --help 133 ``` 134 135### Docker image 136 137Those tools are also available as a Docker image from 138[dockerhub](https://hub.docker.com/r/pelletier/go-toml). For example, to 139use `tomljson`: 140 141``` 142docker run -v $PWD:/workdir pelletier/go-toml tomljson /workdir/example.toml 143``` 144 145Only master (`latest`) and tagged versions are published to dockerhub. You 146can build your own image as usual: 147 148``` 149docker build -t go-toml . 150``` 151 152## Contribute 153 154Feel free to report bugs and patches using GitHub's pull requests system on 155[pelletier/go-toml](https://github.com/pelletier/go-toml). Any feedback would be 156much appreciated! 157 158### Run tests 159 160`go test ./...` 161 162### Fuzzing 163 164The script `./fuzz.sh` is available to 165run [go-fuzz](https://github.com/dvyukov/go-fuzz) on go-toml. 166 167## Versioning 168 169Go-toml follows [Semantic Versioning](http://semver.org/). The supported version 170of [TOML](https://github.com/toml-lang/toml) is indicated at the beginning of 171this document. The last two major versions of Go are supported 172(see [Go Release Policy](https://golang.org/doc/devel/release.html#policy)). 173 174## License 175 176The MIT License (MIT) + Apache 2.0. Read [LICENSE](LICENSE). 177