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