toby3d

auth

Fork 0

5.0 KiB

Raw Blame History

go-toml

Go library for the TOML format.

This library supports TOML version
v1.0.0-rc.3

Development status

ℹ️ Consider go-toml v2!

The next version of go-toml is in active development, and
nearing completion.

Though technically in beta, v2 is already more tested, fixes bugs,
and much faster. If you only need reading and writing TOML documents
(majority of cases), those features are implemented and the API unlikely to
change.

The remaining features will be added shortly. While pull-requests are welcome on
v1, no active development is expected on it. When v2.0.0 is released, v1 will be
deprecated.

👉 go-toml v2

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
Marshaling 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.Printf("Query result %d: %v\n", ii, item)
}

Documentation

The documentation and additional examples are available at
pkg.go.dev.

Tools

Go-toml provides three handy command line tools:

tomll: Reads TOML files and lints 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

jsontoml: Reads a JSON file and outputs a TOML representation.

go install github.com/pelletier/go-toml/cmd/jsontoml
jsontoml --help

Docker image

Those tools are also available as a Docker image from
dockerhub. For example, to
use tomljson:

docker run -v $PWD:/workdir pelletier/go-toml tomljson /workdir/example.toml

Only master (latest) and tagged versions are published to dockerhub. You
can build your own image as usual:

docker build -t go-toml .

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

go test ./...

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) + Apache 2.0. Read LICENSE.

5.0 KiB Raw Blame History Unescape Escape