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).