1# go-toml
2
3Go library for the [TOML](https://github.com/mojombo/toml) format.
4
5This library supports TOML version
6[v1.0.0-rc.1](https://github.com/toml-lang/toml/blob/master/versions/en/toml-v1.0.0-rc.1.md)
7
8[![GoDoc](https://godoc.org/github.com/pelletier/go-toml?status.svg)](http://godoc.org/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## Features
16
17Go-toml provides the following features for using data parsed from TOML documents:
18
19* Load TOML documents from files and string data
20* Easily navigate TOML structure using Tree
21* Marshaling and unmarshaling to and from data structures
22* Line & column position data for all parsed elements
23* [Query support similar to JSON-Path](query/)
24* Syntax errors contain line and column numbers
25
26## Import
27
28```go
29import "github.com/pelletier/go-toml"
30```
31
32## Usage example
33
34Read a TOML document:
35
36```go
37config, _ := toml.Load(`
38[postgres]
39user = "pelletier"
40password = "mypassword"`)
41// retrieve data directly
42user := config.Get("postgres.user").(string)
43
44// or using an intermediate object
45postgresConfig := config.Get("postgres").(*toml.Tree)
46password := postgresConfig.Get("password").(string)
47```
48
49Or use Unmarshal:
50
51```go
52type Postgres struct {
53    User     string
54    Password string
55}
56type Config struct {
57    Postgres Postgres
58}
59
60doc := []byte(`
61[Postgres]
62User = "pelletier"
63Password = "mypassword"`)
64
65config := Config{}
66toml.Unmarshal(doc, &config)
67fmt.Println("user=", config.Postgres.User)
68```
69
70Or use a query:
71
72```go
73// use a query to gather elements without walking the tree
74q, _ := query.Compile("$..[user,password]")
75results := q.Execute(config)
76for ii, item := range results.Values() {
77    fmt.Printf("Query result %d: %v\n", ii, item)
78}
79```
80
81## Documentation
82
83The documentation and additional examples are available at
84[godoc.org](http://godoc.org/github.com/pelletier/go-toml).
85
86## Tools
87
88Go-toml provides two handy command line tools:
89
90* `tomll`: Reads TOML files and lints them.
91
92    ```
93    go install github.com/pelletier/go-toml/cmd/tomll
94    tomll --help
95    ```
96* `tomljson`: Reads a TOML file and outputs its JSON representation.
97
98    ```
99    go install github.com/pelletier/go-toml/cmd/tomljson
100    tomljson --help
101    ```
102
103 * `jsontoml`: Reads a JSON file and outputs a TOML representation.
104
105    ```
106    go install github.com/pelletier/go-toml/cmd/jsontoml
107    jsontoml --help
108    ```
109
110### Docker image
111
112Those tools are also availble as a Docker image from
113[dockerhub](https://hub.docker.com/r/pelletier/go-toml). For example, to
114use `tomljson`:
115
116```
117docker run -v $PWD:/workdir pelletier/go-toml tomljson /workdir/example.toml
118```
119
120Only master (`latest`) and tagged versions are published to dockerhub. You
121can build your own image as usual:
122
123```
124docker build -t go-toml .
125```
126
127## Contribute
128
129Feel free to report bugs and patches using GitHub's pull requests system on
130[pelletier/go-toml](https://github.com/pelletier/go-toml). Any feedback would be
131much appreciated!
132
133### Run tests
134
135`go test ./...`
136
137### Fuzzing
138
139The script `./fuzz.sh` is available to
140run [go-fuzz](https://github.com/dvyukov/go-fuzz) on go-toml.
141
142## Versioning
143
144Go-toml follows [Semantic Versioning](http://semver.org/). The supported version
145of [TOML](https://github.com/toml-lang/toml) is indicated at the beginning of
146this document. The last two major versions of Go are supported
147(see [Go Release Policy](https://golang.org/doc/devel/release.html#policy)).
148
149## License
150
151The MIT License (MIT). Read [LICENSE](LICENSE).
152