Convertir XML en TOML

Chaque élément avec des enfants devient une table, écrite comme un en-tête entre crochets nommant le chemin complet en points. Un élément à trois niveaux de profondeur produit un en-tête contenant trois noms plutôt que trois blocs imbriqués, parce que TOML exprime la profondeur dans l’en-tête et non dans l’indentation.

À l’intérieur de chaque table, les valeurs simples viennent en premier et les tables imbriquées suivent, ce qui est le seul ordre que TOML autorise — tout ce qui est sous un en-tête lui appartient jusqu’à ce que l’en-tête suivant apparaisse. Cela veut dire que la sortie ne se lit pas dans le même ordre que le XML, et sur une config avec beaucoup de petits éléments le réarrangement est substantiel. C’est une réorganisation, pas un changement : aucune valeur ne va dans un autre chemin.

C’est la partie de la conversion qui n’a pas besoin de réparation. Deux éléments frères ou plus avec le même tag deviennent un tableau TOML de tables, avec l’en-tête à double crochets écrit une fois par item dans l’ordre du document. Une liste de dépendances, une liste de serveurs, une liste de règles — tout cela arrive sous la forme qu’une config TOML aurait utilisée de toute façon.

La réserve habituelle sur le XML s’applique toujours en dessous. Une occurrence unique d’un élément répétable n’est pas un tableau, donc cela devient une table simple avec un en-tête à crochet unique à la place. Convertissez un fichier avec une entrée et le même fichier avec deux, et les deux sorties diffèrent structurellement. Si la config est générée ou archivée dans un dépôt, c’est un diff que vous voulez comprendre avant qu’il apparaisse.

Les clés nues de TOML n’acceptent que des lettres, des chiffres, des soulignés et des traits d’union, et rien d’autre. Les attributs arrivent de l’analyseur sous forme de clés commençant par @, le texte propre d’un élément sous une clé nommée #text, et une déclaration d’espace de noms sous une forme comme @xmlns:soap. Tous sont entre guillemets dans la sortie, ce qui est du TOML valide et a l’air exactement aussi inhabituel que cela sonne.

C’est aussi une liste de choses à faire. Une clé entre guillemets est le convertisseur qui vous dit que ce nom vient de la machinerie XML plutôt que de votre configuration, et presque chacun d’eux devrait être renommé : un attribut @value devient une clé de valeur simple, une clé @xmlns est supprimée, une clé #text prend le nom de ce que l’élément contenait réellement. Faites cette passe une fois, immédiatement, pendant que vous vous souvenez encore de ce que le XML signifiait.

Un document TOML est lui-même une table, et un document XML a exactement un élément racine, donc la config entière apparaît un niveau plus bas que ce que vous voulez — sous un en-tête unique nommé d’après la racine. Un fichier enraciné dans configuration produit une table configuration qui contient tout.

Promouvoir le contenu est une édition mécanique : supprimez le premier en-tête et retirez ce segment de chaque autre en-tête du fichier. Cela vaut la peine d’être fait plutôt que d’être subi, parce que chaque chemin dans la config gagne un niveau en moins et un fichier TOML se lit par ses en-têtes. Le faire à la main force aussi une passe sur le fichier entier, ce qui sur une migration est du temps bien employé.

TOML n’a pas de valeur nulle, et convertir depuis des formats qui en ont — YAML notamment — signifie que des clés disparaissent en silence quand leur valeur est vide. Cela ne peut pas arriver ici, parce que le XML n’a pas de null non plus. Un élément vide et un élément auto-fermant veulent dire la même chose et tous les deux deviennent une chaîne vide, écrite comme deux guillemets.

Donc la garantie pour ce sens est plus forte que pour ses voisins : chaque élément qui avait une valeur dans le XML a une clé dans le TOML. Les chaînes vides sont malgré tout faciles à manquer dans un long fichier, donc si la migration est aussi une occasion de retirer des paramètres que personne n’utilise, chercher les paires vides dans la sortie est la manière la plus rapide de les trouver.

TOML met les dates et les heures dans sa spécification de base — datetimes décalés, datetimes locaux, dates locales et heures locales — et un analyseur les rend comme des dates plutôt que comme des chaînes. YAML a aussi une balise d’horodatage, mais elle appartient à la bibliothèque de types 1.1 plutôt qu’au schéma de base 1.2, donc ce que rend un chargeur dépend du chargeur. Les quatre types de TOML, eux, ne dépendent de rien.

Une valeur XML est du texte, donc une date dans la source arrive comme une chaîne entre guillemets et le reste. Enlever les guillemets de ces valeurs dans la sortie, c’est ce qui les transforme en vraies dates TOML, et cela prend une minute. Le cas inverse mérite aussi d’être surveillé : une valeur écrite 1.0 dans le XML est analysée comme un nombre et écrite comme l’entier TOML 1, donc une version est devenue un entier et a perdu sa forme. La remettre entre guillemets est la correction.

Un élément contenant plusieurs lignes — une description, un bloc de licence, un script incorporé — devient une seule chaîne TOML basique avec des échappements antislash-n là où étaient les sauts de ligne. C’est correct et c’est illisible, et cela défait le but de passer à un format que les gens éditent à la main.

TOML a une syntaxe de chaîne multiligne à triple guillemet qui contient une telle valeur de manière lisible, et l’écrivain ne l’utilise pas. Trouvez les valeurs qui contiennent des échappements et réécrivez chacune en bloc à triple guillemet. Sur la plupart des configs il y en a une ou deux ; sur une config pleine de texte incorporé, c’est un signal que le contenu veut vivre dans son propre fichier plutôt qu’à l’intérieur d’un fichier de paramètres.

Les commentaires sont supprimés, alors que les deux formats les supportent, donc les explications dans l’ancien fichier n’apparaissent pas dans le nouveau. Les espaces de noms cessent de signifier quoi que ce soit à l’instant où les préfixes deviennent des caractères dans une clé. Et le schéma disparaît : le XML peut être validé contre un XSD avant qu’une application ne démarre, et TOML n’a pas de langage de schéma dans sa spécification.

C’est ce dernier point qui est l’échange à faire consciemment. TOML est plus facile à lire, plus facile à écrire à la main et sans ambiguïté sur les types, et il abandonne la capacité de rejeter mécaniquement une config mal formée. Si le XML était réellement validé dans votre build, vous retirez une vérification, et la remplacer — par une vérification au démarrage dans l’application — fait partie de la migration plutôt que comme un extra optionnel.

Ce que l’outil vous donne, c’est chaque valeur du XML, dans la bonne table, avec le bon nom dans la majorité des cas et un nom visiblement faux entre guillemets dans le reste. C’est un bon point de départ et pas un fichier de config fini.

Le travail après est petit et non optionnel : supprimez la table racine, renommez les clés @ et #text, enlevez les guillemets des dates, réécrivez les valeurs multilignes, et recopiez les commentaires depuis l’original. Une heure sur un gros fichier. Sauter cette étape produit une config TOML qui marche et en laquelle personne qui la lira plus tard ne croira qu’elle a été écrite exprès.