YAML in TOML umwandeln

Ein Python-Paket richtet seine Einstellungen inzwischen in pyproject.toml ein, ein Rust-Projekt in Cargo.toml, und wer bislang eine eigene YAML-Datei dafür gepflegt hat, muss sie einmal umstellen. Das kommt gerade bei öffentlich finanzierter Software häufiger vor, seit die Initiative Öffentliches Geld, Öffentlicher Code Behörden und Institute dazu drängt, intern entwickelte Werkzeuge sauber verpackt zu veröffentlichen — und ein sauber verpacktes Python-Projekt bedeutet heute meist pyproject.toml.

Diese Umwandlung übernimmt die mechanische Seite davon: Sie liest die YAML und schreibt eine TOML-Datei mit derselben Struktur, so weit TOML das ausdrücken kann. Zwei Gewohnheiten aus der YAML-Welt überstehen den Weg nicht, und die stehen weiter unten, weil sie beim ersten Durchlesen der Ausgabe leicht übersehen werden.

Einfache Werte und Listen stehen oben, danach folgt jede verschachtelte Zuordnung als eigener Tabellenkopf in eckigen Klammern. Eine drei Ebenen tiefe Verschachtelung ergibt einen einzigen Kopf mit Punkten statt drei ineinander verschachtelter Blöcke — aus tool, darin ruff, darin einer Einstellung wird ein einziger [tool.ruff]-Kopf mit der Einstellung darunter.

Diese Abflachung der Köpfe ist der sichtbare Unterschied zwischen beiden Formaten. YAML drückt Tiefe über Einrückung aus und kann beliebig weit schachteln, bevor es unlesbar wird; TOML drückt Tiefe im Namen des Kopfes aus und bleibt bei vier Ebenen noch lesbar, weil der vollständige Pfad in jedem Block ausgeschrieben steht.

Eine Zeile mit einem Schlüssel und nichts dahinter ist gültiges YAML und wird zu null geparst. TOML kennt keinen Nullwert — die Spezifikation sieht schlicht keinen vor —, also lässt der Schreiber den Schlüssel ganz weg. Keine Fehlermeldung, kein Platzhalter: Der Schlüssel stand in der YAML und steht nicht mehr in der TOML.

Das wiegt mehr, als es klingt, weil leere Schlüssel in YAML eine bewusste Konvention sind — sie markieren eine Einstellung als vorhanden, aber noch offen, oder dokumentieren, dass eine Option existiert. All das verschwindet still. Vor der Umwandlung lohnt es sich, nach Zeilen zu suchen, die mit einem Doppelpunkt und nichts danach enden, und für jede zu entscheiden, ob sie einen echten Wert, eine leere Zeichenkette oder einen Kommentar in der TOML bekommen soll.

Dasselbe null innerhalb einer Liste verhält sich anders: Der Schreiber verweigert die Arbeit, und die Umwandlung schlägt mit einer Meldung fehl, dass Arrays keinen null-Wert enthalten dürfen. Es entsteht keine Datei.

Das ist das bessere der beiden Verhalten, und die Uneinheitlichkeit ist Absicht. Einen Schlüssel aus einer Tabelle zu lassen, lässt den Rest der Tabelle sinnvoll; ein Element aus einer Liste zu lassen, verschiebt jedes Element danach und macht aus einer geordneten Liste eine andere geordnete Liste. Ablehnen ist die einzig sichere Antwort — eine YAML mit einem leeren Listeneintrag sagt das lieber, statt still etwas leicht Falsches zu produzieren.

TOML gruppiert nach Tabelle. Alles, was zu einer Tabelle gehört, muss nach ihrem Kopf und vor dem nächsten stehen, also schreibt der Konverter zuerst alle einfachen Werte und Listen und danach jeden verschachtelten Block der Reihe nach. Eine umgewandelte CI-Konfiguration setzt ihr stages-Array nach oben und die Job-Definitionen darunter als Tabellen, unabhängig davon, wie sie in der YAML standen.

Wichtig für den Diff: Liegt die YAML-Datei zur Prüfung im selben Repository und wird durch die TOML ersetzt, sieht der erste Commit wie eine Neufassung aus, weil er genau das ist. Die Umwandlung als eigenen Commit ohne weitere Änderungen einzuchecken lässt spätere Leser erkennen, dass sich nur die Syntax geändert hat.

Ein Blockskalar — das Pipe-Zeichen mit eingerücktem Shell-Skript darunter, wie es jede CI-Datei für ihre Build-Befehle nutzt — wird zu einer Zeichenkette mit Zeilenumbrüchen und vom Schreiber als gewöhnliche quotierte TOML-Zeichenkette mit Backslash-n-Escapes ausgegeben. Ein zehnzeiliges Skript wird zu einer einzigen, sehr langen Zeile.

