Convertire YAML in TOML

Valori piatti e array vengono scritti in cima, poi ogni mappa nidificata appare come propria intestazione tabella tra parentesi quadre. Nidificare tre livelli in profondità produce un'unica intestazione con punti dentro invece di tre blocchi annidati, quindi una mappa scritta come tool, poi ruff, poi un'impostazione, esce come un'unica intestazione [tool.ruff] con l'impostazione sotto.

Quell'appiattimento delle intestazioni è la differenza visibile tra i due formati. YAML esprime la profondità con lo spazio bianco e può nidificare senza limiti prima di diventare illeggibile; TOML esprime la profondità nel nome dell'intestazione e resta leggibile a quattro livelli perché il percorso completo è scritto su ogni blocco. È lo scambio attorno a cui il formato è stato progettato, e per una config di progetto di solito è quello giusto.

Una riga scritta chiave: senza nulla dopo è YAML valido e viene analizzata come null. TOML non ha valore null — la specifica semplicemente non lo definisce — quindi lo scrittore omette la chiave. Nessun errore, nessun segnaposto, nessun commento: la chiave era nel proprio YAML e non è nel proprio TOML.

Conta più di quanto sembri perché le chiavi vuote sono un idioma YAML deliberato. Segnano un'impostazione come presente ma non impostata, tengono un posto per qualcosa che un operatore compilerà dopo, e documentano che un'opzione esiste. Tutto ciò è informazione, e tutto sparisce. Si cercano nella sorgente le righe che finiscono con due punti prima di convertire, e si decide per ognuna se dovrebbe portare un valore esplicito, una stringa vuota, o un commento nel TOML.

Lo stesso null dentro un array si comporta diversamente: lo scrittore si rifiuta, e la conversione fallisce con un messaggio che dice che gli array non possono contenere valori null o undefined. Nulla viene prodotto.

È il migliore dei due comportamenti, e l'incoerenza è deliberata piuttosto che accidentale. Scartare una chiave da una tabella lascia il resto della tabella significativo; scartare un elemento da un array sposta ogni elemento successivo, il che trasforma una lista ordinata in una lista ordinata diversa. Rifiutare è l'unica risposta sicura, e significa che un file YAML con un trattino vagante e nulla dopo lo dice invece di convertire in qualcosa di sottilmente sbagliato.

TOML raggruppa per tabella. Tutto ciò che appartiene a una tabella deve apparire dopo la sua intestazione e prima della successiva, quindi lo scrittore emette ogni scalare e array prima e poi ogni blocco nidificato a turno. Un .gitlab-ci.yml convertito così mette il suo array stages in cima e le definizioni job sotto come tabelle, a prescindere da come erano ordinate nel YAML.

La conseguenza da pianificare è il diff. Se il file YAML è in revisione e il TOML lo sostituisce nello stesso repository, il primo commit sembrerà una riscrittura invece di una traduzione, perché lo è. Si fa atterrare la conversione come proprio commit senza nient'altro dentro, così che il prossimo lettore veda che è cambiata solo la sintassi.

Uno scalare a blocco — il carattere pipe seguito da uno script shell indentato, come ogni file CI contiene i propri comandi di build — viene analizzato in una stringa contenente a capo, e lo scrittore la emette come una normale stringa TOML tra virgolette con escape backslash-n dentro. Uno script di dieci righe diventa una riga molto lunga.

TOML ha una sintassi stringa multiriga con virgolette triple che conterrebbe lo script leggibilmente, e lo scrittore non la usa. È una conversione da fare a mano: si trovano i valori con a capo sfuggiti dentro, e si riscrive ognuno come blocco tra virgolette triple. Vale la pena farlo per qualsiasi cosa un umano modificherà di nuovo, e non vale la pena per un valore che legge solo un programma.

TOML è l'unico formato in questa famiglia con date di prima classe: datetime con offset, datetime locali, date locali e ore locali fanno tutte parte della specifica e un parser TOML le restituisce come date piuttosto che stringhe. È il motivo principale per cui un progetto sceglie TOML su JSON.

Non le si ottiene da questa conversione. YAML 1.2 tratta un 2024-01-02 senza virgolette come stringa, quindi arriva nel TOML come "2024-01-02" con virgolette attorno. Togliere le virgolette da quei valori dopo è tutto il lavoro e richiede secondi; lasciarli tra virgolette funziona comunque e significa semplicemente che il proprio TOML contiene testo dove potrebbe contenere una data. Lo stesso vale per gli interi scritti con un punto decimale: un valore YAML di 1.0 diventa l'intero TOML 1, perché il parser lo ha risolto a un numero intero prima che lo scrittore lo vedesse.

Il costrutto per cui la gente si preoccupa risulta essere quello che funziona meglio. Una lista YAML i cui elementi sono mappe — una lista di autori, una lista di binari, una lista di job — diventa un array di tabelle TOML, con l'intestazione a doppia parentesi ripetuta una volta per elemento. È esattamente la forma che un pyproject.toml o un Cargo.toml vuole per i suoi autori e i suoi target.

Una lista in cima al file YAML è l'eccezione. I documenti TOML sono sempre una tabella, quindi un documento che è solo una lista viene avvolto in una tabella con una singola chiave chiamata items e la lista sotto. Se il proprio YAML è una sequenza alla radice, si decide da sé il nome della chiave e lo si aggiunge alla sorgente prima di convertire, così che il nome significhi qualcosa.

Le chiavi nude TOML permettono lettere, cifre, underscore e trattini. Qualsiasi altra cosa deve essere tra virgolette, e lo scrittore lo fa per conto proprio: una chiave contenente un punto esce come "date.timezone" virgolette incluse, e così una chiave contenente uno spazio. Le chiavi tra virgolette sono TOML del tutto valido.

Sono anche un segnale. Una chiave tra virgolette con un punto dentro di solito significa che il YAML esprimeva struttura nel nome della chiave invece che nella nidificazione, e in TOML quella struttura sarebbe meglio scritta come una vera tabella. Se dividerla sia una decisione riguarda la propria config, non la conversione, ma le virgolette nell'output sono un posto affidabile da cui iniziare a guardare.

Entrambi i formati supportano commenti e nessuno dei propri passa. Il parser li scarta leggendo e lo scrittore non ha nulla da scrivere. Su una config di progetto è un costo reale — la nota che spiega perché una dipendenza è fissata, l'alternativa commentata, la riga che dice a quale ambiente si applica un blocco.

La migrazione è finita solo quando quelli sono tornati. Si converte, poi si apre il vecchio YAML e il nuovo TOML fianco a fianco e si riattaccano i commenti dove appartengono. Sono dieci minuti su un file tipico ed è la differenza tra una config che qualcuno può mantenere e una che funziona e nessuno osa cambiare.