TOML Parser

TOML (Tom's Obvious Minimal Language) is a minimal configuration file format designed to be easy to read and write. It's the standard configuration format for Rust (Cargo.toml), Python packaging (pyproject.toml), and many other modern development tools.

Specifications

• TOML v1.0.0 Specification
• TOML.io

Common Use Cases

• Parse Cargo.toml for Rust project dependencies and metadata
• Read pyproject.toml for Python build configuration (PEP 518/621)
• Process Hugo, Zola, or other static site generator configs
• Edit Deno configuration files (deno.toml)
• Validate configuration before deployment

Features

• Full TOML v1.0.0 specification support
• Parse tables, arrays of tables, and nested structures
• Handle inline tables and arrays
• Support for date/time values
• Convert to JSON, YAML, or XML
• Syntax validation with error messages

Examples

[package]
name = "my-project"
version = "0.1.0"
edition = "2021"

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-package"
version = "1.0.0"
dependencies = ["requests>=2.28"]

Tips

• TOML uses = for key-value pairs, unlike YAML's colons.
• Strings must be quoted. Use """ for multi-line strings.
• Tables ([table]) create nested structures.
• Arrays of tables use [[array]] syntax.

Understanding TOML

TOML (Tom's Obvious Minimal Language) is a configuration file format designed to be unambiguous and easy to read. Created by Tom Preston-Werner (co-founder of GitHub), TOML maps cleanly to a hash table and is intentionally simpler than YAML while being more expressive than INI files. Version 1.0.0 was finalized in 2021.

TOML's design centers on clarity. Keys and values use a simple "key = value" syntax. Tables (sections) are denoted with [brackets], creating nested structures without indentation sensitivity. Arrays of tables use [[double brackets]] to define repeated sections. TOML natively supports strings, integers, floats, booleans, dates, times, and date-times as first-class types, eliminating parsing ambiguity common in JSON and YAML.

The Rust ecosystem adopted TOML early with Cargo.toml as the package manifest format. Python followed with pyproject.toml (PEP 518 and PEP 621), making it the modern replacement for setup.py and setup.cfg. TOML also appears in Go tools, Deno (deno.toml), Hugo, and many other developer tools that value explicit, readable configuration.

TOML trades flexibility for predictability. Unlike YAML, there is only one way to represent each data structure. There are no anchors, no aliases, no implicit type coercion surprises, and no significant whitespace. The tradeoff is that deeply nested structures become verbose, since each level requires its own table header.

TOML excels for flat or moderately nested configuration files that humans edit frequently. Its unambiguous syntax avoids YAML pitfalls like boolean coercion and indentation errors, while being more readable than JSON for configuration purposes. TOML is the natural choice for project manifests (Cargo.toml, pyproject.toml) and tool configuration. YAML remains better suited for deeply nested structures like Kubernetes manifests, and JSON is the standard for data interchange between systems.

The [[double brackets]] syntax creates arrays of tables, where each occurrence of the header adds a new element to the array. For example, [[products]] appearing three times creates an array of three product objects, each with its own key-value pairs collected in order. TOML also supports single-line comments using the hash symbol (#), which can appear on their own line or after a value. There is no multi-line comment syntax, but the single-line variant is still a significant advantage over JSON, which has no comment support at all.

Tables and inline tables serve different purposes. Tables use [header] syntax and span multiple lines, making them readable for sections with many keys. Inline tables use curly braces on a single line (key = { a = 1, b = 2 }) and must be defined entirely on that one line — they cannot be extended after definition. As a rule of thumb, use standard tables for readability when a section has more than two or three keys.