README.md
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[](http://godoc.org/github.com/pelletier/go-toml)
9[](https://github.com/pelletier/go-toml/blob/master/LICENSE)
10[](https://travis-ci.org/pelletier/go-toml)
11[](https://coveralls.io/github/pelletier/go-toml?branch=master)
12[](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 TomlTree
20* Line & column position data for all parsed elements
21* Query support similar to JSON-Path
22* Syntax errors contain line and column numbers
23
24Go-toml is designed to help cover use-cases not covered by reflection-based TOML parsing:
25
26* Semantic evaluation of parsed TOML
27* Informing a user of mistakes in the source document, after it has been parsed
28* Programatic handling of default values on a case-by-case basis
29* Using a TOML document as a flexible data-store
30
31## Import
32
33 import "github.com/pelletier/go-toml"
34
35## Usage
36
37### Example
38
39Say you have a TOML file that looks like this:
40
41```toml
42[postgres]
43user = "pelletier"
44password = "mypassword"
45```
46
47Read the username and password like this:
48
49```go
50import (
51 "fmt"
52 "github.com/pelletier/go-toml"
53)
54
55config, err := toml.LoadFile("config.toml")
56if err != nil {
57 fmt.Println("Error ", err.Error())
58} else {
59 // retrieve data directly
60 user := config.Get("postgres.user").(string)
61 password := config.Get("postgres.password").(string)
62
63 // or using an intermediate object
64 configTree := config.Get("postgres").(*toml.TomlTree)
65 user = configTree.Get("user").(string)
66 password = configTree.Get("password").(string)
67 fmt.Println("User is ", user, ". Password is ", password)
68
69 // show where elements are in the file
70 fmt.Println("User position: %v", configTree.GetPosition("user"))
71 fmt.Println("Password position: %v", configTree.GetPosition("password"))
72
73 // use a query to gather elements without walking the tree
74 results, _ := config.Query("$..[user,password]")
75 for ii, item := range results.Values() {
76 fmt.Println("Query result %d: %v", ii, item)
77 }
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 lint 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## Contribute
104
105Feel free to report bugs and patches using GitHub's pull requests system on
106[pelletier/go-toml](https://github.com/pelletier/go-toml). Any feedback would be
107much appreciated!
108
109### Run tests
110
111You have to make sure two kind of tests run:
112
1131. The Go unit tests
1142. The TOML examples base
115
116You can run both of them using `./test.sh`.
117
118## License
119
120The MIT License (MIT). Read [LICENSE](LICENSE).
121
){kind=link}
){kind=link}
){kind=link}
){kind=link}