README.md
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[](https://pkg.go.dev/github.com/pelletier/go-toml)
9[](https://github.com/pelletier/go-toml/blob/master/LICENSE)
10[](https://dev.azure.com/pelletierthomas/go-toml-ci/_build/latest?definitionId=1&branchName=master)
11[](https://codecov.io/gh/pelletier/go-toml)
12[](https://goreportcard.com/report/github.com/pelletier/go-toml)
13[](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
){kind=link}
){kind=link}
){kind=link}
){kind=link}