Convertire INI in JSON

Il risultato è un singolo oggetto JSON. Ogni intestazione di sezione diventa una chiave che contiene un oggetto, e le coppie chiave-valore sotto quell’intestazione diventano proprietà di quell’oggetto. Le chiavi scritte prima di qualsiasi intestazione, quelle che molti strumenti chiamano il blocco globale, stanno al livello superiore accanto agli oggetti delle sezioni, invece di finire in un contenitore dedicato.

Questa è l’intera traduzione strutturale, perché non c’è nient’altro in un file INI da tradurre. Ciò che rende questa conversione degna di essere letta non è la forma, ma i valori, che non sopravvivono al viaggio in modo altrettanto letterale.

Un file INI non ha tipi. Tutto ciò che sta dopo il segno di uguale è caratteri, e ogni programma che lo legge decide da solo cosa significhino. Qui la regola è: le stringhe esatte true e false diventano booleani JSON, ciò che si analizza come numero finito diventa un numero JSON, e il resto resta una stringa.

Per la maggior parte delle configurazioni è la scelta giusta e risparmia un passaggio di parseInt dall’altra parte. Una porta esce come 8080 anziché «8080», un timeout come 30, e un flag negativo come -1 come numero confrontabile. Il costo è che il lettore non distingue una quantità da un identificatore, ed è lì che arriva il danno.

Quattro casi falliscono in silenzio e tutti e quattro compaiono in file di configurazione reali. Un identificatore con zero iniziale scritto 007 diventa il numero 7. Un permesso Unix scritto 0755 diventa 755, che è un permesso diverso e sarà applicato come tale. Una maschera esadecimale scritta 0x1F diventa 31, corretta nel valore e sbagliata in ogni riga di log che la ristampa. Una versione fermata a 1.0 diventa 1.

Il quarto caso è più sottile: un intero più grande di circa nove quadrilioni perde precisione, perché i numeri JSON sono double IEEE. Un identificatore a 64 bit scritto 9223372036854775807 esce come 9223372036854776000, senza nessun avviso. Se una chiave contiene uno snowflake ID, un numero seriale o un riferimento di conto, meglio virgolettarlo nel file INI di partenza; i valori fra virgolette vengono comunque analizzati, quindi la soluzione più sicura è premettere o posporre qualcosa di non numerico, o correggere il valore nel JSON dopo.

Vale la pena sapere quali chiavi non serve controllare. Tutto ciò che ha un’unità attaccata è al sicuro, quindi un limite di memoria scritto 128M resta la stringa 128M. Gli indirizzi dotted restano stringhe, quindi 127.0.0.1 passa intatto. Orari come 08:00 restano stringhe, e lo stesso vale per percorsi, URL e tutto ciò che contiene una lettera che non fa parte di un numero.

Anche un valore che contiene un segno di uguale sopravvive, perché la riga viene divisa solo al primo uguale, e questo preserva integre una stringa di connessione o un parametro di query. Le virgolette esterne vengono tolte, ma solo la coppia più esterna: un valore scritto con spaziatura dentro le virgolette conserva quella spaziatura, mentre un valore non quotato viene rifilato a entrambe le estremità. Dentro le virgolette, e solo lì, un backslash avvia un escape: un backslash e una n diventano un a-capo, e due backslash diventano uno. È questo che permette a un valore multi-linea di sopravvivere al viaggio fuori e dentro un INI, ed è perché un percorso Windows non quotato come C:\new viene letto esattamente com’è mentre lo stesso percorso fra virgolette non lo è.

I file INI di Windows e php.ini usano On e Off molto più spesso di true e false, e il lettore non li tratta come booleani. Escono come le stringhe «On» e «Off», il che è difendibile — sono, in fondo, solo parole — ed è quasi sempre non ciò che chi consuma il JSON si aspetta.

Lo stesso vale per yes e no, e per 1 e 0 usati come flag, che diventano i numeri 1 e 0 invece di booleani. Qualunque cosa legga il JSON deve decidere cosa conta come truthy, e l’abitudine più sicura è normalizzare quelle chiavi in modo esplicito nel codice che consuma, invece di presumere che la conversione le abbia rese coerenti. Una configurazione con engine impostato a On e debug impostato a false si trova adesso due tipi diversi di sì.

L’ordine delle chiavi è preservato quasi sempre, e questo conta quando si legge una diff invece di una macchina. Le sezioni escono nell’ordine in cui comparivano, e le chiavi dentro una sezione mantengono l’ordine in cui sono state scritte.

L’eccezione sono le chiavi numeriche. Gli oggetti JavaScript mettono le chiavi intere per prime e in ordine numerico ascendente, prima di tutte le altre, quindi una sezione scritta 10, 2, name esce come 2, 10, name. I file INI che usano numeri come chiavi, come elenchi di server, regole ordinate o voci di playlist, escono riordinati. Se l’ordine ha significato in un certo file, quella sezione vuole diventare un array JSON, e trasformarla è un edit manuale.

INI non ha una specifica, quindi le implementazioni sono in disaccordo su cosa significhi un’intestazione di sezione ripetuta: alcune uniscono i due blocchi, alcune li tengono entrambi, alcune prendono l’ultimo. Questo lettore apre una sezione nuova e vuota ogni volta che incontra un’intestazione, quindi un file che contiene [logging] due volte conserva solo le chiavi del secondo blocco. Il primo è andato, e il JSON è valido, e nulla lo segnala.

Questo schema compare ogni volta che le configurazioni vengono assemblate per concatenazione, che è un trucco di distribuzione frequente: un file di base più un overlay di ambiente, accodato. Prima di convertire, cercare intestazioni duplicate nel sorgente. Le chiavi ripetute dentro una sola sezione si comportano allo stesso modo, e vince l’ultima assegnazione.

Questa è la perdita strutturale, non incidentale. INI supporta i commenti e li usa parecchio; JSON, come da RFC 8259, non ha alcuna sintassi per i commenti. Anche un convertitore che volesse conservarli non avrebbe dove metterli, se non inventando una convenzione come una chiave `_comment` che nessun consumatore leggerebbe.

Su un file di impostazioni questa è spesso la cosa più grande che si perde. La nota che spiega perché la dimensione del pool è 12 invece del default, il blocco commentato lasciato come esempio, la riga che segnala un valore tarato per un cliente: niente di tutto ciò passa. Conservare il file INI originale nel controllo di versione accanto al JSON, invece di trattare la conversione come una sostituzione.

L’output è un JSON ordinario con indentazione di due spazi, quindi jq, Node, Python e ogni validatore di JSON Schema lo leggono senza cerimonie. Una sezione diventa un percorso di oggetto, .database.host in jq, e uno schema può quindi affermare che la porta è un numero e l’host è una stringa, che è il guadagno reale rispetto al file INI, dato che un file INI non può essere validato da nulla.

Conversioni di file di queste dimensioni sono istantanee e girano interamente nel browser, con un tetto di 100 MB sul piano gratuito che nessun file di configurazione raggiungerà mai. Il vincolo pratico non è la dimensione, ma la revisione: leggere i valori numerici nell’output una volta, prima che il JSON diventi il file di cui tutto il resto si fida.