# go-toml

Go library for the [TOML](https://github.com/mojombo/toml) format.

This library supports TOML version

[v0.4.0](https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.4.0.md)

[![GoDoc](https://godoc.org/github.com/pelletier/go-toml?status.svg)](http://godoc.org/github.com/pelletier/go-toml)

[![license](https://img.shields.io/github/license/pelletier/go-toml.svg)](https://github.com/pelletier/go-toml/blob/master/LICENSE)

[![Build Status](https://travis-ci.org/pelletier/go-toml.svg?branch=master)](https://travis-ci.org/pelletier/go-toml)

[![Coverage Status](https://coveralls.io/repos/github/pelletier/go-toml/badge.svg?branch=master)](https://coveralls.io/github/pelletier/go-toml?branch=master)

[![Go Report Card](https://goreportcard.com/badge/github.com/pelletier/go-toml)](https://goreportcard.com/report/github.com/pelletier/go-toml)

## Features

Go-toml provides the following features for using data parsed from TOML documents:

* Load TOML documents from files and string data

* Easily navigate TOML structure using Tree

* Mashaling and unmarshaling to and from data structures

* Line & column position data for all parsed elements

* [Query support similar to JSON-Path](query/)

* Syntax errors contain line and column numbers

## Import

```go

import "github.com/pelletier/go-toml"

```

## Usage example

Read a TOML document:

```go

config, _ := toml.Load(`

[postgres]

user = "pelletier"

password = "mypassword"`)

// retrieve data directly

user := config.Get("postgres.user").(string)

// or using an intermediate object

postgresConfig := config.Get("postgres").(*toml.Tree)

password := postgresConfig.Get("password").(string)

```

Or use Unmarshal:

```go

type Postgres struct {

    User     string

    Password string

}

type Config struct {

    Postgres Postgres

}

doc := []byte(`

[Postgres]

User = "pelletier"

Password = "mypassword"`)

config := Config{}

toml.Unmarshal(doc, &config)

fmt.Println("user=", config.Postgres.User)

```

Or use a query:

```go

// use a query to gather elements without walking the tree

q, _ := query.Compile("$..[user,password]")

results := q.Execute(config)

for ii, item := range results.Values() {

    fmt.Println("Query result %d: %v", ii, item)

}

```

## Documentation

The documentation and additional examples are available at

[godoc.org](http://godoc.org/github.com/pelletier/go-toml).

## Tools

Go-toml provides two handy command line tools:

* `tomll`: Reads TOML files and lint them.

    ```

    go install github.com/pelletier/go-toml/cmd/tomll

    tomll --help

    ```

* `tomljson`: Reads a TOML file and outputs its JSON representation.

    ```

    go install github.com/pelletier/go-toml/cmd/tomljson

    tomljson --help

    ```

## Contribute

Feel free to report bugs and patches using GitHub's pull requests system on

[pelletier/go-toml](https://github.com/pelletier/go-toml). Any feedback would be

much appreciated!

### Run tests

You have to make sure two kind of tests run:

1. The Go unit tests

2. The TOML examples base

You can run both of them using `./test.sh`.

### Fuzzing

The script `./fuzz.sh` is available to

run [go-fuzz](https://github.com/dvyukov/go-fuzz) on go-toml.

## Versioning

Go-toml follows [Semantic Versioning](http://semver.org/). The supported version

of [TOML](https://github.com/toml-lang/toml) is indicated at the beginning of

this document. The last two major versions of Go are supported

(see [Go Release Policy](https://golang.org/doc/devel/release.html#policy)).

## License

The MIT License (MIT). Read [LICENSE](LICENSE).