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