Formattatore TOML

Ultimo aggiornamento: aprile 2026

Cos'è la Formattazione TOML?

TOML (Tom's Obvious Minimal Language) è un formato di file di configurazione creato da Tom Preston-Werner nel 2013. Si mappa direttamente a una tabella hash e utilizza la tipizzazione esplicita per tutti i valori. Un formattatore TOML prende del TOML grezzo o con uno stile non uniforme e lo ri-serializza con spaziatura uniforme, indentazione corretta e ordinamento canonico delle chiavi. Il risultato è un file che segue le stesse convenzioni in tutto il progetto, rendendo le modifiche alla configurazione più facili da revisionare nelle diff.

La specifica TOML v1.0.0, finalizzata nel gennaio 2021, definisce la grammatica in modo sufficientemente rigoroso da garantire che qualsiasi parser conforme produca una struttura dati identica dallo stesso input. La formattazione non modifica il contenuto semantico di un file TOML. Regola solo gli spazi bianchi, il raggruppamento delle chiavi e lo stile delle virgolette. Questo significa che puoi formattare liberamente i file TOML senza preoccuparti di alterare il comportamento della tua applicazione.

A differenza di JSON, TOML supporta i commenti, i tipi date-time nativi e più forme di stringa (base, letterale e multiriga). Un buon formattatore preserva i commenti e rispetta la distinzione tra tabelle inline e intestazioni di tabella standard. Gestisce correttamente anche gli array di tabelle, mantenendo intatto il raggruppamento delle sezioni in modo che il file rimanga leggibile sia per gli esseri umani sia per i parser che lo consumano.

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"

Perché Usare un Formattatore TOML?

I file di configurazione accumulano deriva di stile nel tempo, man mano che diversi membri del team li modificano. I tab si mescolano con gli spazi, alcune chiavi vengono virgolettate inutilmente e le sezioni di tabella perdono il loro raggruppamento visivo. Un formattatore TOML normalizza tutto questo in un solo passaggio.

Casi d'Uso del Formattatore TOML

Riferimento alla Sintassi TOML

TOML ha un insieme ridotto di costrutti. La tabella seguente elenca ogni elemento strutturale definito nella specifica TOML v1.0.0. Un formattatore applica spaziatura e raggruppamento coerenti a tutti questi elementi.

TOML vs JSON vs YAML

TOML, JSON e YAML risolvono problemi simili ma con compromessi diversi.

Esempi di Codice

Gli esempi seguenti mostrano come formattare TOML a livello di codice in diversi linguaggi e strumenti. Ciascuno legge un file, lo analizza e scrive una versione formattata.

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

Domande Frequenti