TOML naar NDJSON omzetten

Een TOML-document is een tabel. Er bestaat geen TOML-bestand dat op het hoogste niveau een lijst is — de specificatie staat het niet toe — dus de recordgrens die newline-delimited JSON nodig heeft, verschijnt nooit binnen één bestand. Het hele document wordt één regel.

Voor de meeste bronnen zou dat een beperking zijn. Hier is het de vorm van het probleem: niemand wil een pyproject.toml in fragmenten gesplitst, en iedereen die er een naar NDJSON omzet, bouwt een verzameling waarin elk bestand een record is.

De werkwijze: zet elk bestand om, voeg de regel toe aan een groeiend uitvoerbestand. Omdat elke regel een complete, op zichzelf staande JSON-waarde is en niets het bestand omwikkelt, is samenvoegen de hele mergestap. Twee regels uit twee omzettingen vormen een geldig NDJSON-bestand met twee records.

Dat levert een dataset op waar je vragen aan kunt stellen. Welke crates een specifieke afhankelijkheidsversie vastpinnen, welke pakketten geen licentie declareren — allemaal één query over de verzameling in plaats van een script dat mappen doorloopt.

Een record zonder bron is bijna nutteloos in een inventaris. De omzetter leest de inhoud van een bestand en verder niets — hij kent het pad, de repository of de commit niet, dus de regel die hij produceert zegt niet waar hij vandaan kwam.

Voeg het zelf toe, op een van twee momenten. Een jq-stap tijdens het samenvoegen kan een pad-sleutel per regel injecteren, wat de TOML-bestanden onaangeroerd laat. Een sleutel binnen elk TOML-bestand overleeft elke toekomstige omzetting maar betekent bestanden bewerken die van anderen zijn.

Compacte JSON: geen inspringing, geen spaties na dubbele punten, sleutels in de volgorde van de TOML, eindigend met een regeleinde. Tabellen worden geneste objecten en arrays van tabellen worden arrays van objecten.

De regel is zo lang als de config is. Een pyproject.toml is een paar kilobyte, en een gegenereerde lock-achtige config kan veel groter zijn, en een lezer die regel voor regel verwerkt, moet de hele regel in het geheugen houden.

TOML heeft echte temporele typen en JSON niet, dus elke datum en datumtijd wordt een string. Offsets blijven behouden in plaats van naar UTC genormaliseerd, een lokale datum komt precies zo aan als geschreven.

Twee float-literalen zijn lossy op een manier die niets meldt: inf en nan zijn geldige TOML en worden null in JSON, dus een geconfigureerde oneindige limiet en een niet-geconfigureerde worden onderscheidbaar in de dataset. Het onderscheid geheel getal/float verdwijnt ook, want 1.0 serialiseert als 1.

TOML 1.0 vereist 64-bit ondertekende gehele getallen en JSON-getallen zijn IEEE-doubles, dus een waarde boven ongeveer negen biljard kan niet exact weergegeven worden. De parser stopt met een fout die de regel noemt in plaats van een afgerond getal in je dataset te schrijven.

Dat is correct gedrag, vooral voor een inventaris, waar een fout getal niet te onderscheiden zou zijn van een goed getal over tienduizend records. Zet de waarde tussen aanhalingstekens in het bronbestand — het was in elk echt geval waarin dit voorkomt een identificatiecode, geen hoeveelheid.

Configs uit verschillende projecten hebben niet dezelfde secties. De ene declareert een tool-tabel met drie linters erin, de volgende geen, een derde gebruikt een sleutel die niemand anders gebruikt. Elke regel draagt alleen de sleutels die zijn bestand had, een echt voordeel boven dezelfde verzameling platslaan naar een tabel.

De bestemming bepaalt hoeveel dat kost. Een schema-on-read-opslag verwerkt onregelmatige records nativement. Een lader met vast schema wijst de uitschieters af of laat velden vallen. Bekijk het breedste en smalste bestand in de verzameling voor je het doel definieert.

TOML-commentaar is de redenering in een config: waarom een afhankelijkheid vastgepind is, welk ticket bij een workaround hoort. NDJSON is JSON per regel en JSON kent geen commentaarsyntaxis, dus verdwijnt alles daarvan uit de dataset.

Dat is aanvaardbaar voor een inventaris en onaanvaardbaar als migratie. Niemand die opzoekt welke pakketten een versie vastpinnen heeft de omringende proza nodig; wie de TOML-bestanden zou vervangen door iets uit deze data gegenereerd, zou het wegwerpen.

Heb je maar één config te lezen, zet die dan om naar JSON in plaats van NDJSON. Ingesprongen JSON is leesbaar, jq verwerkt het identiek, en een bestand van één regel is voor elk ander doel slechter dan toevoegen. NDJSON verdient zijn plek zodra er veel bestanden zijn die ergens naartoe gaan.

De andere grens is herhaling. Moet de inventaris op een schema opnieuw opgebouwd worden, dan hoort het werk in een script dat de boom doorloopt, elk bestand met een echte TOML-bibliotheek ontleedt en de regels met het pad al eraan vast uitvoert. Deze omzetter is voor de eerste keer de dataset bouwen.