Wie TOML-Tabellen zu JSON-Objekten werden: [Tabelle], [[Array]] und punktierte Schlüssel Die Header von

Woher kam das Nest? – eine flach aussehende TOML-Datei, die in eine tief verschachtelte JSON konvertiert wurde, und die Header, die sie verursacht haben

Eine TOML-Datei kann nahezu flach erscheinen, da die Verschachtelung durch Klammern erfolgt. `[a.b.c]` öffnet Zwischentabellen, sodass `d = 1` darunter zu `{"a":{"b":{"c":{"d":1}}}}` wird. Die geschweiften Klammern JSON machen eine Hierarchie sichtbar, die TOML durch den aktiven Tabellenpfad ausdrückt.

ToolAcre delegiert die Syntaxanalyse an smol-toml und normalisiert dann Werte, die JSON nicht übertragen kann. Dies ist kein zeilenbasiertes Umschreiben. Tabellen, Punktschlüssel und Arrays von Tabellen werden vor der JSON-Serialisierung zu gewöhnlichen Objekten und Arrays, weshalb ihre Schreibweise und Kommentare in der Ausgabe nicht verfügbar sind.

[table]-Header – wie ein Header ein verschachteltes Objekt öffnet und wie [a.b.c] implizit Zwischenobjekte erstellt

Eine Kopfzeile mit einer Klammer öffnet eine Tabelle. `[owner]` leitet folgende Zuweisungen an `owner`; `[owner.contact]` erstellt das verschachtelte Kontaktobjekt oder gibt es ein. Zwischenobjekte müssen keine separaten Header haben. Ihre Existenz ergibt sich aus den Pfadsegmenten im Header.

Zuweisungen vor jedem Header bleiben im Stammverzeichnis. Spätere Tabellen verschieben sie nicht rückwirkend. Befolgen Sie beim Überprüfen der konvertierten JSON den vollständigen Eigenschaftspfad und nicht den physischen Abstand zwischen den Zeilen: Die aktuelle Tabelle von TOML bleibt aktiv, bis sie durch einen anderen Header geändert wird.

[[Array von Tabellen]] – warum ein wiederholter Header in doppelten Klammern Objekte an ein Array anhängt und welche Reihenfolge er beibehält

Ein Header in doppelten Klammern hängt eine Tabelle an ein Array an. Zwei `[[server]]`-Abschnitte werden in der Quellreihenfolge zu `server: [{...},{...}]`. Felder unter jedem Header gehören zu diesem Array-Mitglied, bis ein anderer Header beginnt, wodurch die wiederholte Konfiguration in JSON explizit wird.

Die Reihenfolge innerhalb des Arrays liegt bei den Daten und bleibt erhalten. Die Objektschlüsselpräsentation kann später sortiert werden, wenn die Option ausgewählt ist, Array-Mitglieder werden jedoch nie neu angeordnet. Eine Verwechslung der beiden würde die Serverpriorität oder die Plugin-Reihenfolge ändern, anstatt lediglich ein Dokument zu formatieren.

Gepunktete Schlüssel und Inline-Tabellen – a.b = 1 und { x = 1 } als zwei weitere Möglichkeiten, dieselbe Verschachtelung auszudrücken

Gepunktete Zuweisungen bieten eine andere Pfadnotation: `a.b.c = true` ergibt die gleiche verschachtelte Objektform wie entsprechende Tabellenköpfe. Inline-Tabellen wie `point = { x = 1, y = 2 }` werden sofort zu verschachtelten Objekten. Diese Formulare können ähnliche Bäume beschreiben, sehen für einen Rezensenten jedoch sehr unterschiedlich aus.

JSON zeichnet nur die resultierenden Schlüssel und Werte auf, nicht die TOML-Notation, die sie erstellt hat. Eine Rückkonvertierung kann daher die ursprüngliche Auswahl zwischen Überschriften, Punktschlüsseln und Inline-Tabellen nicht wiederherstellen. Der TOML-Writer wählt seine eigene gültige Serialisierung aus dem Baum.

Typen, die übertragen werden, und Typen, die dies nicht tun – Ganzzahlen, Gleitkommazahlen, boolesche Werte und Zeichenfolgen werden direkt zugeordnet; Datums- und Uhrzeitangaben werden zu Zeichenfolgen und JSON null hat keine TOML-Quelle

Zeichenfolgen, sichere Ganzzahlen, Gleitkommazahlen, boolesche Werte, Arrays und Tabellen werden direkt zugeordnet. Die vier zeitlichen Typen von TOML tun dies nicht: Offset-Datum/Uhrzeit, lokales Datum/Uhrzeit, lokales Datum und lokale Uhrzeit werden zu ihren RFC 3339-ähnlichen Quellzeichenfolgen, und eine Warnung benennt jeden Pfad und jede Art. Der Autor zitiert später diese Zeichenfolgen, anstatt Datum/Uhrzeit-Token neu zu erstellen.

