TOML Formatter

The TOML Formatter beautifies TOML files (Tom's Obvious, Minimal Language) used for configuration in Rust (Cargo.toml), Python (pyproject.toml for Poetry, hatch, pip), Hugo (config.toml), netlify.toml, dbt profiles, and many other modern tools. TOML is a simpler alternative to YAML — no significant whitespace, explicit sections, clear syntax. This formatter normalizes section ordering (optional), aligns key-value pairs, preserves comments, and validates TOML 1.0 syntax.

TOML (v1.0 stabilized 2021) has gained adoption as the preferred config format for modern tooling. Rust Cargo uses TOML. Python PEP 621 made pyproject.toml the standard for Python package metadata. Hugo, netlify, and many new tools default to TOML instead of YAML (easier to get right — no indentation pitfalls). This formatter handles all TOML syntax: tables, arrays, inline tables, arrays of tables, dates, strings with escapes, multiline strings.

TOML v1.0 (Tom's Obvious, Minimal Language) — specification by Tom Preston-Werner (GitHub co-founder).

Syntax:

Key-value pairs:

``toml
name = "Alice"
age = 30
active = true
``

Strings:

- Basic: name = "Alice" (escape sequences supported)
- Literal: path = 'C:\Users\' (no escape, single quotes)
- Multi-line basic: description = """multi line with \n escapes"""
- Multi-line literal: regex = ''multi line raw''

Numbers:

- Integer: 42, -1000, 0xff (hex), 0o755 (octal), 0b1010 (binary)
- Float: 3.14, 1e10, inf, nan
- Underscores for readability: 1_000_000

Booleans: true, false (lowercase only)

Dates:

- Offset date-time: 2026-05-05T10:30:00Z
- Local date-time: 2026-05-05T10:30:00
- Local date: 2026-05-05
- Local time: 10:30:00

Arrays:

``toml
tags = ["admin", "user"]
numbers = [1, 2, 3]
mixed = [1, "two", 3.0]
``

Tables (sections):

```toml
[server]
host = "localhost"
port = 8080

[database]
url = "postgres://..."
```

Nested tables:

``toml
[server.ssl]
cert = "/path/to/cert"
key = "/path/to/key"
``

Inline tables (on one line):

``toml
point = { x = 1, y = 2 }
``

Arrays of tables:

```toml
[[servers]]
name = "server-1"
ip = "10.0.0.1"

[[servers]]
name = "server-2"
ip = "10.0.0.2"
```

Dotted keys:

``toml
apple.type = "fruit"
apple.color = "red"
``

Equivalent to:

``toml
[apple]
type = "fruit"
color = "red"
``

Common TOML files:

Cargo.toml (Rust):
```toml
[package]
name = "my-app"
version = "0.1.0"
authors = ["Alice <alice@example.com>"]

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

[[bin]]
name = "main"
path = "src/main.rs"
```

pyproject.toml (Python, PEP 621):
```toml
[project]
name = "my-package"
version = "0.1.0"
description = "A cool package"
authors = [{ name = "Alice", email = "alice@example.com" }]
dependencies = ["requests >=2.0"]

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

Formatter behavior:

- Normalizes spacing around = (one space each side).
- Aligns values in sections (optional).
- Preserves order within sections.
- Normalizes string quoting (converts single to double if no special chars).
- Keeps comments (# comments) in their position.
- Detects syntax errors.

Validation:

TOML is strict. Parser errors usually indicate:
- Missing quotes around strings.
- Using = after section headers (invalid).
- Inline tables with extra whitespace.
- Mixed array element types (disallowed in arrays).

TOML vs YAML: TOML is simpler — no significant whitespace, explicit sections. YAML is more feature-rich but has quirks (Norway problem, type coercion). TOML is growing for configs; YAML still dominates in K8s/CI.

TOML vs JSON: TOML supports comments (JSON does not). TOML has date type (JSON does not). TOML is more human-readable. JSON is more machine-parseable. Config vs API.

TOML vs INI: INI is older, simpler, less structured. TOML is inspired by INI but adds nested tables, arrays, dates, multiple types. TOML is INI's modern successor.

Cargo.toml vs package.json: Both manifest files. Cargo uses TOML; npm uses JSON. Both accomplish same goal (dependencies, metadata). TOML allows comments, JSON does not.

pyproject.toml adoption: PEP 621 (2020) standardized pyproject.toml for Python package metadata. Replaces old setup.py and setup.cfg. Unified format for all Python tools.

TOML 1.0 vs 0.5: 1.0 (2021) is stable. Earlier versions (0.5, 0.4) had different rules. This formatter uses 1.0 syntax.