Convertire INI in YAML

Ogni intestazione di sezione diventa una chiave al livello superiore, e le sue impostazioni sono rientrate di due spazi sotto di essa. Le chiavi scritte sopra la prima intestazione di sezione restano al livello superiore accanto a quei blocchi. L’output usa spazi dappertutto: YAML vieta le tabulazioni per il rientro, e un convertitore che le emettesse produrrebbe un file che nessun parser accetta.

Il risultato è un documento YAML valido, non un frammento. La distinzione conta quando la destinazione è un values file o un insieme di variabili, perché di solito si vorrà il blocco intero annidato di un livello sotto una chiave propria, ed è più facile rientrare un documento di cui si conosce la validità che ragionare su un frammento.

I file INI dicono On e Off molto più spesso di true e false. php.ini lo fa, la configurazione di Windows lo fa, e decine di demoni lo fanno. Il lettore qui non tratta quelle parole come booleani, quindi restano stringhe, e chi scrive le emette non quotate: engine: On.

Se quella riga significhi una stringa o un booleano dipende da quale versione di YAML il parser implementa. YAML 1.2, la versione che il registro indica per il formato e la versione che il parser di questa pagina implementa, dice che è la stringa «On». YAML 1.1 dice che è il booleano true, e PyYAML implementa 1.1, il che significa che Ansible, e una lunga coda di strumenti Python, leggeranno quella riga come un booleano. Lo stesso vale per yes, no, y e n.

La soluzione è mettere fra virgolette, e va fatto a mano perché il convertitore non può sapere quali dei valori On erano pensati come interruttori. Scrivere engine: "On" per volere la stringa in ogni parser, o engine: true per volere il booleano in ogni parser. Entrambe sono non ambigue sotto 1.1 e 1.2, che è l’unica proprietà che valga la pena di ottimizzare.

Vale la pena di fare il passaggio in modo deliberato invece di aggiustare quelli che si rompono. Un booleano letto come stringa di solito è truthy e quindi silenziosamente acceso, e una stringa letta come booleano di solito fallisce uno schema in modo vistoso; la direzione pericolosa è quella silenziosa, dove un’impostazione disabilitata torna abilitata e nulla fallisce finché qualcosa non fallisce.

La tipizzazione avviene durante la lettura dell’INI, non durante la scrittura dello YAML, quindi quando lo scrittore YAML parte la decisione è già presa. I valori che si analizzano come numeri finiti diventano numeri, true e false diventano booleani, e il resto resta una stringa.

Tre casi in un file di configurazione escono modificati. Una versione fermata a 1.0 diventa 1. Un permesso file scritto 0755 diventa 755, che non è lo stesso permesso. Una maschera esadecimale scritta 0x1F diventa 31. I valori con un’unità attaccata sono al sicuro, quindi 128M resta 128M e 30s resta 30s, e lo sono gli indirizzi come 127.0.0.1 e gli orari come 08:00, che non si analizzano come un singolo numero. Una stringa che contiene almeno una lettera che non è parte di un numero resta una stringa, ed è la regola che protegge la maggior parte delle password e dei nomi di servizio dentro un INI.

Un’intestazione scritta [tool.pytest] o [mail.smtp] diventa una sola chiave con quel nome esatto, non due livelli di annidamento. Il lettore prende tutto ciò che sta fra parentesi come un nome unico, che è l’unica lettura difendibile: in php.ini, chiavi e sezioni sono piene di punti che fanno parte del nome.

YAML accetta una chiave del genere non quotata, quindi l’output è valido e si legge bene. Non è nemmeno ciò che un chart Helm o un ruolo Ansible vogliono, dove mail.smtp.host normalmente sarebbero tre livelli. Spezzarlo è un edit manuale e deliberato, perché si sta decidendo qualcosa che il file di partenza non diceva mai.

Le configurazioni assemblate accodando un overlay di ambiente a un file di base finiscono con la stessa intestazione di sezione due volte. Il lettore crea una sezione nuova e vuota ogni volta che vede un’intestazione, quindi solo l’ultima occorrenza sopravvive e quella precedente viene eliminata senza un messaggio.

Vale la pena di controllare prima della migrazione, non dopo, perché l’output è uno YAML ben formato a cui mancano delle impostazioni, e una chiave mancante in una distribuzione di solito si presenta come un default applicato silenziosamente invece di come un errore. Cercare nell’INI le intestazioni duplicate prima; la stessa regola del «vince l’ultimo» si applica a una chiave ripetuta dentro una sola sezione.

YAML supporta i commenti, INI supporta i commenti, e nessuno dei vostri sopravvive a questa conversione. Le righe di commento sono saltate durante la lettura e nulla le riscrive, quindi un file che era per metà spiegazione arriva come sole impostazioni.

Su una configurazione modificata sul posto per anni, quei commenti sono la memoria istituzionale: la nota per cui un timeout è stato alzato per un report, il blocco commentato durante un incidente e mai rimosso, le iniziali e la data accanto a un valore che nessuno vuole toccare. Copiare il file INI originale nel repository nello stesso commit dello YAML. Non costa nulla, ed è l’unico posto in cui quel ragionamento esiste ancora.

Il lettore e chi scrive sono entrambi JavaScript in questa pagina, quindi il file non viene mai spedito altrove. È una proprietà generale delle conversioni di dati qui, e questa coppia è quella in cui si guadagna: il file INI che si sta migrando da un vecchio server è molto spesso il file con la password del database, le credenziali SMTP e le chiavi API.

Il tetto gratuito è 100 MB, che nessun file di configurazione raggiunge. In pratica la conversione è istantanea, e l’unica cosa che vale la pena fare con calma dopo è leggere l’output, perché nel momento in cui quei segreti sono in un file YAML dentro un repository, sono nella storia del repository per sempre, ed è una decisione da prendere prima del commit, non dopo.

Se l’applicazione legge ancora INI e sempre lo farà, convertire è lavoro inutile. YAML compra annidamento, liste, commenti in revisione e un linter, e niente di tutto ciò aiuta un programma il cui parser si aspetta sezioni e segni di uguale. La migrazione vale quando la configurazione sta andando in un sistema che legge YAML in modo nativo, non quando il file sembra solo vecchio.

L’altra ragione onesta per fermarsi è la dimensione. Un file con tre sezioni e venti chiavi è più veloce da riscrivere a mano nella struttura di destinazione che da convertire e poi rimodellare, e riscrivere a mano significa rileggere ogni valore una volta. Usare il convertitore quando il file è abbastanza grande che rileggerlo a mano è l’opzione soggetta a errori.