Die vorzeichenbehafteten 64-Bit-Ganzzahlen von TOML können den sicheren Ganzzahlbereich von JavaScript überschreiten. smol-toml gibt bei Bedarf Werte wie BigInt zurück; ToolAcre wandelt sie in Dezimalzeichenfolgen um und gibt eine Warnung aus, anstatt die Ziffern zu runden. Dadurch bleibt die Rechtschreibung erhalten, allerdings muss der Typ JSON geändert werden.

Bearbeitetes Beispiel: ein pyproject.toml – [project], [project.optional-dependencies] und eine [[tool.plugins]]-Liste, konvertiert in JSON, wobei jede Ebene verfolgt wird

Versuchen Sie es mit `name = "demo"`, `[project]`, `dependencies = ["a", "b"]`, `[project.optional]`, `test = ["vitest"]` und dann zwei `[[tool.plugins]]`-Tabellen mit unterschiedlichen Namen. JSON platziert den Namen im Stammverzeichnis, verschachtelt Projekt und optional und erstellt ein Plugins-Array unter dem Tool.

Fügen Sie `released = 1979-05-27` und `huge = 9223372036854775807` hinzu. Der erste wird zur Zeichenfolge `1979-05-27`; die zweite wird zu einer Dezimalzeichenfolge. Beide Warnungen identifizieren die geänderten Pfade und machen die Nicht-JSON-Typen überprüfbar, anstatt eine stille Datums- oder Zahlenerzwingung zu ermöglichen.

Was dies nicht abdeckt – das Zurückkonvertieren von JSON in das idiomatische TOML mit sinnvoller Header-Gruppierung, was Stilauswahlen beinhaltet, die keine Regel vollständig bestimmt

JSON-to-TOML wird für ein Stammobjekt unterstützt, es werden jedoch keine idiomatischen Autorenauswahlen oder Kommentare neu erstellt. Nullwertige Schlüssel werden weggelassen; null innerhalb eines Arrays wird zu einer leeren Zeichenfolge, um Positionen beizubehalten. Ein Root-Array, ein Skalar oder Null wird abgelehnt, da ein TOML-Dokument eine Tabelle sein muss.

Dieses Verhalten korrigiert die Schlussfolgerung der Gliederung, dass die umgekehrte Konvertierung außerhalb des Geltungsbereichs liegt. Der Konverter schreibt TOML, doch die Stiltreue ist außerhalb seines Versprechens. Der Unterschied ist wichtig: Die unterstützte Serialisierung ist nicht dasselbe wie die Wiederherstellung der Quelldatei Byte für Byte oder die Auswahl des Layouts, das ein Betreuer bevorzugen würde.

Das Zurückschreiben von JSON in TOML wird unterstützt, Kommentare, Datum/Uhrzeit-Typen und Autorenstil werden jedoch nicht zurückgegeben

Lesen Sie TOML-Header als Pfade und doppelte Klammern als Anhängevorgänge. Die Ansicht JSON ist für die Nachverfolgung des resultierenden Baums hilfreich, während Warnungen Datumsangaben und breite Ganzzahlen offenlegen, die eine Typgrenze überschreiten. Rufen Sie den Vorgang nicht als verlustfrei auf, wenn eine der Warnungen angezeigt wird.

Bewahren Sie für die Konfigurationsmigration das Original neben der konvertierten Ausgabe auf. Überprüfen Sie zunächst die Werte und bearbeiten Sie dann die Organisation TOML für Leser und das Zieltool. Syntaxkonverter führen den mechanischen Parse-and-Write-Schritt durch; Es kann nicht über projektspezifische Gruppierungen, akzeptierte Schlüssel oder ob die Anwendung diese Datei unterstützt, entscheiden.

Ein abschließender Vergleich sollte drei Fragen trennen, die leicht miteinander verwischt werden können. Erstens: Haben die analysierten Werte überlebt? Zweitens: Wurde aus einem Nur-TOML-Typ ein JSON-String oder ist eine Null verschwunden? Drittens: Ist das neu serialisierte TOML so organisiert, dass ein Betreuer es verstehen kann? Die ersten beiden können anhand von Werten und Warnungen überprüft werden. der dritte bedarf einer menschlichen Überprüfung. Durch die getrennte Durchführung dieser Prüfungen wird verhindert, dass eine technisch gültige Serialisierung als originalgetreue Migration bezeichnet wird, wenn sich ihr Typ oder ihre Autorenstruktur ändert.