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.Load(` 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{} 65toml.Unmarshal(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 73q, _ := query.Compile("$..[user,password]") 74results := q.Execute(config) 75for ii, item := range results.Values() { 76 fmt.Println("Query result %d: %v", ii, item) 77} 78``` 79 80## Documentation 81 82The documentation and additional examples are available at 83[godoc.org](http://godoc.org/github.com/pelletier/go-toml). 84 85## Tools 86 87Go-toml provides two handy command line tools: 88 89* `tomll`: Reads TOML files and lint them. 90 91 ``` 92 go install github.com/pelletier/go-toml/cmd/tomll 93 tomll --help 94 ``` 95* `tomljson`: Reads a TOML file and outputs its JSON representation. 96 97 ``` 98 go install github.com/pelletier/go-toml/cmd/tomljson 99 tomljson --help 100 ``` 101 102## Contribute 103 104Feel free to report bugs and patches using GitHub's pull requests system on 105[pelletier/go-toml](https://github.com/pelletier/go-toml). Any feedback would be 106much appreciated! 107 108### Run tests 109 110You have to make sure two kind of tests run: 111 1121. The Go unit tests 1132. The TOML examples base 114 115You can run both of them using `./test.sh`. 116 117### Fuzzing 118 119The script `./fuzz.sh` is available to 120run [go-fuzz](https://github.com/dvyukov/go-fuzz) on go-toml. 121 122## Versioning 123 124Go-toml follows [Semantic Versioning](http://semver.org/). The supported version 125of [TOML](https://github.com/toml-lang/toml) is indicated at the beginning of 126this document. The last two major versions of Go are supported 127(see [Go Release Policy](https://golang.org/doc/devel/release.html#policy)). 128 129## License 130 131The MIT License (MIT). Read [LICENSE](LICENSE). 132