go-toml vs BurntSushi/toml which should I use?

go-toml v2 generally offers better performance, with benchmarks showing up to 5x faster unmarshaling. However, BurntSushi/toml might be preferred if you need stability without breaking changes from v1 or rely on removed features like query support.

How to preserve comments when writing TOML with go-toml?

Use the commented config feature by adding the 'commented' tag to struct fields or configuring the Encoder. This allows outputting TOML with comments and commented-out values for configuration files.

Does go-toml support the latest TOML spec?

Yes, go-toml v2 fully supports TOML v1.0.0, including all features like local date/time and inline tables. It's designed to be compatible with modern TOML documents.

What are the main breaking changes in go-toml v2?

Key breaking changes include dropped default struct tags and Unmarshaler interface, altered decoding for arrays and interfaces to match encoding/json, and removal of tom.Tree and query package. The README provides a detailed migration guide.

How to handle local dates in go-toml?

Use the provided LocalDate, LocalTime, and LocalDateTime types. These can be directly unmarshaled from TOML and converted to time.Time if needed, ensuring accurate representation without timezone ambiguity.

Is go-toml v2 stable for production use?

Core marshaling/unmarshaling is stable and follows semantic versioning, but the Parser API is marked as unstable. For most use cases, it's production-ready, but avoid unstable APIs if long-term compatibility is critical.

Open-Awesome

go-toml

NOASSERTIONGov2.4.3

A Go library for encoding and decoding TOML configuration files with high performance and stdlib-like behavior.

Visit Website GitHub

2.0k stars248 forks0 contributors

What is go-toml?

go-toml is a Go library for working with the TOML file format, enabling encoding and decoding of TOML documents to and from Go data structures. It solves the problem of parsing and generating TOML configuration files in Go applications with high performance and a familiar API. The library supports the full TOML v1.0.0 specification and includes features like strict mode validation and local date/time types.

Target Audience

Go developers who need to read or write TOML configuration files in their applications, particularly those working on tools, services, or CLI applications that use TOML for settings.

Value Proposition

Developers choose go-toml for its excellent performance compared to other Go TOML libraries, its stdlib-like API that reduces learning curve, and its comprehensive feature set including strict validation mode and contextual error messages. It's maintained, supports the latest TOML spec, and comes with useful command-line tools.

Overview

Go library for the TOML file format

Use Cases

Best For

Parsing configuration files in Go applications
Generating TOML documents from Go structs
Building CLI tools that work with TOML files
Validating TOML configuration with strict error checking
Converting between TOML and JSON formats
Linting and formatting TOML files

Not Ideal For

Applications requiring advanced document manipulation or AST-level editing of TOML files
Teams upgrading from go-toml v1 who cannot easily refactor for breaking API changes
Projects where configuration is primarily in JSON or YAML, and TOML support is optional
Use cases needing built-in default value handling via struct tags or custom unmarshaler interfaces

Pros & Cons

Pros

High Performance

Benchmarks show 2-5x faster unmarshaling compared to go-toml v1 and BurntSushi/toml, making it efficient for processing large configuration files.

Stdlib-like Familiarity

Designed to mimic Go's encoding/json API, reducing the learning curve for developers already accustomed to standard library patterns.

Contextual Error Debugging

Provides DecodeError with human-readable messages that include line and column context, simplifying troubleshooting of TOML syntax issues.

Strict Mode Validation

Decoder can be set to error on unknown fields, helping catch typos and ensure configuration files are correct.

Local Date/Time Support

Offers native LocalDate, LocalTime, and LocalDateTime types to accurately represent TOML's local date/time without timezone confusion.

Cons

Breaking Changes from v1

Migration to v2 requires significant code changes due to dropped features like default struct tags, Unmarshaler interface, and altered behavior in decoding arrays and interfaces.

No Document Model

Removed support for tom.Tree and query functionality, forcing users to handle arbitrary structures with maps and reflection, which is less convenient for complex manipulations.

Unstable Parser API

The Parser API for iterative AST parsing is explicitly marked as unstable, with no backward compatibility guarantees, risking future changes in production code.

External Dependency for Querying

Query features are absent; users must rely on third-party tools like dasel for JSONPath-style queries, adding complexity to the toolchain.

Frequently Asked Questions

Related Projects

blackfriday

Blackfriday: a markdown processor for Go

Stars5,610

Forks599

Last commit2 years ago

toml

TOML parser for Golang with reflection.

Stars4,985

Forks559

Last commit26 days ago

goldmark

:trophy: A markdown parser written in Go. Easy to extend, standard(CommonMark) compliant, well structured.

Stars4,908

Forks299

Last commit12 days ago

html-to-markdown

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

Stars3,755

Forks216

Last commit11 days ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub