vendor/github.com/pelletier/go-toml/README.md

   1 # go-toml
   2
   3 Go library for the [TOML](https://github.com/mojombo/toml) format.
   4
   5 This 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
  16 Go-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
  28 import "github.com/pelletier/go-toml"
  29 ```
  30
  31 ## Usage example
  32
  33 Read a TOML document:
  34
  35 ```go
  36 config, _ := toml.Load(`
  37 [postgres]
  38 user = "pelletier"
  39 password = "mypassword"`)
  40 // retrieve data directly
  41 user := config.Get("postgres.user").(string)
  42
  43 // or using an intermediate object
  44 postgresConfig := config.Get("postgres").(*toml.Tree)
  45 password := postgresConfig.Get("password").(string)
  46 ```
  47
  48 Or use Unmarshal:
  49
  50 ```go
  51 type Postgres struct {
  52     User     string
  53     Password string
  54 }
  55 type Config struct {
  56     Postgres Postgres
  57 }
  58
  59 doc := []byte(`
  60 [Postgres]
  61 User = "pelletier"
  62 Password = "mypassword"`)
  63
  64 config := Config{}
  65 toml.Unmarshal(doc, &config)
  66 fmt.Println("user=", config.Postgres.User)
  67 ```
  68
  69 Or use a query:
  70
  71 ```go
  72 // use a query to gather elements without walking the tree
  73 q, _ := query.Compile("$..[user,password]")
  74 results := q.Execute(config)
  75 for ii, item := range results.Values() {
  76     fmt.Println("Query result %d: %v", ii, item)
  77 }
  78 ```
  79
  80 ## Documentation
  81
  82 The documentation and additional examples are available at
  83 [godoc.org](http://godoc.org/github.com/pelletier/go-toml).
  84
  85 ## Tools
  86
  87 Go-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
 104 Feel 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
 106 much appreciated!
 107
 108 ### Run tests
 109
 110 You have to make sure two kind of tests run:
 111
 112 1. The Go unit tests
 113 2. The TOML examples base
 114
 115 You can run both of them using `./test.sh`.
 116
 117 ### Fuzzing
 118
 119 The script `./fuzz.sh` is available to
 120 run [go-fuzz](https://github.com/dvyukov/go-fuzz) on go-toml.
 121
 122 ## Versioning
 123
 124 Go-toml follows [Semantic Versioning](http://semver.org/). The supported version
 125 of [TOML](https://github.com/toml-lang/toml) is indicated at the beginning of
 126 this 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
 131 The MIT License (MIT). Read [LICENSE](LICENSE).