Files

T

Thomas Pelletier 23f644976a Move query to its own subpackage (#152 )

Move all the query system to its own package. The reason is to
avoid it to rely on unexported methods and structures, and move
it out of the main package since this is really not a core
feature. It is still tied to the toml.TomlTree and toml.Position
structures for now.

* Move query mechanism to its own subpackage
* Rename QueryResult to Result to avoid stutter
* Add query.CompileAndExecute

Fixes #116

2017-05-07 17:14:13 -07:00

3.6 KiB

Raw Blame History

go-toml

Go library for the TOML format.

This library supports TOML version v0.4.0

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

The Go unit tests
The TOML examples base

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

License

The MIT License (MIT). Read LICENSE.

3.6 KiB Raw Blame History