Convertire YAML in INI

L’INI ha un solo livello di raggruppamento: una sezione tra parentesi quadre e le chiavi al suo interno. Lo YAML ne ha quanti ne servono con l’indentazione. La conversione risolve la differenza percorrendo tutto l’albero, costruendo un percorso puntato per ogni valore finale, e dividendo poi ciascun percorso una sola volta: la parte prima del primo punto diventa la sezione, il resto diventa la chiave.

Così una mappa YAML chiamata database, che contiene pool, che contiene timeout, produce una sezione chiamata database e una chiave chiamata pool.timeout. Ogni valore sopravvive; solo la forma va persa. Chi legge il file dall’altra parte vede chiavi piatte con punti nel nome, senza modo di sapere quali punti erano indentazione e quali facevano parte del nome originale.

Una sequenza YAML non ha equivalente in INI, quindi ogni elemento diventa una chiave con il proprio indice. Uno script di build scritto come elenco di tre comandi esce come script.0, script.1 e script.2 dentro la sezione job, nell’ordine in cui erano scritti.

L’ordine viene mantenuto, ed è la parte che conta, ma la convenzione è nostra, non uno standard universale. Alcuni parser INI capiscono chiavi numerate come un elenco, la maggior parte no, e alcuni si aspettano invece una chiave ripetuta più volte. Conviene verificare cosa fa il programma che leggerà il file prima di dare per scontato che l’elenco sia sopravvissuto in modo utile.

Un elenco al livello più alto del documento non ha una chiave sotto cui essere numerato, quindi diventa una sezione chiamata come la chiave che lo conteneva, con 0, 1 e 2 come nomi delle sue chiavi. Un file YAML la cui chiave stages contiene due voci produce una sezione intitolata stages con una chiave chiamata 0 e una chiamata 1.

Una sezione piena di numeri è INI valido e appare strana a chiunque la legga. Se il programma di destinazione si aspetta un elenco separato da virgole in un’unica chiave — che è la convenzione INI più comune per una sequenza — conviene unire l’elenco già nello YAML prima di convertire, oppure nell’INI dopo.

Uno scalare a blocco YAML — una barra verticale seguita da un blocco indentato, il modo in cui ogni file CI contiene uno script di shell — viene interpretato come un’unica stringa con degli a capo dentro. Fino al 2026-08-09 lo strumento scriveva quella stringa così com’era, trasformando gli a capo in interruzioni di riga vere: la prima riga dello script finiva dopo il segno di uguale e ogni riga sotto restava per conto proprio. Rileggendo un file simile, quelle righe venivano scartate, e ogni riga che assomigliava a un’intestazione di sezione ne apriva una mai presente nello YAML originale.

Oggi lo strumento racchiude un valore multi-riga tra virgolette e scrive ogni interruzione come una barra rovesciata seguita da una n, così lo script resta su una sola riga, resta un’unica voce, e torna invariato attraverso questo convertitore. Quello che non cambia è la destinazione: i dialetti INI non sono d’accordo sulle sequenze di escape, e un parser che tratta una barra rovesciata come un carattere ordinario restituirà lo script con quei due caratteri visibili anziché un a capo.

Una chiave YAML senza nulla dopo diventa null e viene scritta come chiave, segno di uguale, e niente. L’INI non può esprimere la differenza tra una chiave non impostata e una stringa vuota, quindi entrambe tornano come stringa vuota dall’altra parte. Se la distinzione conta per il programma che legge il file, va codificata in altro modo — un valore sentinella, oppure lasciando la chiave del tutto assente.

I booleani vengono scritti come le parole true e false, esattamente quello che diceva l’origine, e non è quello che ogni consumatore di INI si aspetta: la configurazione di Windows e php.ini usano On e Off, e un parser che cerca quelle parole tratterà true come una stringa non riconosciuta. Le virgolette vengono applicate solo dove un valore non sopravvivrebbe altrimenti alla rilettura — un a capo al suo interno, uno spazio a un’estremità, o virgolette già presenti — quindi i valori ordinari mantengono la loro punteggiatura senza modifiche.

Una configurazione profonda due livelli, fatta di valori semplici e senza valori multi-riga, si converte perfettamente e non richiede alcuna correzione. Molte configurazioni applicative hanno esattamente questa forma, ed è il motivo per cui questa coppia esiste: un blocco di variabili d’ambiente di docker-compose o un insieme di flag di funzionalità si appiattisce senza perdere nulla che un lettore noterebbe.

Un file con elenchi di mappe no. Un elenco YAML di definizioni di server, ognuna con un host e una porta, diventa servers.0.host, servers.0.port, servers.1.host e così via dentro un’unica sezione: una codifica fedele dei dati e un file di configurazione illeggibile. Se è questo il vostro sorgente, la risposta onesta è che l’INI non è una destinazione adatta e la conversione produce qualcosa che dovrete comunque riscrivere.

Un valore semplice al livello più alto dello YAML — una versione, un nome, un singolo flag — non ha un genitore che possa diventare una sezione. Questi valori vengono scritti per primi, prima di qualunque intestazione tra parentesi, la convenzione INI standard per un blocco globale, capita dalla maggior parte dei parser.

Le sezioni seguono, nell’ordine in cui le loro chiavi comparivano nello YAML. Questo ordine conta se il file viene rivisto a occhio piuttosto che da una macchina, perché significa che l’output si legge più o meno nella stessa sequenza dell’origine, e un confronto tra due conversioni dello stesso file resta leggibile.

I commenti vengono persi. Entrambi i formati li supportano, ma l’analizzatore li scarta durante la lettura e lo strumento di scrittura non ha nulla da riscrivere. La spiegazione sopra un valore di timeout, quella che rendeva lo YAML utile da leggere, non è nell’INI.

Un file con separatori --- fallisce del tutto invece di convertire in parte. È voluto: un flusso YAML può contenere più documenti, un file INI descrive un solo insieme di impostazioni, e prendere in silenzio il primo documento produrrebbe una configurazione a cui manca gran parte di sé stessa. Conviene dividere il file e convertire solo il documento che serve.

La conversione vale la pena farla quando lo YAML è grande, piatto e ripetitivo. Non vale la pena quando l’origine è piccola: venti impostazioni si riscrivono a mano più in fretta di quanto ci si metta a convertire e poi correggere, e riscrivere costringe a leggere ogni valore una volta, un vantaggio più che un costo su una configurazione che sta per essere affidata a un programma vecchio.

È anche lo strumento sbagliato quando la destinazione si aspetta un dialetto INI specifico. Programmi che vogliono valori tra virgolette, booleani On e Off, elenchi separati da virgole o chiavi ripetute chiedono convenzioni che questo strumento non produce: convertite per estrarre i valori dall’albero, poi rimodellate per adattarli al parser che state effettivamente alimentando.