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