Convertir TOML en XML

TOML est aujourd’hui le format par défaut pour les manifests Python, Rust et Go. XML reste le format par défaut pour Maven, Ant, Spring XML, les descripteurs de déploiement Java, la plupart des configurations SOAP, les fichiers de build Android, et un grand nombre d’autres chaînes Java et .NET qui ne sont pas près de changer. Quand un dépôt moderne doit produire un artefact consommé par l’une d’elles, la conversion est le point de friction.

Le cas d’usage honnête est donc presque toujours unidirectionnel : un fichier moderne devient un document lisible par un consommateur ancien, le temps d’une intégration, d’un constructeur CI ou d’une API qui demande du XML. La conversion sert cet aller-simple. L’inverse — un XML riche et commenté vers TOML — est un travail de réécriture qu’aucun convertisseur ne fait bien, parce que ce qu’il faut décider n’est pas dans le fichier.

Une table TOML devient un élément XML du même nom, et un header pointé `database.connection` devient un élément `database` contenant un élément `connection` — l’imbrication du XML correspond exactement à l’imbrication du header, parce que les deux modèles décrivent un arbre de paires. Un array of tables écrit avec un header à double crochets devient une suite d’éléments frères, tous nommés d’après la dernière partie du header et apparaissant dans l’ordre du fichier TOML.

Une table unique sous ce qui pourrait être un array of tables — un fichier qui a un seul auteur, par exemple — produit un seul élément, parce qu’il n’y a rien à répéter. La structure s’aplatit sur le bord de l’array : un fichier avec une dépendance et un autre avec deux dépendances produisent du XML structurellement différent, ce qui est un diff qu’une revue de code veut comprendre. C’est aussi pourquoi un export qui était un array of tables doit le rester : ajouter un élément ne change rien, en retirer un change tout.

L’ordre des enfants et des attributs n’est pas le même en TOML et en XML. TOML a un seul concept de paire clé-valeur ; XML a deux concepts, l’attribut sur l’élément et l’enfant sous l’élément, et le choix entre les deux est la décision qu’aucun convertisseur ne peut prendre correctement. La convention appliquée ici met les scalaires en attributs et les objets en enfants, ce qui donne un XML où l’identifiant, le nom, la version et le booléen sont visibles sans entrer dans l’élément, et où tout ce qui est structuré vit plus bas.

C’est lisible pour un humain, mais ce n’est pas toujours ce que le schéma attend. Un schéma XSD qui définit un champ obligatoire comme élément enfant refusera le document, et la correction est d’éditer l’ordre des choses à la main plutôt que d’insister depuis le convertisseur. Pour une cible sans schéma — un script qui parse au feeling, un consommateur interne — la convention par défaut sert la lecture, et c’est la majorité des cas où cette conversion est demandée.

TOML est un des rares formats de configuration qui a de vrais types temporels dans sa spécification : offset datetimes, local datetimes, local dates et local times. XML n’a pas de type date du tout. Tout devient une chaîne, et la chaîne est exactement celle que TOML a acceptée, avec l’offset s’il y en avait un.

C’est mieux que de normaliser en UTC, parce qu’une date normalisée peut avoir été saisie dans un autre fuseau et un destinataire qui ne sait pas qu’une normalisation a eu lieu lira l’heure comme locale et se trompera d’une heure ou deux. Le défaut honnête est de passer ce que le fichier a écrit. La correction pour un consommateur qui exige du ISO 8601 strict est une édition, et c’est la même édition qu’il faudrait pour n’importe quel format source qui ne le produirait pas déjà.

TOML 1.0 promet des entiers 64 bits signés et le parseur les respecte. XML, comme JSON, n’a que des types numériques approximatifs au-delà de neuf trillions, et un grand identifiant — un snowflake Discord, un horodatage nanoseconde en nanosecondes depuis l’epoch, un grand numéro de série — est silencieusement arrondi si le convertisseur le force dans un nombre XML.

Refuser est la décision correcte, et c’est la même décision que pour JSON : un identifiant silencieusement arrondi devient un bogue qui se manifeste des semaines plus tard dans une jointure qui ne correspond plus à rien. Mettez ces valeurs entre guillemets dans le TOML source pour qu’elles deviennent des chaînes, et la conversion se fera sans accroc. C’est une édition d’une minute sur le fichier d’origine, et c’est celle qui distingue une migration qui marche d’une qui marchera presque.

