YAML in INI umwandeln

In vielen Fertigungshallen und Betrieben des Mittelstands läuft neben der modernen Infrastruktur noch eine Maschinensteuerung, eine Kassensoftware oder ein Auftragsverwaltungsprogramm, das seit fünfzehn Jahren INI-Dateien liest und dessen Hersteller es nicht mehr gibt. Die Einstellungen dafür werden inzwischen zentral in YAML gepflegt, weil das jedes andere Werkzeug im Haus auch tut — nur eben nicht dieses eine.

Diese Seite löst genau diesen Bruch. Sie liest das YAML und schreibt eine INI-Datei, die das alte Programm versteht, indem sie die Baumstruktur auf zwei Ebenen zusammenfaltet: Sektion und Schlüssel. Was dabei verloren geht, steht weiter unten, und es ist mehr, als man beim ersten Blick vermutet.

INI kennt genau eine Gruppierungsebene: eine Sektion in eckigen Klammern und die Schlüssel darin. YAML kennt so viele Ebenen, wie jemand einrücken mag. Die Umwandlung löst das, indem sie für jeden Wert einen Pfad aus Punkten baut und diesen Pfad einmal aufteilt — der Teil vor dem ersten Punkt wird zur Sektion, der Rest zum Schlüssel.

Eine YAML-Zuordnung namens datenbank, darin pool, darin timeout, ergibt also eine Sektion datenbank mit einem Schlüssel pool.timeout. Jeder Wert bleibt erhalten, nur die Form geht verloren — ein Programm auf der anderen Seite sieht flache Schlüssel mit Punkten darin und kann nicht mehr unterscheiden, welcher Punkt eine Schachtelung war und welcher zum Namen gehörte.

Für eine YAML-Sequenz gibt es in INI kein Gegenstück, also wird jeder Eintrag zu einem nach seiner Position benannten Schlüssel. Ein Build-Skript aus drei Befehlen kommt als script.0, script.1 und script.2 innerhalb der zugehörigen Sektion heraus, in der geschriebenen Reihenfolge.

Die Reihenfolge stimmt, aber die Konvention dahinter ist unsere, kein Standard. Manche INI-Parser deuten durchnummerierte Schlüssel als Liste, die meisten tun es nicht, und einige erwarten stattdessen einen mehrfach wiederholten Schlüsselnamen. Vor dem Verlassen auf das Ergebnis lohnt sich ein Blick in die Dokumentation der Zielsoftware — eine geordnete Liste, die als drei unzusammenhängende Einstellungen ankommt, wurde korrekt umgewandelt und falsch verstanden.

Ein YAML-Blockskalar — ein Pipe-Zeichen mit eingerücktem Text darunter, wie ihn jede CI-Pipeline für ein Shell-Skript nutzt — wird zu einer einzelnen Zeichenkette mit Zeilenumbrüchen darin. Der Schreiber setzt einen solchen Wert in Anführungszeichen und schreibt jeden Umbruch als Backslash und n, sodass das Skript ein einziger INI-Eintrag bleibt statt in einzelne, unzusammenhängende Zeilen zu zerfallen.

Was das nicht löst, ist die Gegenseite: INI-Dialekte behandeln Backslash-Escapes unterschiedlich, und ein Parser, der den Backslash als gewöhnliches Zeichen liest, gibt genau diese zwei Zeichen statt eines Zeilenumbruchs zurück. Wenn das Programm dahinter wichtiger ist als der originalgetreue Rücktransport, gehört ein langes Skript in eine eigene Datei, auf die die INI nur verweist.

Ein YAML-Schlüssel ohne Wert dahinter wird zu null geparst und als Schlüssel, Gleichheitszeichen und nichts geschrieben. INI kann einen fehlenden Wert nicht von einer leeren Zeichenkette unterscheiden, also kommen beide auf der anderen Seite als leerer String an. Wo der Unterschied zählt, muss er im Programm selbst über einen Platzhalterwert abgebildet werden.

