1 # go-toml |
|
2 |
|
3 Go library for the [TOML](https://toml.io/) format. |
|
4 |
|
5 This 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 |
|
20 The next version of go-toml is in [active development][v2-dev], and |
|
21 [nearing completion][v2-map]. |
|
22 |
|
23 Though technically in beta, v2 is already more tested, [fixes bugs][v1-bugs], |
|
24 and [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 |
|
26 change. |
|
27 |
|
28 The remaining features will be added shortly. While pull-requests are welcome on |
|
29 v1, no active development is expected on it. When v2.0.0 is released, v1 will be |
|
30 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 |
|
42 Go-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 |
|
54 import "github.com/pelletier/go-toml" |
|
55 ``` |
|
56 |
|
57 ## Usage example |
|
58 |
|
59 Read a TOML document: |
|
60 |
|
61 ```go |
|
62 config, _ := toml.Load(` |
|
63 [postgres] |
|
64 user = "pelletier" |
|
65 password = "mypassword"`) |
|
66 // retrieve data directly |
|
67 user := config.Get("postgres.user").(string) |
|
68 |
|
69 // or using an intermediate object |
|
70 postgresConfig := config.Get("postgres").(*toml.Tree) |
|
71 password := postgresConfig.Get("password").(string) |
|
72 ``` |
|
73 |
|
74 Or use Unmarshal: |
|
75 |
|
76 ```go |
|
77 type Postgres struct { |
|
78 User string |
|
79 Password string |
|
80 } |
|
81 type Config struct { |
|
82 Postgres Postgres |
|
83 } |
|
84 |
|
85 doc := []byte(` |
|
86 [Postgres] |
|
87 User = "pelletier" |
|
88 Password = "mypassword"`) |
|
89 |
|
90 config := Config{} |
|
91 toml.Unmarshal(doc, &config) |
|
92 fmt.Println("user=", config.Postgres.User) |
|
93 ``` |
|
94 |
|
95 Or use a query: |
|
96 |
|
97 ```go |
|
98 // use a query to gather elements without walking the tree |
|
99 q, _ := query.Compile("$..[user,password]") |
|
100 results := q.Execute(config) |
|
101 for ii, item := range results.Values() { |
|
102 fmt.Printf("Query result %d: %v\n", ii, item) |
|
103 } |
|
104 ``` |
|
105 |
|
106 ## Documentation |
|
107 |
|
108 The documentation and additional examples are available at |
|
109 [pkg.go.dev](https://pkg.go.dev/github.com/pelletier/go-toml). |
|
110 |
|
111 ## Tools |
|
112 |
|
113 Go-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 |
|
137 Those tools are also available as a Docker image from |
|
138 [dockerhub](https://hub.docker.com/r/pelletier/go-toml). For example, to |
|
139 use `tomljson`: |
|
140 |
|
141 ``` |
|
142 docker run -v $PWD:/workdir pelletier/go-toml tomljson /workdir/example.toml |
|
143 ``` |
|
144 |
|
145 Only master (`latest`) and tagged versions are published to dockerhub. You |
|
146 can build your own image as usual: |
|
147 |
|
148 ``` |
|
149 docker build -t go-toml . |
|
150 ``` |
|
151 |
|
152 ## Contribute |
|
153 |
|
154 Feel 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 |
|
156 much appreciated! |
|
157 |
|
158 ### Run tests |
|
159 |
|
160 `go test ./...` |
|
161 |
|
162 ### Fuzzing |
|
163 |
|
164 The script `./fuzz.sh` is available to |
|
165 run [go-fuzz](https://github.com/dvyukov/go-fuzz) on go-toml. |
|
166 |
|
167 ## Versioning |
|
168 |
|
169 Go-toml follows [Semantic Versioning](http://semver.org/). The supported version |
|
170 of [TOML](https://github.com/toml-lang/toml) is indicated at the beginning of |
|
171 this 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 |
|
176 The MIT License (MIT) + Apache 2.0. Read [LICENSE](LICENSE). |
|