How do I parse a TOML file into a Go struct with BurntSushi/toml?

Use the toml.Decode function similar to json.Unmarshal: define a struct with fields matching TOML keys or use struct tags like `toml:"key_name"` for custom mapping. The README shows an example with age, cats, and other fields decoded into a Config struct.

BurntSushi/toml vs pelletier/go-toml: which is better?

BurntSushi/toml offers a reflection-based API mirroring Go's standard library, ideal for those familiar with encoding/json, while pelletier/go-toml might have different performance profiles or API styles. BurntSushi/toml is praised for strict TOML v1.1.0 compliance and the included tomlv validator.

How to handle custom types like dates or emails in BurntSushi/toml?

Implement the encoding.TextUnmarshaler interface or a custom UnmarshalTOML method. The README provides a working example with mail.Address, where a wrapper type parses email strings automatically during decoding.

Does BurntSushi/toml support nested TOML tables?

Yes, it fully supports nested tables and arrays as per TOML v1.1.0. You can map them to nested structs in Go, using tags if field names don't match, similar to the standard json package.

How to validate TOML files from the command line?

Install the tomlv CLI tool with `go install github.com/BurntSushi/toml/cmd/tomlv@latest` and run `tomlv your-file.toml`; it will output errors for invalid syntax, making it useful for CI/CD pipelines.

Is BurntSushi/toml actively maintained?

Yes, the project has regular releases and changelogs, as indicated in the README's reference to the releases page and git tags, ensuring updates for bugs and spec changes.

Open-Awesome

toml

MITGov1.6.0

A TOML parser for Go with reflection, compatible with TOML v1.1.0 and offering a CLI validator tool.

GitHub

5.0k stars568 forks0 contributors

What is toml?

BurntSushi/toml is a Go library for parsing and generating TOML configuration files. It provides a reflection-based interface similar to Go's standard json and xml packages, enabling seamless integration with Go structs for configuration management. The library fully supports TOML v1.1.0 and includes a CLI validator tool for checking file correctness.

Target Audience

Go developers who need to read or write TOML configuration files in their applications, particularly those seeking an idiomatic, standard-library-like approach. It's also useful for DevOps engineers or tool authors who require a reliable TOML parser and validator within Go-based tools.

Value Proposition

Developers choose this library because it offers a minimal, obvious API that integrates naturally with Go's ecosystem, mirroring the familiar patterns of encoding/json. Its full TOML v1.1.0 compliance and included CLI validator provide reliability and convenience not always found in alternatives.

Overview

TOML parser for Golang with reflection.

Use Cases

Best For

Parsing TOML configuration files into Go structs with reflection-based mapping.
Generating TOML from Go structs for configuration serialization.
Validating TOML files for syntax correctness using the included tomlv CLI tool.
Handling custom data types in TOML via encoding.TextUnmarshaler or UnmarshalTOML interfaces.
Managing configuration in Go projects where struct tags are needed for key-field mapping.
Ensuring compatibility with the latest TOML v1.1.0 specification in Go applications.

Not Ideal For

Projects not using Go, as this is a language-specific library with no cross-platform support.
High-performance applications where reflection overhead could bottleneck parsing or serialization speed.
Environments stuck on Go versions older than 1.18, due to its minimum version requirement.
Scenarios requiring fine-grained control over TOML parsing without reflection, such as custom lexer/parser implementations.

Pros & Cons

Pros

Standard-Library Familiarity

Uses a reflection interface identical to Go's json and xml packages, making it instantly familiar to developers and reducing the learning curve.

Full TOML v1.1.0 Compliance

Supports the latest TOML specification, ensuring reliable parsing and generation without compatibility issues for modern features.

Built-in CLI Validator

Includes the tomlv tool for command-line validation of TOML files, adding convenience for testing and debugging configurations.

Flexible Custom Unmarshaling

Allows integration with encoding.TextUnmarshaler and custom UnmarshalTOML interfaces, enabling handling of complex types like email addresses as demonstrated in the README.

Cons

Reflection Performance Overhead

The reflection-based decoding, while convenient, can be slower than optimized, direct parsers, making it less suitable for latency-sensitive applications.

Exported Fields Limitation

Only exported struct fields are processed, as noted in the README, which can complicate scenarios involving private or internal data structures.

Go Version Lock-in

Requires Go 1.18 or newer, potentially excluding legacy projects or environments with strict version constraints.

Frequently Asked Questions

Related Projects

blackfriday

Blackfriday: a markdown processor for Go

Stars5,593

Forks598

Last commit2 years ago

goldmark

:trophy: The Golden Swiss Army Knife for markdown processing. 100% CommonMark compliant, AST w/ CST, Extensible, Fast, CJK-friendly.

Stars5,071

Forks328

Last commit2 days ago

html-to-markdown

⚙️ Convert HTML to Markdown. Even works with entire websites and can be extended through rules.

Stars3,836

Forks229

Last commit2 months ago

go-toml

Go library for the TOML file format

Stars1,998

Forks259