Wahrheitswerte werden als true und false geschrieben, also genau so, wie YAML sie gelesen hat. Das ist nicht das, was jeder INI-Leser erwartet: Windows-Konfigurationen und php.ini kennen On und Off, und ein Parser, der danach sucht, behandelt true als unbekannte Zeichenkette. Anführungszeichen setzt der Schreiber nur dort, wo ein Wert sonst falsch zurückgelesen würde — bei einem Zeilenumbruch, einem Leerzeichen am Rand oder bereits vorhandenen Anführungszeichen.

Eine Konfiguration, die zwei Ebenen tief ist, nur einfache Werte enthält und keine mehrzeiligen Felder hat, wird ohne Nacharbeit umgewandelt. Ein großer Teil der Anwendungskonfigurationen sieht genau so aus, und genau dafür ist dieses Seitenpaar gedacht — ein Satz Feature-Flags oder ein Umgebungsblock aus einer docker-compose-Datei verliert dabei nichts, was jemand vermissen würde.

Eine Datei mit Listen von Zuordnungen dagegen nicht. Eine YAML-Liste von Serverdefinitionen, jede mit host und port, wird zu servers.0.host, servers.0.port, servers.1.host und so weiter in einer einzigen Sektion — technisch korrekt und praktisch unlesbar. Wer so eine Struktur hat, sollte INI als Ziel aufgeben und die Konfiguration von Hand neu schreiben.

Ein einzelner Wert auf der obersten YAML-Ebene — eine Versionsnummer, ein Name, ein einzelnes Flag — hat keine übergeordnete Struktur, aus der eine Sektion entstehen könnte. Solche Werte schreibt der Konverter zuerst, noch vor jeder eckigen Klammer, was der übliche INI-Weg für einen globalen Block ist und von den meisten Parsern verstanden wird.

Danach folgen die Sektionen in der Reihenfolge, in der ihre Schlüssel im YAML auftauchten. Das ist beim Gegenlesen von Hand hilfreich, weil die Ausgabe ungefähr in derselben Reihenfolge steht wie die Quelle und ein Diff zwischen zwei Umwandlungen derselben Datei nachvollziehbar bleibt.

Kommentare werden verworfen. Beide Formate erlauben sie, der Parser übergeht sie beim Lesen, und der Schreiber hat nichts, was er zurückschreiben könnte. Die Erklärung über dem Timeout, die die YAML-Datei eigentlich lesenswert gemacht hat, steht in der INI nicht mehr.

Eine Datei mit --- Trennzeichen schlägt vollständig fehl statt teilweise umzuwandeln, und das mit Absicht: Ein YAML-Strom kann mehrere Dokumente enthalten, eine INI-Datei beschreibt genau eine Konfiguration, und stillschweigend das erste Dokument zu nehmen würde eine Datei erzeugen, der der größte Teil ihrer selbst fehlt. Die Datei muss vorher geteilt werden.

Die Umwandlung zahlt sich aus, wenn die YAML-Datei groß, flach und unspektakulär ist. Sie lohnt sich nicht bei einer kleinen Quelle — zwanzig Einstellungen sind schneller neu getippt als konvertiert und danach repariert, und das Neutippen zwingt dazu, jeden Wert einmal bewusst zu lesen, was bei einer Konfiguration, der ein altes Programm bald vertrauen soll, ein Gewinn ist.

Sie ist auch das falsche Werkzeug, wenn die Zielsoftware einen bestimmten INI-Dialekt erwartet. Programme, die quotierte Werte, On und Off als Wahrheitswerte, kommagetrennte Listen oder wiederholte Schlüssel verlangen, wollen Konventionen, die dieser Schreiber nicht erzeugt. Die Umwandlung holt die Werte aus dem Baum heraus; die Feinanpassung an den tatsächlichen Parser bleibt danach übrig.

Parser und Schreiber laufen beide als JavaScript in diesem Tab. Eine Konfiguration mit internen Hostnamen, Lizenzschlüsseln oder Pfaden zu einem Fertigungsnetz verlässt das eigene Gerät nicht, was bei einer Datei, die für eine Maschine oder eine Kasse bestimmt ist, mehr als eine Formalität ist.

Es gibt kein Konto, keine Warteschlange und keine Obergrenze, die wir setzen — Dateien bis 100 MB werden angenommen, weit mehr, als eine Konfigurationsdatei je erreicht. Das lässt sich im Netzwerk-Tab des Browsers nachprüfen statt nur behauptet zu werden.