YAML naar TOML omzetten

Losse waarden en arrays worden bovenaan geschreven, en elke geneste mapping krijgt een eigen tabelkop tussen haakjes. Drie niveaus diep genest levert één kop met punten erin op, in plaats van drie geneste blokken.

Die afplatting van kopjes is het zichtbare verschil tussen de twee formaten. YAML drukt diepte uit met witruimte en kan eindeloos nesten voordat het onleesbaar wordt; TOML drukt diepte uit in de kopnaam en blijft leesbaar op vier niveaus omdat het volledige pad steeds wordt uitgeschreven.

Een regel geschreven als sleutel: met niets erna is geldige YAML en levert null op. TOML kent geen null — de specificatie definieert er simpelweg geen — dus de schrijver laat de sleutel weg. Geen foutmelding, geen placeholder: de sleutel stond in je YAML en staat niet in je TOML.

Dat weegt zwaarder dan het klinkt, want lege sleutels zijn een bewust YAML-idioom: ze markeren een instelling als aanwezig maar onbepaald. Doorzoek de bron op regels die op een dubbele punt eindigen voordat je omzet.

Diezelfde null binnen een array gedraagt zich anders: de schrijver weigert, en de omzetting mislukt met een melding dat arrays geen null of undefined mogen bevatten.

Dit is het betere van de twee gedragingen, en de inconsistentie is bewust. Een sleutel uit een tabel laten vallen laat de rest betekenisvol; een element uit een array laten vallen verschuift alles erna en verandert een geordende lijst in een andere.

TOML groepeert per tabel. Alles wat bij een tabel hoort moet na zijn kop en voor de volgende staan, dus de schrijver zet eerst elke losse waarde en array, en pas daarna elk genest blok als tabel.

Het gevolg om rekening mee te houden is de diff. Vervangt de TOML de YAML in dezelfde repository, dan ziet de eerste commit eruit als een herschrijving, want dat is het. Land de omzetting als eigen commit met verder niets erin.

Een blokscalair — het verticale streepje gevolgd door een ingesprongen shellscript, hoe elk CI-bestand zijn buildcommando’s bewaart — wordt geparst tot een string met newlines, en de schrijver geeft die weg als gewone TOML-string met backslash-n erin. Een script van tien regels wordt één zeer lange regel.

TOML heeft een meerregelige stringsyntax met drievoudige aanhalingstekens die het script leesbaar zou houden, en de schrijver gebruikt die niet. Dat is een omzetting die je met de hand doet — vind de waarden met ontsnapte newlines en herschrijf ze.

TOML is het enige formaat in deze familie met eersteklas datums: offset-datetimes, lokale datetimes, lokale datums en tijden zijn allemaal onderdeel van de specificatie, en een TOML-parser geeft ze als datum terug in plaats van als string.

Die krijg je hier niet automatisch. YAML 1.2 behandelt een niet-aangehaalde 2024-01-02 als string, dus die komt in de TOML aan als "2024-01-02" met aanhalingstekens erom. Die achteraf verwijderen kost seconden.

De constructie waar mensen zich zorgen om maken, blijkt juist het beste te werken. Een YAML-lijst met mappings als items — een lijst auteurs, een lijst binaries — wordt een TOML-array van tabellen, met de dubbele-haakjeskop herhaald per item.

Een lijst helemaal bovenaan het YAML-bestand is de uitzondering. TOML-documenten zijn altijd een tabel, dus een document dat alleen een lijst is, wordt verpakt in een tabel met één sleutel genaamd items.

TOML staat kale sleutels toe met letters, cijfers, underscores en streepjes. Al het andere moet aangehaald worden, en de schrijver doet dat automatisch: een sleutel met een punt erin komt aan als "date.timezone" met de aanhalingstekens erbij.

Aangehaalde sleutels zijn ook een signaal: een aangehaalde sleutel met een punt erin betekent vaak dat de YAML structuur uitdrukte in de sleutelnaam in plaats van in de nesting, en die zou in TOML beter als echte tabel geschreven worden.

Beide formaten ondersteunen commentaar en geen van jouw regels reist mee. De parser gooit ze weg bij het lezen en de schrijver heeft niets om te schrijven. Op een projectconfig is dat een echte kost — de notitie waarom een afhankelijkheid vastgezet is.

De migratie is pas klaar als die terug zijn. Zet, na het omzetten, de oude YAML en de nieuwe TOML naast elkaar en herplaats de commentaren waar ze horen.