tree: 834ec6d84281de47cb11b4ee16fc76f1e9980eed [path history] [tgz]
  1. .gitignore
  2. .travis.yml
  3. LICENSE
  4. README.md
  5. clean.sh
  6. doc.go
  7. example-crlf.toml
  8. example.toml
  9. keysparsing.go
  10. lexer.go
  11. match.go
  12. parser.go
  13. position.go
  14. query.go
  15. querylexer.go
  16. queryparser.go
  17. test.sh
  18. token.go
  19. toml.go
  20. tomltree_conversions.go
vendor/github.com/pelletier/go-toml/README.md

go-toml

Go library for the TOML format.

This library supports TOML version v0.4.0

GoDoc License Build Status Coverage Status Go Report Card

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 TomlTree
  • Line & column position data for all parsed elements
  • Query support similar to JSON-Path
  • Syntax errors contain line and column numbers

Go-toml is designed to help cover use-cases not covered by reflection-based TOML parsing:

  • Semantic evaluation of parsed TOML
  • Informing a user of mistakes in the source document, after it has been parsed
  • Programatic handling of default values on a case-by-case basis
  • Using a TOML document as a flexible data-store

Import

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

Usage

Example

Say you have a TOML file that looks like this:

[postgres]
user = "pelletier"
password = "mypassword"

Read the username and password like this:

import (
    "fmt"
    "github.com/pelletier/go-toml"
)

config, err := toml.LoadFile("config.toml")
if err != nil {
    fmt.Println("Error ", err.Error())
} else {
    // retrieve data directly
    user := config.Get("postgres.user").(string)
    password := config.Get("postgres.password").(string)

    // or using an intermediate object
    configTree := config.Get("postgres").(*toml.TomlTree)
    user = configTree.Get("user").(string)
    password = configTree.Get("password").(string)
    fmt.Println("User is ", user, ". Password is ", password)

    // show where elements are in the file
    fmt.Println("User position: %v", configTree.GetPosition("user"))
    fmt.Println("Password position: %v", configTree.GetPosition("password"))

    // use a query to gather elements without walking the tree
    results, _ := config.Query("$..[user,password]")
    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/tomjson
    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.

License

The MIT License (MIT). Read LICENSE.