Formattazione TOML
Formatta e convalida il TOML, il linguaggio minimale ideato da Tom. Verifica la sintassi secondo la specifica TOML v1.1.0, uniforma gli spazi attorno a = e fra gli elementi dei vettori e segnala gli errori di sintassi indicando il numero di riga.
I principali tipi di dato del TOML
| Tipo | Esempio di scrittura | Descrizione |
|---|---|---|
| Stringa (di base) | "hello" | Racchiusa fra virgolette doppie. Ammette le sequenze protette come \n e \t. |
| Stringa (letterale) | 'C:\path' | Racchiusa fra virgolette semplici. Non esegue alcuna protezione dei caratteri ed è quindi comoda per i percorsi con barre rovesciate. |
| Intero | 42 | Oltre al decimale ammette i prefissi 0x per l'esadecimale, 0o per l'ottale e 0b per il binario, e la separazione con il trattino basso, come 1_000. |
| Numero in virgola mobile | 3.14 | Sono valori validi anche la notazione esponenziale, come 1e10, e le voci inf e nan. |
| Valore logico | true | Soltanto true oppure false. La forma con l'iniziale maiuscola non è valida. |
| Vettore | [1, 2, 3] | Valori separati da virgole entro parentesi quadre. È ammessa anche la virgola finale. |
| Tabella | [server] | Le coppie chiave e valore che seguono l'intestazione di sezione diventano elementi figli di quella tabella. |
| Vettore di tabelle | [[fruits-basket]] | Ripetendo più volte una tabella omonima si esprime un vettore, per esempio per definire più pacchetti da cui si dipende. |
| Data e ora | 1979-05-27T07:32:00Z | Nel formato della norma RFC 3339. È l'unico valore composito che si scrive senza virgolette. |
Formattare il TOML e verificarne la sintassi
TOML è un formato pensato per i file di configurazione, e il suo pregio sta nella schiettezza del limitarsi a elencare coppie key = value. Questo strumento mette in ordine il TOML che incollate e nel contempo giudica se la sintassi regge; quando qualcosa è rotto, ne indica la riga colpevole.
La prima cosa su cui si inciampa in TOML è che la struttura nasce da righe di intestazione scritte [tabella] e non dall'indentazione. Chi viene da YAML ricorre d'istinto al rientro per esprimere la gerarchia, ma in TOML il rientro non significa proprio nulla: le chiavi scritte fra un'intestazione di tabella e la successiva appartengono a quella tabella. È dunque la posizione della riga a decidere la struttura. L'altro tratto caratteristico è che date e orari sono tipi a pieno titolo, sicché un valore come 2026-09-20T10:00:00Z si può scrivere senza virgolette, così com'è.
Come si usa
-
Incollate il TOML
Il contenuto di un
Cargo.tomlo di unpyproject.tomlsi inserisce così com'è. - Guardate il verdetto Un ingresso sano viene indicato come TOML valido; se la sintassi non regge, viene segnalata la riga in questione.
- Leggete il risultato formattato Gli spazi attorno a = e fra gli elementi dei vettori diventano uniformi e i confini fra le tabelle diventano facili da cogliere.
- Ricopiatelo indietro Il contenuto riordinato può tornare nel file senza altre modifiche.
Consigli per sfruttarlo al meglio
- Vettori, tabelle in linea e stringhe su più righe ("""...""" o '''...''') distribuiti su più righe sono riprodotti così come sono scritti, perché il loro contenuto non cambi. La formattazione riguarda i valori che stanno su una riga.
- La sintassi è verificata con smol-toml, un analizzatore conforme al TOML v1.1.0. Segnala come non validi anche gli interi con zeri iniziali (007), gli esadecimali con segno (+0x10), le chiavi senza virgolette che contengono spazi e le chiavi definite due volte.
- Il risultato allinea sempre a uno spazio singolo ciò che precede e segue il segno «=» e uniforma anche i separatori dei vettori e delle tabelle in linea: le abitudini di scrittura dei singoli autori vengono così assorbite.
- I commenti, cioè quanto segue il cancelletto, sono conservati; la formattazione si limita ad aggiungere uno spazio subito dopo il cancelletto, senza alterarne il contenuto.
- Le righe vuote consecutive sono ridotte a una sola, rendendo più evidenti gli stacchi fra una tabella e l'altra.
- L'elaborazione avviene interamente nel navigatore: il contenuto del file di configurazione che inserite non viene mai trasmesso a un servente esterno.
Quando torna utile
Nel cercare un errore in un file di configurazione
Collocare male un'intestazione di tabella cambia in silenzio a quale tabella appartiene una chiave, ed è un genere di errore che l'occhio coglie di rado.
Nel leggere la configurazione di un progetto in Rust o Python
Formattare un Cargo.toml o un pyproject.toml rende assai più agevole seguire le divisioni fra le dipendenze.
Nel verificare qualcosa convertito da un altro formato
Impostazioni riscritte da JSON o YAML si possono provare sul momento per vedere se la sintassi regge.
Nell'uniformare lo stile di una squadra
Formattare prima di consolidare tiene gli spazi vaganti fuori dal diff e vi lascia solo ciò che conta.
Termini del TOML
- Tabella
- Un'intestazione scritta fra parentesi quadre, come
[package], che raccoglie in un gruppo le chiavi che vanno da lì all'intestazione seguente. - Array di tabelle
- La notazione scritta con parentesi doppie,
[[dependencies]]. Ripetere la stessa intestazione aggiunge un altro elemento all'array. - Tabella in linea
- Una tabella scritta su una sola riga come
{ a = 1, b = 2 }. Si presta a impostazioni brevi. Il TOML v1.0.0 non vi ammetteva a capo, mentre dalla v1.1.0 (pubblicata a dicembre 2025) sono consentiti gli a capo e una virgola finale. - Stringa di base
- Una stringa fra virgolette doppie, dentro la quale hanno effetto gli escape come
\n. - Stringa letterale
- Una stringa fra apici singoli. Nessun escape vi ha effetto, il che la rende la scelta giusta per i percorsi di Windows e le espressioni regolari.
- Data e ora
- Un tipo che TOML offre in modo nativo. Una data o un'ora come
1979-05-27T07:32:00Zsi può scrivere senza virgolette.
Domande frequenti
[[sezione]] avviene regolarmente, ma non si riuniscono le sezioni omonime in un unico vettore né si converte il tutto in un oggetto JSON. Per le strutture complesse di vettori di tabelle, verificate a vista il risultato della formattazione riga per riga prima di usarlo.
A proposito — perché il TOML è diventato la lingua comune dei file di configurazione
Il TOML è un formato ideato nel 2013 da Tom Preston-Werner, cofondatore di GitHub, e il suo nome — «il linguaggio minimale e ovvio di Tom» — ne esprime direttamente il principio ispiratore: una sintassi maneggevole per la macchina come quella del JSON e insieme leggibile e scrivibile senza esitazioni da una persona.
La spinta decisiva alla sua diffusione venne dall'adozione del file Cargo.toml come formato di configurazione da parte del gestore di pacchetti di Rust. In seguito lo standard di impacchettamento di Python introdusse pyproject.toml, unificando una situazione in cui proliferavano file di configurazione e di requisiti diversi.
La differenza principale rispetto a YAML sta nel non attribuire significato al rientro. In YAML uno scarto nell'ampiezza del rientro provoca facilmente errori di sintassi o strutture dati fraintese, mentre il TOML esprime la gerarchia con la sola combinazione di [sezione] e chiave = valore: si dice perciò che gli incidenti da copia e incolla vi siano assai meno frequenti.
Il TOML è però meno espressivo di YAML. Non si presta al riuso dei valori tramite ancore e alias né alla scrittura sintetica di strutture complesse e profondamente annidate: nella pratica si è consolidato l'uso di scegliere fra TOML, YAML e JSON secondo il caso.