Go library for the TOML language
Clone or download
Latest commit 27c6b39 Nov 24, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Update issue templates Jul 19, 2018
cmd Fix path not found message on Windows (#227) Jul 3, 2018
query Go 1.10 support (#223) Mar 23, 2018
.gitignore Add fuzz.sh to do fuzzing with go-fuzz (#194) Oct 21, 2017
.travis.yml Travis check for golang 1.11 (#240) Sep 18, 2018
LICENSE Update license (#128) Feb 9, 2017
PULL_REQUEST_TEMPLATE.md Setup Codecov (#235) Jul 24, 2018
README.md Fossa badge Nov 24, 2018
appveyor.yml Update Go version in Appveyor (#246) Nov 19, 2018
benchmark.json Benchmark against other libraries (#175) Jun 25, 2017
benchmark.sh Benchmark against other libraries (#175) Jun 25, 2017
benchmark.toml Benchmark against other libraries (#175) Jun 25, 2017
benchmark.yml Benchmark against other libraries (#175) Jun 25, 2017
benchmark_test.go Benchmark against other libraries (#175) Jun 25, 2017
doc.go Fix typos (#195) Oct 21, 2017
doc_test.go Improve doc for un/marshal functions (#189) Oct 1, 2017
example-crlf.toml Fix support for CRLF line ending Feb 19, 2016
example.toml Readd source files. I need coffee now Feb 25, 2013
fuzz.go Fix fuzz (#199) Oct 22, 2017
fuzz.sh Add fuzz.sh to do fuzzing with go-fuzz (#194) Oct 21, 2017
keysparsing.go Fix parsing of single quoted keys (#201) Jan 18, 2018
keysparsing_test.go Fix parsing of single quoted keys (#201) Jan 18, 2018
lexer.go Add support for special float values (inf and nan) (#210) Jan 18, 2018
lexer_test.go Fix parsing of single quoted keys (#201) Jan 18, 2018
marshal.go Allow to marshal pointer to struct and map (#247) Nov 19, 2018
marshal_test.go Allow to marshal pointer to struct and map (#247) Nov 19, 2018
marshal_test.toml Reflection-based marshaling / unmarshaling (#149) Mar 29, 2017
parser.go Fix integer keys in inline tables (#239) Sep 22, 2018
parser_test.go Fix integer keys in inline tables (#239) Sep 22, 2018
position.go Pointer cleanup (#78) Jul 21, 2016
position_test.go Simplify redundant types in literals (#95) Aug 23, 2016
test.sh Setup Codecov (#235) Jul 24, 2018
token.go Add support for special float values (inf and nan) (#210) Jan 18, 2018
token_test.go Fix multiline strings (#62) Apr 21, 2016
toml.go Support byte order mark (#253) Nov 24, 2018
toml_test.go Support byte order mark (#253) Nov 24, 2018
tomltree_create.go Comment annotation for Marshal (#185) Oct 1, 2017
tomltree_create_test.go Lint (#206) Dec 22, 2017
tomltree_write.go Multiline Marshal tag (#221) Jun 5, 2018
tomltree_write_test.go Add support for special float values (inf and nan) (#210) Jan 18, 2018

README.md

go-toml

Go library for the TOML format.

This library supports TOML version v0.4.0

GoDoc license Build Status Windows Build status codecov Go Report Card FOSSA Status

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
  • Syntax errors contain line and column numbers

Import

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

Usage example

Read a TOML document:

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:

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:

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

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. 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 on go-toml.

Versioning

Go-toml follows Semantic Versioning. The supported version of TOML is indicated at the beginning of this document. The last two major versions of Go are supported (see Go Release Policy).

License

The MIT License (MIT). Read LICENSE.