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[![Coverage Status](https://coveralls.io/repos/github/pelletier/go-toml/badge.svg?branch=master)](https://coveralls.io/github/pelletier/go-toml?branch=master)
12[![Go Report Card](https://goreportcard.com/badge/github.com/pelletier/go-toml)](https://goreportcard.com/report/github.com/pelletier/go-toml)
13
14## Features
15
16Go-toml provides the following features for using data parsed from TOML documents:
17
18* Load TOML documents from files and string data
19* Easily navigate TOML structure using Tree
20* Mashaling and unmarshaling to and from data structures
21* Line & column position data for all parsed elements
22* [Query support similar to JSON-Path](query/)
23* Syntax errors contain line and column numbers
24
25## Import
26
27```go
28import "github.com/pelletier/go-toml"
29```
30
31## Usage example
32
33Read a TOML document:
34
35```go
36config, _ := toml.LoadString(`
37[postgres]
38user = "pelletier"
39password = "mypassword"`)
40// retrieve data directly
41user := config.Get("postgres.user").(string)
42
43// or using an intermediate object
44postgresConfig := config.Get("postgres").(*toml.Tree)
45password = postgresConfig.Get("password").(string)
46```
47
48Or use Unmarshal:
49
50```go
51type Postgres struct {
52    User     string
53    Password string
54}
55type Config struct {
56    Postgres Postgres
57}
58
59doc := []byte(`
60[postgres]
61user = "pelletier"
62password = "mypassword"`)
63
64config := Config{}
65Unmarshal(doc, &config)
66fmt.Println("user=", config.Postgres.User)
67```
68
69Or use a query:
70
71```go
72// use a query to gather elements without walking the tree
73results, _ := config.Query("$..[user,password]")
74for ii, item := range results.Values() {
75    fmt.Println("Query result %d: %v", ii, item)
76}
77```
78
79## Documentation
80
81The documentation and additional examples are available at
82[godoc.org](http://godoc.org/github.com/pelletier/go-toml).
83
84## Tools
85
86Go-toml provides two handy command line tools:
87
88* `tomll`: Reads TOML files and lint them.
89
90    ```
91    go install github.com/pelletier/go-toml/cmd/tomll
92    tomll --help
93    ```
94* `tomljson`: Reads a TOML file and outputs its JSON representation.
95
96    ```
97    go install github.com/pelletier/go-toml/cmd/tomljson
98    tomljson --help
99    ```
100
101## Contribute
102
103Feel free to report bugs and patches using GitHub's pull requests system on
104[pelletier/go-toml](https://github.com/pelletier/go-toml). Any feedback would be
105much appreciated!
106
107### Run tests
108
109You have to make sure two kind of tests run:
110
1111. The Go unit tests
1122. The TOML examples base
113
114You can run both of them using `./test.sh`.
115
116## License
117
118The MIT License (MIT). Read [LICENSE](LICENSE).
119