INI naar JSON omzetten

Het resultaat is één JSON-object. Elke sectiekop wordt een sleutel met een eigen object, en de sleutel-waardeparen daaronder worden de eigenschappen van dat object. Sleutels vóór de eerste sectiekop — wat veel tools het globale blok noemen — staan op het hoogste niveau naast de sectieobjecten.

Dat is de hele structurele vertaling, want er is verder niets in een INI-bestand om te vertalen. Wat dit paar de moeite waard maakt om te lezen, is niet de vorm maar de waarden, die de overtocht minder letterlijk overleven dan de vorm.

Een INI-bestand kent geen typen. Alles na het isgelijkteken is tekens, en elk programma dat het leest beslist zelf wat die tekens betekenen. Deze lezer beslist zo: de exacte tekst true en false worden JSON-booleans, alles wat als een eindig getal leest wordt een JSON-getal, en de rest blijft tekst.

Voor de meeste configuratie is dat de juiste keuze en scheelt het een parseInt-stap aan de andere kant. Een poort komt eruit als 8080 in plaats van "8080". De prijs is dat de lezer geen hoeveelheid van een identificatiecode kan onderscheiden, en daar ontstaat de schade.

Vier gevallen falen stilzwijgend en komen alle vier in echte configbestanden voor. Een identificatiecode geschreven als 007 wordt het getal 7. Een Unix-bestandsmodus geschreven als 0755 wordt 755, een andere modus die zo ook wordt toegepast. Een hexadecimaal masker geschreven als 0x1F wordt 31, correct in waarde en fout in elke logregel die het terugprint.

Het vierde is subtieler: een geheel getal groter dan ongeveer negen biljard verliest precisie, omdat JSON-getallen IEEE-doubles zijn. Bevat een sleutel een snowflake-ID of serienummer, zet het dan tussen aanhalingstekens in de bron-INI, of geef het een niet-numeriek voor- of achtervoegsel.

Het is nuttig om te weten welke sleutels je niet hoeft te controleren. Alles met een eenheid erbij is veilig, dus een geheugenlimiet geschreven als 128M blijft de tekst 128M. IP-adressen blijven tekst, zo ook kloktijden zoals 08:00, paden, URL’s, en alles met een letter die geen deel is van een getal.

Een waarde met een isgelijkteken erin overleeft ook, want de regel wordt alleen bij het eerste teken gesplitst. Omringende aanhalingstekens worden verwijderd, maar alleen het buitenste paar. Binnen die aanhalingstekens, en alleen daar, begint een backslash een ontsnappingsteken: backslash-n wordt een regeleinde.

Windows-INI-bestanden en php.ini gebruiken On en Off veel vaker dan true en false, en de lezer behandelt ze niet als booleans. Ze komen eruit als de tekst «On» en «Off», wat verdedigbaar is maar bijna nooit is wat de gebruiker van de JSON verwacht.

Hetzelfde geldt voor yes en no, en voor 1 en 0 als vlaggen gebruikt, die getallen worden in plaats van booleans. Normaliseer die sleutels expliciet in de code die de JSON leest in plaats van consistentie aan te nemen.

Sleutelvolgorde blijft bijna overal behouden, wat telt als je een diff leest in plaats van een machine. Secties komen in de volgorde waarin ze verschenen, sleutels binnen een sectie houden hun geschreven volgorde.

De uitzondering zijn numerieke sleutels. JavaScript-objecten zetten geheeltallige sleutels vooraan in oplopende numerieke volgorde, vóór elke andere sleutel, dus een sectie geschreven als 10, 2, naam komt eruit als 2, 10, naam. Is volgorde betekenisvol in je bestand, dan wil die sectie eigenlijk een JSON-array zijn.

INI heeft geen specificatie, dus implementaties zijn het oneens over herhaalde sectiekoppen: sommige voegen samen, sommige houden beide, sommige nemen de laatste. Deze lezer begint elke keer een nieuwe, lege sectie bij een kop, dus een bestand met [logging] tweemaal behoudt alleen de sleutels van het tweede blok.

Dat patroon komt voor als configuraties door aaneenschakeling worden opgebouwd — een basisbestand plus een omgevingslaag. Zoek vooraf op dubbele koppen. Dubbele sleutels binnen één sectie gedragen zich hetzelfde, waarbij de laatste toewijzing wint.

Dit verlies is structureel, geen bijzaak. INI ondersteunt commentaar en gebruikt het volop; JSON, zoals gespecificeerd in RFC 8259, kent geen commentaarsyntaxis. Zelfs een omzetter die commentaar wilde bewaren, zou nergens naartoe kunnen zonder een conventie als een _comment-sleutel te verzinnen.

Bij een instellingenbestand is dit vaak het grootste verlies. De notitie die uitlegt waarom een poolgrootte 12 is in plaats van de standaard — niets daarvan komt over. Bewaar het originele INI-bestand in versiebeheer naast de JSON.

De uitvoer is gewone JSON met inspringing van twee spaties, dus jq, Node, Python en elke JSON Schema-validator lezen hem zonder omhaal. Een sectie wordt een objectpad — .database.host in jq — en een schema kan dan afdwingen dat de poort een getal is.

Omzettingen van bestanden op deze schaal zijn ogenblikkelijk en draaien volledig in de browser, met een plafond van 100 MB op het gratis niveau dat geen configuratiebestand ooit haalt. De echte beperking is niet grootte maar controle: lees de numerieke waarden in de uitvoer één keer na.