XML naar TOML omzetten

Elk element met kinderen wordt een tabel, geschreven als een kop tussen haken die het volledige pad met punten benoemt. Een element drie niveaus diep levert één kop op met drie namen erin in plaats van drie geneste blokken, want TOML drukt diepte uit in de kop en niet in de inspringing.

Binnen elke tabel komen platte waarden eerst en geneste tabellen erna, wat de enige volgorde is die TOML toestaat — alles onder een kop hoort erbij tot de volgende kop verschijnt. Dat betekent dat de uitvoer niet in dezelfde volgorde leest als de XML, en op een configuratie met veel kleine elementen is de herschikking aanzienlijk. Het is een herordening, geen wijziging: geen waarde verhuist naar een ander pad.

Dit is het deel van de omzetting dat geen reparatie nodig heeft. Twee of meer zusterelementen met dezelfde tag worden een TOML-array van tabellen, met de dubbele-hakenkop eenmaal per item in documentvolgorde geschreven. Een lijst afhankelijkheden, een lijst servers, een lijst regels — allemaal landen ze in de vorm die een TOML-configuratie toch al zou gebruiken.

De vertrouwde XML-eigenaardigheid geldt er nog steeds onder. Eén voorkomen van een herhaalbaar element is geen array, dus wordt het een gewone tabel met een enkele-hakenkop in plaats daarvan. Zet een bestand met één item om en hetzelfde bestand met twee, en de twee uitvoeren verschillen structureel. Is de configuratie gegenereerd of ingecheckt in een repository, dan is dat een diff die je wilt begrijpen voordat hij verschijnt.

TOML-blote sleutels staan alleen letters, cijfers, underscores en koppeltekens toe. Attributen komen van de parser als sleutels die beginnen met @, de eigen tekst van een element onder een sleutel genaamd #text, en een naamruimteverklaring als iets als @xmlns:soap. Ze zijn allemaal aangehaald in de uitvoer, wat correcte TOML is en er precies zo vreemd uitziet als het klinkt.

Ze zijn ook een to-dolijst. Een aangehaalde sleutel is de converter die je vertelt dat deze naam uit XML-machinerie komt en niet uit je configuratie, en vrijwel elke moet hernoemd worden: een @value-attribuut wordt een gewone value-sleutel, een @xmlns-sleutel wordt verwijderd, een #text-sleutel wordt wat het element daadwerkelijk droeg. Doe die ronde eenmalig, meteen, terwijl je nog weet wat de XML betekende.

Een TOML-document is zelf een tabel, en een XML-document heeft precies één hoofdelement, dus verschijnt de hele configuratie één niveau dieper dan je wilt — onder één kop vernoemd naar dat hoofdelement. Een bestand geworteld op configuration levert een configuration-tabel op die alles bevat.

De inhoud promoveren is een mechanische bewerking: verwijder de eerste kop en haal dat segment uit elke andere kop in het bestand. Het is de moeite waard om te doen in plaats van ermee te leven, want elk pad in de configuratie wordt een niveau korter en een TOML-bestand wordt gelezen aan zijn koppen. Het met de hand doen dwingt ook één ronde over het hele bestand af, wat bij een migratie goed bestede tijd is.

TOML kent geen null-waarde, en omzetten vanuit formaten die er wel een hebben — YAML voorop — betekent sleutels die stilletjes verdwijnen als hun waarde leeg is. Dat kan hier niet gebeuren, want XML kent ook geen null. Een leeg element en een zelfsluitend element betekenen hetzelfde en worden allebei een lege tekenreeks, geschreven als twee aanhalingstekens.

De garantie voor deze richting is dus sterker dan voor haar buren: elk element dat een waarde had in de XML heeft een sleutel in de TOML. Lege tekenreeksen zijn makkelijk over het hoofd te zien in een lang bestand, dus als de migratie ook een kans is om instellingen die niemand gebruikt te verwijderen, is de uitvoer doorzoeken op die lege paren de snelste manier om ze te vinden.

TOML zet datum en tijd in de kernspecificatie — offset-datumtijden, lokale datumtijden, lokale datums en lokale tijden — en een parser geeft ze terug als datums en niet als tekenreeksen. YAML heeft ook een tijdstempeltag, maar die hoort bij de 1.1-typebibliotheek en niet bij het 1.2-kernschema, dus wat een loader teruggeeft hangt af van welke loader het is. TOML's vier typen zijn dat niet.

Een XML-waarde is tekst, dus komt een datum in de bron aan als een aangehaalde tekenreeks en blijft dat. De aanhalingstekens weghalen bij die waarden in de uitvoer is wat ze echte TOML-datums maakt, en het kost een minuut. Het omgekeerde geval is ook de moeite waard om op te letten: een waarde geschreven als 1.0 in de XML wordt als getal geparseerd en als de TOML-integer 1 geschreven, dus is een versie een geheel getal geworden en zijn vorm kwijtgeraakt. Hem weer aanhalen is de oplossing.

Een element met meerdere regels — een beschrijving, een licentieblok, een ingesloten script — wordt één gewone TOML-tekenreeks met backslash-n-escapes waar de regeleindes stonden. Het is correct en het is onleesbaar, en het ondermijnt het doel van naar een formaat overstappen dat mensen met de hand bewerken.

TOML heeft een syntaxis voor tekst over meerdere regels met drievoudige aanhalingstekens die zo'n waarde leesbaar houdt, en de schrijver gebruikt die niet. Vind de waarden met escapes erin en herschrijf elk als een blok met drievoudige aanhalingstekens. In de meeste configuraties zijn er een of twee; in een configuratie vol ingebedde tekst is dat een signaal dat de inhoud beter in zijn eigen bestand kan wonen dan in een instellingenbestand.

Commentaar valt weg, hoewel beide formaten het ondersteunen, dus verschijnen de uitleg in het oude bestand niet in het nieuwe. Naamruimtes houden op iets te betekenen zodra de voorvoegsels tekens in een sleutel worden. En het schema gaat verloren: XML kan tegen een XSD gevalideerd worden voordat een toepassing start, en TOML heeft geen schemataal in zijn specificatie.

Dat laatste is de ruil om bewust te maken. TOML is makkelijker te lezen, makkelijker met de hand te schrijven en ondubbelzinnig over typen, en het geeft het vermogen op om een misvormde configuratie mechanisch af te wijzen. Werd de XML echt gevalideerd in je build, dan verwijder je een controle, en die vervangen — met een controle bij het opstarten van de toepassing — hoort bij de migratie en is geen extraatje.

Wat het gereedschap je geeft is elke waarde uit de XML, in de juiste tabel, met de juiste naam in de meeste gevallen en een aangehaalde, overduidelijk verkeerde naam bij de rest. Dat is een goed startpunt en geen afgerond configuratiebestand.

Het werk erna is klein en niet optioneel: de hoofdtabel verwijderen, de @- en #text-sleutels hernoemen, de datums uitkleden, de waarden over meerdere regels herschrijven, en het commentaar uit het origineel overkopiëren. Een uur op een groot bestand. Overslaan levert een TOML-configuratie op die werkt en waarvan niemand die hem later leest zal geloven dat hij met opzet zo geschreven is.