1 # go-toml |
1 # go-toml |
2 |
2 |
3 Go library for the [TOML](https://github.com/mojombo/toml) format. |
3 Go library for the [TOML](https://toml.io/) format. |
4 |
4 |
5 This library supports TOML version |
5 This library supports TOML version |
6 [v0.5.0](https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.5.0.md) |
6 [v1.0.0-rc.3](https://toml.io/en/v1.0.0-rc.3) |
7 |
7 |
8 [](http://godoc.org/github.com/pelletier/go-toml) |
8 [](https://pkg.go.dev/github.com/pelletier/go-toml) |
9 [](https://github.com/pelletier/go-toml/blob/master/LICENSE) |
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) |
10 [](https://dev.azure.com/pelletierthomas/go-toml-ci/_build/latest?definitionId=1&branchName=master) |
11 [](https://codecov.io/gh/pelletier/go-toml) |
11 [](https://codecov.io/gh/pelletier/go-toml) |
12 [](https://goreportcard.com/report/github.com/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) |
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 (Document structure editing and tooling) will be added |
|
29 shortly. While pull-requests are welcome on v1, no active development is |
|
30 expected on it. When v2.0.0 is released, v1 will be 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 |
14 |
39 |
15 ## Features |
40 ## Features |
16 |
41 |
17 Go-toml provides the following features for using data parsed from TOML documents: |
42 Go-toml provides the following features for using data parsed from TOML documents: |
18 |
43 |
19 * Load TOML documents from files and string data |
44 * Load TOML documents from files and string data |
20 * Easily navigate TOML structure using Tree |
45 * Easily navigate TOML structure using Tree |
21 * Mashaling and unmarshaling to and from data structures |
46 * Marshaling and unmarshaling to and from data structures |
22 * Line & column position data for all parsed elements |
47 * Line & column position data for all parsed elements |
23 * [Query support similar to JSON-Path](query/) |
48 * [Query support similar to JSON-Path](query/) |
24 * Syntax errors contain line and column numbers |
49 * Syntax errors contain line and column numbers |
25 |
50 |
26 ## Import |
51 ## Import |
72 ```go |
97 ```go |
73 // use a query to gather elements without walking the tree |
98 // use a query to gather elements without walking the tree |
74 q, _ := query.Compile("$..[user,password]") |
99 q, _ := query.Compile("$..[user,password]") |
75 results := q.Execute(config) |
100 results := q.Execute(config) |
76 for ii, item := range results.Values() { |
101 for ii, item := range results.Values() { |
77 fmt.Println("Query result %d: %v", ii, item) |
102 fmt.Printf("Query result %d: %v\n", ii, item) |
78 } |
103 } |
79 ``` |
104 ``` |
80 |
105 |
81 ## Documentation |
106 ## Documentation |
82 |
107 |
83 The documentation and additional examples are available at |
108 The documentation and additional examples are available at |
84 [godoc.org](http://godoc.org/github.com/pelletier/go-toml). |
109 [pkg.go.dev](https://pkg.go.dev/github.com/pelletier/go-toml). |
85 |
110 |
86 ## Tools |
111 ## Tools |
87 |
112 |
88 Go-toml provides two handy command line tools: |
113 Go-toml provides three handy command line tools: |
89 |
114 |
90 * `tomll`: Reads TOML files and lint them. |
115 * `tomll`: Reads TOML files and lints them. |
91 |
116 |
92 ``` |
117 ``` |
93 go install github.com/pelletier/go-toml/cmd/tomll |
118 go install github.com/pelletier/go-toml/cmd/tomll |
94 tomll --help |
119 tomll --help |
95 ``` |
120 ``` |
97 |
122 |
98 ``` |
123 ``` |
99 go install github.com/pelletier/go-toml/cmd/tomljson |
124 go install github.com/pelletier/go-toml/cmd/tomljson |
100 tomljson --help |
125 tomljson --help |
101 ``` |
126 ``` |
102 |
127 |
103 * `jsontoml`: Reads a JSON file and outputs a TOML representation. |
128 * `jsontoml`: Reads a JSON file and outputs a TOML representation. |
104 |
129 |
105 ``` |
130 ``` |
106 go install github.com/pelletier/go-toml/cmd/jsontoml |
131 go install github.com/pelletier/go-toml/cmd/jsontoml |
107 jsontoml --help |
132 jsontoml --help |
108 ``` |
133 ``` |
109 |
134 |
110 ### Docker image |
135 ### Docker image |
111 |
136 |
112 Those tools are also availble as a Docker image from |
137 Those tools are also available as a Docker image from |
113 [dockerhub](https://hub.docker.com/r/pelletier/go-toml). For example, to |
138 [dockerhub](https://hub.docker.com/r/pelletier/go-toml). For example, to |
114 use `tomljson`: |
139 use `tomljson`: |
115 |
140 |
116 ``` |
141 ``` |
117 docker run -v $PWD:/workdir pelletier/go-toml tomljson /workdir/example.toml |
142 docker run -v $PWD:/workdir pelletier/go-toml tomljson /workdir/example.toml |