Comment les tables TOML deviennent des objets JSON : [table], [[array]] et clés pointées Les en-têtes de

D'où vient la nidification ? — un fichier TOML d'aspect plat converti en JSON profondément imbriqué, et les en-têtes qui l'ont provoqué

Un fichier TOML peut apparaître presque plat car les crochets portent l'imbrication. `[a.b.c]` ouvre les tables intermédiaires, donc `d = 1` en dessous devient `{"a":{"b":{"c":{"d":1}}}}`. Les accolades JSON rendent visible une hiérarchie que TOML exprime à travers le chemin de la table active.

ToolAcre délègue l'analyse syntaxique à smol-toml, puis normalise les valeurs que JSON ne peut pas transporter. Il ne s’agit pas d’une réécriture basée sur des lignes. Les tableaux, les clés pointées et les tableaux de tableaux deviennent des objets et des tableaux ordinaires avant la sérialisation JSON, c'est pourquoi leur orthographe et leurs commentaires ne sont pas disponibles dans la sortie.

en-têtes [table] - comment un en-tête ouvre un objet imbriqué et comment [a.b.c] crée implicitement des objets intermédiaires

Un en-tête à support unique ouvre un tableau. `[owner]` dirige les affectations suivantes vers `owner` ; `[owner.contact]` crée ou saisit l'objet contact imbriqué. Les objets intermédiaires n'ont pas besoin d'avoir des en-têtes séparés. Leur existence découle des segments de chemin dans l'en-tête.

Les affectations avant tout en-tête restent à la racine. Les tables ultérieures ne les déplacent pas rétroactivement. Lors de l'examen de JSON converti, suivez le chemin complet de la propriété plutôt que la distance physique entre les lignes : la table actuelle de TOML reste active jusqu'à ce qu'un autre en-tête la modifie.

[[tableau de tables]] - pourquoi un en-tête répété à double crochet ajoute des objets à un tableau et l'ordre qu'il préserve

Un en-tête à double crochet ajoute une table à un tableau. Deux sections `[[server]]` deviennent `server: [{...},{...}]` dans l'ordre source. Les champs sous chaque en-tête appartiennent à ce membre du tableau jusqu'à ce qu'un autre en-tête commence, rendant la configuration répétée explicite dans JSON.

L'ordre à l'intérieur du tableau correspond aux données et est préservé. La présentation objet-clé peut être triée ultérieurement lorsque l'option est sélectionnée, mais les membres du tableau ne sont jamais réorganisés. Confondre les deux modifierait la priorité du serveur ou la séquence des plugins plutôt que de simplement formater un document.

Clés en pointillés et tableaux en ligne — a.b = 1 et { x = 1 } comme deux autres façons d'exprimer la même imbrication

Les affectations en pointillés fournissent une autre notation de chemin : `a.b.c = true` donne la même forme d'objet imbriqué que les en-têtes de tableau correspondants. Les tables en ligne telles que `point = { x = 1, y = 2 }` deviennent immédiatement des objets imbriqués. Ces formulaires peuvent décrire des arbres similaires tout en ayant un aspect très différent pour un évaluateur.

JSON enregistre uniquement les clés et valeurs résultantes, et non la notation TOML qui les a créées. La reconversion ne peut donc pas restaurer le choix d'origine parmi les en-têtes, les touches pointillées et les tableaux en ligne. Le rédacteur TOML choisit sa propre sérialisation valide dans l'arborescence.

Types qui sont reportés et types qui ne le sont pas : les entiers, les flottants, les booléens et les chaînes sont directement mappés ; les dates et heures deviennent des chaînes et JSON null n'a pas de source TOML

Les chaînes, les entiers sûrs, les flottants, les booléens, les tableaux et les tables sont mappés directement. Les quatre types temporels de TOML ne deviennent pas leurs chaînes source de type RFC 3339, et un avertissement nomme chaque chemin et type. L'auteur cite plus tard ces chaînes plutôt que de recréer des jetons datetime.

Les entiers 64 bits signés de TOML peuvent dépasser la plage d'entiers sécurisés de JavaScript. smol-toml renvoie des valeurs telles que BigInt si nécessaire ; ToolAcre les convertit en chaînes décimales et avertit plutôt que d'arrondir les chiffres. Cela préserve l'orthographe au prix de la modification du type JSON.

Exemple concret : un pyproject.toml — [project], [project.optional-dependencies] et une liste [[tool.plugins]] convertis en JSON avec chaque niveau tracé

Essayez `name = "demo"`, `[project]`, `dependencies = ["a", "b"]`, `[project.optional]`, `test = ["vitest"]`, puis deux tables `[[tool.plugins]]` avec des noms distincts. JSON place le nom à la racine, imbrique le projet et facultatif, et produit un tableau de plugins sous l'outil.

Ajoutez `released = 1979-05-27` et `huge = 9223372036854775807`. La première devient la chaîne `1979-05-27` ; la seconde devient une chaîne décimale. Les deux avertissements identifient les chemins modifiés, rendant les types non-JSON révisables au lieu d'autoriser la coercition silencieuse de date ou de numéro.

Ce que cela ne couvre pas : la reconversion de JSON en TOML idiomatique avec un regroupement d'en-têtes judicieux, ce qui implique des choix de style qu'aucune règle ne détermine entièrement

JSON-to-TOML est pris en charge pour un objet racine, mais il ne recrée pas les choix ou les commentaires idiomatiques de l'auteur. Les clés de valeur nulle sont omises ; null à l'intérieur d'un tableau devient une chaîne vide pour conserver les positions. Un tableau racine, scalaire ou nul est refusé car un document TOML doit être une table.

Ce comportement corrige l’implication du plan selon laquelle la conversion inverse est hors de portée. Le convertisseur écrit TOML, mais la fidélité du style est en dehors de sa promesse. La distinction est importante : la sérialisation prise en charge n'est pas la même chose que la restauration du fichier source octet par octet ou le choix de la disposition qu'un responsable préférerait.

L'écriture de JSON dans TOML est prise en charge, mais les commentaires, les types datetime et le style d'auteur ne sont pas renvoyés.

Lisez les en-têtes TOML comme chemins et les doubles crochets comme opérations d'ajout. La vue JSON est utile pour tracer l'arborescence résultante, tandis que les avertissements exposent les dates et heures et les entiers larges qui traversent une limite de type. N’appelez pas l’opération sans perte lorsque l’un ou l’autre des avertissements apparaît.

Pour la migration de la configuration, conservez l'original à côté de la sortie convertie. Vérifiez d'abord les valeurs, puis modifiez l'organisation TOML pour les lecteurs et l'outil cible. Les convertisseurs de syntaxe effectuent l'étape mécanique d'analyse et d'écriture ; il ne peut pas décider du regroupement spécifique au projet, des clés acceptées ou si l'application prend en charge ce fichier.

Une comparaison finale devrait séparer trois questions faciles à confondre. Premièrement, les valeurs analysées ont-elles survécu ? Deuxièmement, un type TOML uniquement est-il devenu une chaîne JSON ou un null a-t-il disparu ? Troisièmement, le TOML nouvellement sérialisé est-il organisé d'une manière qu'un responsable peut comprendre ? Les deux premiers peuvent être vérifiés par rapport aux valeurs et aux avertissements ; le troisième a besoin d’un examen humain. Garder ces contrôles séparés empêche une sérialisation techniquement valide d'être qualifiée de migration fidèle lorsque ses types ou sa structure d'auteur ont changé.