TOML hat eine mehrzeilige Zeichenkettensyntax mit dreifachen Anführungszeichen, die das Skript lesbar halten würde, und der Schreiber nutzt sie nicht. Das ist eine Nacharbeit von Hand: die Werte mit Escape-Umbrüchen suchen und als dreifach quotierten Block neu schreiben. Bei allem, was ein Mensch später noch bearbeitet, lohnt sich das; bei einem Wert, den nur ein Programm liest, nicht.

TOML ist das einzige Format dieser Familie mit echten Datumstypen: versehene und lokale Datumszeiten, lokale Daten und lokale Zeiten gehören alle zur Spezifikation, und ein TOML-Parser gibt sie als Datum zurück statt als Zeichenkette. Das ist der Hauptgrund, aus dem ein Projekt TOML gegenüber JSON wählt.

Aus dieser Umwandlung kommen sie nicht so heraus. YAML 1.2 behandelt ein unquotiertes 2024-01-02 als Zeichenkette, also landet es in der TOML als "2024-01-02" mit Anführungszeichen. Diese Werte danach von Hand zu entquoten dauert Sekunden; sie quotiert zu lassen funktioniert ebenso und bedeutet nur, dass die TOML dort Text statt eines Datums enthält. Dasselbe gilt für Ganzzahlen mit Dezimalpunkt: Ein YAML-Wert 1.0 wird zur TOML-Ganzzahl 1, weil der Parser ihn schon vor dem Schreiber zu einer ganzen Zahl aufgelöst hat.

Ausgerechnet die Konstruktion, um die man sich am meisten sorgt, funktioniert am besten. Eine YAML-Liste, deren Einträge Zuordnungen sind — eine Liste von Autorinnen, eine Liste von Zielen — wird zu einem TOML-Tabellenarray mit dem doppelt geklammerten Kopf einmal pro Eintrag. Genau diese Form erwartet eine pyproject.toml oder Cargo.toml für ihre Autoren und ihre Build-Ziele.

Eine Liste ganz oben in der YAML ist die Ausnahme. TOML-Dokumente sind immer eine Tabelle, also wird ein Dokument, das nur eine Sequenz ist, in eine Tabelle mit einem einzelnen Schlüssel namens items verpackt, darunter die Liste. Steht die YAML als Sequenz auf oberster Ebene, lohnt es sich, den Schlüsselnamen selbst zu wählen und vor der Umwandlung in die Quelle einzutragen, damit er etwas bedeutet.

TOML erlaubt in einem unquotierten Schlüssel nur Buchstaben, Ziffern, Unterstriche und Bindestriche. Alles andere wird quotiert, und der Schreiber übernimmt das automatisch: ein Schlüssel mit einem Punkt kommt als "date.timezone" mit den Anführungszeichen heraus, ein Schlüssel mit Leerzeichen ebenso. Quotierte Schlüssel sind vollkommen gültiges TOML.

Sie sind auch ein Hinweis. Ein quotierter Schlüssel mit Punkt bedeutet meist, dass die YAML Struktur im Schlüsselnamen statt in der Verschachtelung ausgedrückt hat, und in TOML wäre das oft besser als echte Tabelle geschrieben. Ob sich das aufzuteilen lohnt, ist eine Entscheidung über die eigene Konfiguration — die Anführungszeichen in der Ausgabe sind ein guter Ausgangspunkt, um danach zu suchen.

Beide Formate erlauben Kommentare, und keiner überlebt die Umwandlung. Der Parser übergeht sie beim Lesen, der Schreiber hat nichts, was er zurückschreiben könnte. Bei einer Projektkonfiguration ist das ein echter Verlust — die Notiz, warum eine Abhängigkeit auf einer bestimmten Version fixiert ist, oder die auskommentierte Alternative.

Die Umstellung ist erst fertig, wenn diese Notizen zurück sind. YAML und TOML nach der Umwandlung nebeneinanderlegen und die Kommentare dort wieder einfügen, wo sie hingehören, ist bei einer typischen Datei eine Sache von zehn Minuten — und der Unterschied zwischen einer Konfiguration, die jemand pflegen kann, und einer, die zwar funktioniert, an die sich aber niemand mehr herantraut.

Parser und Schreiber laufen beide als JavaScript in diesem Tab. Eine Projektkonfiguration mit internen Tokens oder Pfaden zu einer privaten Paket-Registry verlässt das eigene Gerät nicht, und die kostenlose Grenze liegt bei 100 MB — weit mehr, als eine Konfigurationsdatei je erreicht.

Es gibt kein Konto, keine Warteschlange und nichts, das an einen Server geht, was sich im Netzwerk-Tab des Browsers während der Umwandlung nachprüfen lässt, statt nur behauptet zu werden.