Formattazione TOML
Formatta e convalida il TOML, il linguaggio minimale ideato da Tom. Allinea in modo leggibile le coppie chiave e valore, le tabelle e i 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. |
Consigli
- Vettori e tabelle in linea sono previsti soltanto nella forma che si conclude su una sola riga: riunite in una riga i vettori distribuiti su più righe prima di incollarli.
- 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.
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."""...""" e '''...''' non sono al momento previste e quella riga è segnalata come errore. Per i testi lunghi, convertitele in stringhe su una sola riga con le sequenze protette.
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.