Formater TOML

Ostatnia aktualizacja: kwiecień 2026

Czym jest formatowanie TOML?

TOML (Tom's Obvious Minimal Language) to format pliku konfiguracyjnego stworzony przez Toma Prestona-Wernera w 2013 roku. Mapuje bezpośrednio na tablicę asocjacyjną i używa jawnego typowania dla wszystkich wartości. Formater TOML przyjmuje surowy lub niespójnie wystylizowany TOML i ponownie go serializuje ze spójnymi odstępami, właściwym wcięciem i kanonicznym porządkiem kluczy. Rezultatem jest plik zgodny z tymi samymi konwencjami w całym projekcie, co ułatwia przeglądanie zmian konfiguracji w diffach.

Specyfikacja TOML v1.0.0, sfinalizowana w styczniu 2021 roku, definiuje gramatykę na tyle ściśle, że każdy zgodny parser tworzy identyczną strukturę danych z tego samego wejścia. Formatowanie nie zmienia semantycznej zawartości pliku TOML. Dostosowuje jedynie białe znaki, grupowanie kluczy i styl cytowania. Oznacza to, że możesz formatować pliki TOML bez obaw o naruszenie działania aplikacji.

W przeciwieństwie do JSON, TOML obsługuje komentarze, natywne typy daty i godziny oraz wiele form ciągów (podstawowe, dosłowne i wieloliniowe). Dobry formater zachowuje komentarze i respektuje różnicę między tabelami inline a standardowymi nagłówkami tabel. Poprawnie obsługuje również tablice tabel, zachowując grupowanie sekcji tak, aby plik był czytelny zarówno dla ludzi, jak i parserów go przetwarzających.

title="My App"
version="1.0.0"
debug=false
[database]
host="localhost"
port=5432
name="mydb"
[database.pool]
max_connections=25
timeout=30
[[servers]]
name="web"
host="web.example.com"
[[servers]]
name="api"
host="api.example.com"

title = "My App"
version = "1.0.0"
debug = false

[database]
host = "localhost"
port = 5432
name = "mydb"

[database.pool]
max_connections = 25
timeout = 30

[[servers]]
name = "web"
host = "web.example.com"

[[servers]]
name = "api"
host = "api.example.com"

Dlaczego warto używać formatera TOML?

Pliki konfiguracyjne gromadzą niejednolity styl, gdy różni członkowie zespołu edytują je w czasie. Tabulatory mieszają się ze spacjami, niektóre klucze są niepotrzebnie cytowane, a sekcje tabel tracą wizualne grupowanie. Formater TOML normalizuje to wszystko w jednym przebiegu.

Zastosowania formatera TOML

Skrócona dokumentacja składni TOML

TOML ma niewielki zestaw konstrukcji. Poniższa tabela zawiera wszystkie elementy strukturalne zdefiniowane w specyfikacji TOML v1.0.0. Formater stosuje spójne odstępy i grupowanie do każdego z nich.

TOML vs JSON vs YAML

TOML, JSON i YAML rozwiązują nakładające się problemy, ale przyjmują różne kompromisy.

Przykłady kodu

Poniższe przykłady formatują TOML programistycznie w różnych językach i narzędziach. Każdy odczytuje plik, parsuje go i zapisuje sformatowaną wersję.

import { parse, stringify } from '@iarna/toml'
import fs from 'fs'

const raw = fs.readFileSync('config.toml', 'utf-8')
const doc = parse(raw)
const formatted = stringify(doc)
// stringify() outputs canonical TOML with consistent spacing
fs.writeFileSync('config.toml', formatted)

// Quick one-liner with npx:
// npx taplo fmt config.toml

import tomllib   # Python 3.11+ (read-only)
import tomli_w   # pip install tomli-w (write)

# Parse and re-serialize to format
with open("config.toml", "rb") as f:
    data = tomllib.load(f)

formatted = tomli_w.dumps(data)
# tomli_w produces sorted keys, consistent quoting, and
# proper whitespace around = signs
print(formatted)

# CLI alternative: taplo fmt config.toml

package main

import (
    "fmt"
    "os"
    "github.com/BurntSushi/toml"
    "bytes"
)

func main() {
    var data map[string]interface{}
    _, err := toml.DecodeFile("config.toml", &data)
    if err != nil {
        fmt.Fprintln(os.Stderr, err) // parse error with line number
        os.Exit(1)
    }
    var buf bytes.Buffer
    enc := toml.NewEncoder(&buf)
    enc.Indent = "  "
    enc.Encode(data) // re-serialized with consistent formatting
    fmt.Print(buf.String())
}

# Install taplo — the standard TOML toolkit
cargo install taplo-cli
# or: npm install -g @taplo/cli

# Format a single file in place
taplo fmt config.toml

# Format all .toml files in a project
taplo fmt

# Check formatting without modifying (CI-friendly)
taplo fmt --check

# Validate TOML syntax without formatting
taplo lint config.toml

Często zadawane pytania