Une valeur TOML multi-lignes écrite entre triple guillemets produit un seul attribut XML ou un seul élément texte avec des sauts de ligne échappés, parce que les attributs XML ne peuvent pas porter de saut de ligne et que les éléments texte les portent, mais rarement de la manière dont l’auteur les voulait. Le XML ne connaît pas le triple-guillemet, et l’auteur ici non plus ne l’invente pas.

Pour une cible où la lisibilité compte — un fichier Spring documenté, un manifeste à éditer à la main — passer une fois par sed ou par votre éditeur pour réécrire les valeurs longues en éléments CDATA, ou pour les sortir de l’attribut et les mettre comme enfants, prend quelques minutes et fait une vraie différence. C’est aussi la différence entre un fichier qui invite à être modifié et un fichier qu’aucune équipe ne voudra toucher.

TOML supporte les commentaires et l’outillage Python et Rust les utilisent abondamment : la raison d’une épingle, le numéro de ticket à côté d’un contournement, le bloc qui explique à quel environnement s’applique un réglage. XML supporte aussi les commentaires, mais aucun convertisseur automatique ne peut les faire traverser, parce que le commentaire est un élément de la grammaire et non un attribut du contenu.

La migration honnête recopie les commentaires à la main. Pour un petit fichier c’est cinq minutes, pour un grand manifeste c’est une heure, et c’est du temps bien employé : un document XML sans commentaires est un document que la personne qui le lira dans deux ans ne pourra pas maintenir. Si la cible n’accepte pas les commentaires et qu’aucun consommateur ne les lira, ce coût est nul, et l’absence est pardonnée.

Le document commence par `<?xml version="1.0" encoding="UTF-8"?>`, et l’élément racine prend le nom de la première table de premier niveau du TOML — `project`, `package`, `tool` ou ce que la source déclare. C’est ce qu’un parseur XML standard attend, et c’est ce que la majorité des chaînes d’outillage Java et .NET consomment sans protester.

Le cas particulier est un consommateur qui ne veut pas du prologue, et il en existe : certains pipelines CI remplacent le prologue à leur propre format, certaines configurations Spring ne le tolèrent pas dans un test unitaire, et un fichier qui doit être inliné dans un autre XML ne peut pas avoir deux prologues. Pour ces cas, ouvrir le fichier dans un éditeur et effacer la première ligne est une seconde de travail, et le convertisseur n’a pas de raison de s’en mêler.

XML peut être validé par un schéma XSD ou relax NG avant qu’une application ne démarre, et c’est une partie non négligeable de la valeur d’un fichier de configuration XML : la machine refuse ce qu’un humain oublierait. TOML n’a pas de langage de schéma dans sa spécification, et un TOML généré ne porte pas avec lui la description de ce qui est attendu.

Le convertisseur ne produit pas de schéma. La validation doit être faite par la cible, et pour un document qui doit passer un XSD exigeant, c’est une étape à part. Pour une cible sans XSD — la majorité des cas, et c’est la majorité des cas pour lesquels on convertit vers XML plutôt qu’on ne génère du JSON — le document arrive tel quel et le destinataire fait avec, ce qui est exactement la promesse implicite de cette conversion.

La conversion est un parcours d’arbre en mémoire : TOML lu, arbre intermédiaire construit, XML écrit. Aucun octet ne quitte le navigateur, aucun service n’est appelé, et le fichier produit arrive par le même chemin de téléchargement que tout autre fichier de votre machine.

Pour un manifest de configuration c’est en général sans importance pratique, mais pas toujours. Un pyproject.toml qui liste des dépendances internes nomme des dépôts privés ; un Cargo.toml déclare des crates venues d’un registre d’entreprise ; un fichier de configuration de build peut contenir des jetons de signature ou des identifiants de pipeline. Aucune de ces choses ne devrait traverser un service web tiers sur son chemin vers un consommateur ancien, et c’est exactement la garantie qu’une conversion locale vous donne.