Pourquoi TOML existe : les objectifs de conception derrière Cargo.toml et pyproject.toml

Trois formats de configuration dans un seul référentiel — JSON pour l'éditeur, YAML pour CI, TOML pour la build et la question de savoir pourquoi le troisième existe

Un référentiel peut utiliser JSON, YAML et TOML pour différentes surfaces de configuration. ToolAcre ne peut pas expliquer le choix de chaque projet, mais la conversion rend les différences structurelles concrètes : TOML commence comme une table racine, utilise des en-têtes et des chemins en pointillés pour l'imbrication et transporte des valeurs temporelles non disponibles dans JSON.

Chargez l'exemple plutôt que de discuter de l'apparence. Les tableaux imbriqués deviennent des objets, les tableaux entre crochets deviennent des tableaux et les commentaires disparaissent lorsque les valeurs entrent JSON. Ces limites observées sont plus exploitables qu’une affirmation générique selon laquelle une syntaxe est intrinsèquement meilleure.

Les objectifs de conception : une sémantique minimale et évidente, facile à lire et un format qui correspond sans ambiguïté à une table de hachage

L'analyseur fourni expose une sémantique de table évidente : les en-têtes sont des chemins, les affectations appartiennent à la table active et les jetons scalaires ont défini des types TOML. Les chaînes ne sont pas typées simplement parce que leur contenu ressemble à des dates ; la syntaxe temporelle réelle produit des objets de date que ToolAcre normalise délibérément.

Le référentiel ne fournit pas de sources sur les créateurs du format, les dates ou la philosophie déclarée, donc cet article évite de présenter l'histoire mémorisée comme un fait. Il rapporte le comportement testé dans smol-toml et la propre couche de normalisation du convertisseur.

Propriétés de conception observables dans l'analyseur expédié, sans allégations d'origine sans source

TOML n'a pas de valeur nulle et la racine de son document ne peut pas être un tableau ou un scalaire. Il ne fournit pas d’ancres ou d’alias de style YAML dans ce mappage. Les commentaires existent dans TOML créé mais ne sont pas conservés par l'analyseur de valeur et ne peuvent donc pas survivre à la conversion via JSON ou YAML.

Les valeurs nues non citées suivent la grammaire de TOML plutôt que la sélection de schéma de YAML. L'analyseur accepte une valeur saisie ou signale un TOML non valide avec des informations de position. ToolAcre n'ajoute pas de mode chaîne implicite pour les affectations mal formées.

Ce que le modèle de valeur pris en charge exclut ou gère différemment

Le modèle comprend des chaînes, des entiers signés, des flottants, des booléens, quatre types temporels, des tableaux et des tables. Les tableaux de tables expriment des enregistrements d'objets répétés. Les grands entiers signés au-delà de 2^53 deviennent des chaînes décimales lors de la conversion afin que JavaScript ne les arrondisse pas silencieusement.

Les valeurs temporelles deviennent le texte orienté source pour le décalage date-heure, date-heure locale, date locale ou heure locale. L'avertissement conserve le genre en prose, mais JSON ne reçoit qu'une chaîne. La reconversion le cite donc et perd le type natif TOML.

Adoption — Cargo des premiers jours de Rust, PEP 518 choisissant pyproject.toml et la spécification 1.0.0 dans 2021

L'adoption de Cargo et de pyproject sont des revendications historiques et écosystémiques nécessitant des sources non présentes dans le référentiel du convertisseur. Ils sont intentionnellement omis ici. Un chemin ou un nom de fichier ne constitue pas une preuve d'une chronologie, d'une publication de spécifications ou d'une décision relative aux normes.

La question opérationnelle est de savoir si l'outil cible lit TOML et quelles tables il attend. Vérifiez la documentation actuelle de cet outil. Les convertisseurs de syntaxe connaissent la syntaxe et le mappage de valeurs, pas les contrats de configuration du gestionnaire de packages.

L'historique d'adoption de l'écosystème est omis sans sources de référentiel

L'imbrication profonde peut être plus difficile à analyser car le contexte de la table persiste sur plusieurs lignes, tandis que de grands tableaux de tables répartissent une liste logique sur des en-têtes répétés. JSON rend la hiérarchie complète explicite mais ajoute des accolades et des guillemets. Aucune des deux représentations ne supprime la complexité de la configuration sous-jacente.

L'analyseur limite l'imbrication à 100 et la longueur de la source à deux millions de caractères. Il s'agit de limites de refus, et non de déclarations sur la taille de configuration idéale ou de limites universelles TOML.

Ce que cela ne couvre pas : le choix de l'analyseur TOML dans chaque langage et la nature en lecture seule de certaines implémentations de bibliothèques standard.

Le choix de l'analyseur dans chaque langage sort du cadre, tout comme les capacités d'écriture des bibliothèques standard. ToolAcre utilise smol-toml de manière dynamique et encapsule ses erreurs. Une autre implémentation peut formater différemment une sortie valide ou exposer une autre API tout en représentant les mêmes données.

Utilisez des appareils multi-outils pour les valeurs temporelles, les grands entiers, les tableaux et les clés pointées lorsque l'interopérabilité est importante. Un fichier accepté ici n'est pas automatiquement accepté par tous les consommateurs TOML.

À retenir : TOML est convaincu qu'il s'agit d'un format de configuration - et comment le panneau des convertisseurs de syntaxe vous permet de voir n'importe quel fichier JSON ou YAML sous cette forme

TOML a des opinions de manière observable : racine de table, valeurs typées explicites, types temporels natifs et pas de valeur nulle. La conversion expose ces choix et leurs incompatibilités avec les cibles en forme de JSON sans avoir besoin d'un mythe d'origine.

Utilisez le panneau pour inspecter un arbre et identifier les avertissements. Revenez ensuite au schéma de destination et créez la disposition du tableau que les humains conserveront. Le convertisseur fournit des preuves sur les valeurs, et non un verdict sur les préférences de format.

La même discipline s'applique lorsque TOML n'est qu'une vue intermédiaire. Préservez la source, comparez les valeurs normalisées et notez chaque conversion temporelle ou entière avant de juger de la lisibilité. Une disposition de tableau compacte peut toujours masquer un type modifié, tandis qu'un tableau détaillé de tableaux peut être sémantiquement exact. Le choix du format doit suivre le contrat de configuration et le flux de travail de maintenance, et non la netteté visuelle d'un échantillon généré.