Convertir TOML en NDJSON

Un document TOML est une table. Il n’existe pas de fichier TOML qui soit une liste au niveau supérieur — la spécification ne le permet pas — donc la limite d’enregistrement dont le JSON délimité par retour à la ligne a besoin n’apparaît jamais à l’intérieur d’un seul fichier. Le document entier devient une ligne.

Pour la plupart des sources ce serait une limitation. Ici, c’est la forme du problème : personne ne veut un pyproject.toml fragmenté, et toute personne qui en convertit un en NDJSON construit une collection où chaque fichier est un enregistrement. L’unité du format et l’unité de la question se trouvent d’accord, ce qui n’est pas vrai de toutes les paires sur ce site.

Le flux de travail est : convertir chaque fichier, ajouter la ligne à une sortie qui grossit. Parce que chaque ligne est une valeur JSON complète, autonome, et que rien n’encadre le fichier — pas de tableau englobant, pas de virgules entre enregistrements — la concaténation est toute l’étape de fusion. Deux lignes de deux conversions sont un fichier NDJSON valide à deux enregistrements.

Ce que cela vous apporte est un jeu de données sur lequel poser des questions. Quels crates épinglent une version spécifique de dépendance, quels paquets ne déclarent pas de licence, quels dépôts ciblent encore une vieille édition — tout cela est une requête sur la collection plutôt qu’un script qui parcourt des répertoires et analyse des fichiers. Construire cet inventaire est bien plus utile que lire une seule config, et c’est la raison pour laquelle cette paire existe.

Un enregistrement sans source est proche de l’inutile dans un inventaire. Le convertisseur lit le contenu d’un fichier et rien d’autre — il ne connaît ni le chemin, ni le dépôt, ni le commit — donc la ligne qu’il produit n’a aucun champ disant d’où elle vient.

Ajoutez-le vous-même, à l’un de deux moments. Une passe jq pendant la concaténation peut injecter une clé de chemin par ligne, ce qui garde les fichiers TOML intacts et est la bonne approche pour un parc que vous ne possédez pas. Sinon, une clé à l’intérieur de chaque fichier TOML le nomme, ce qui survit à toute conversion future mais veut dire éditer des fichiers qui appartiennent à d’autres. La première passe à l’échelle ; la seconde est plus honnête quand le fichier devrait vraiment s’identifier lui-même.

JSON compact : pas d’indentation, pas d’espace après les deux-points, les clés dans l’ordre où le TOML les a déclarées, finissant par un retour à la ligne. Les tables deviennent des objets imbriqués et les arrays of tables deviennent des tableaux d’objets, donc une liste d’auteurs ou un ensemble de cibles de build arrive dans la forme qu’un moteur de requête attend.

La ligne est aussi longue que la config l’est. Un pyproject.toml fait quelques kilo-octets et une config lock-adjacent générée peut être bien plus gros, et un lecteur qui traite une ligne à la fois doit garder la ligne entière en mémoire. C’est rarement un problème à des tailles de config, et cela vaut la peine d’être su avant que quelqu’un ne pointe cela vers un fichier qui n’est pas vraiment une config.

TOML a de vrais types temporels et JSON non, donc chaque date et datetime devient une chaîne. Les offsets survivent plutôt que d’être normalisés en UTC, une local date arrive exactement comme écrite, et un local time gagne une composante milliseconde qu’il n’avait pas dans la source. La plupart des chargeurs les liront comme du texte sauf si le schéma cible dit autre chose.

Deux littéraux flottants sont destructeurs d’une manière que rien ne signale : inf et nan sont du TOML valide et deviennent null en JSON, donc une limite infinie configurée et une limite non configurée deviennent indiscernables dans le jeu de données. La distinction entier-flottant s’en va aussi, puisque 1.0 est sérialisé en 1 — ce qui compte si une requête est censée distinguer une version d’un compte.

TOML 1.0 exige des entiers 64 bits signés et les nombres JSON sont des doubles IEEE, donc une valeur au-dessus d’environ neuf trillions ne peut pas être représentée exactement. Le parseur s’arrête avec une erreur nommant la ligne plutôt que d’écrire un nombre arrondi dans votre jeu de données.

C’est le bon comportement pour un inventaire en particulier, où un mauvais nombre serait indiscernable d’un bon à travers dix mille enregistrements. Quand cela arrive, mettez la valeur entre guillemets comme chaîne dans le fichier source — c’était un identifiant plutôt qu’une quantité dans chaque cas réel où cela arrive.

Des configs de projets différents n’auront pas les mêmes sections. L’une déclare une table d’outil avec trois linters dedans, la suivante n’en déclare aucune, une troisième utilise une clé que personne d’autre n’utilise. Chaque ligne porte seulement les clés que son fichier avait, ce qui est un vrai avantage sur l’aplatissement de la même collection dans une table où les colonnes devraient être l’union de tout.

La destination décide combien cela coûte. Un magasin schema-on-read gère nativement les enregistrements irréguliers et permet à une requête de demander une clé que seuls certains enregistrements portent. Un chargeur à schéma fixe rejettera les valeurs aberrantes ou supprimera les champs. Échantillonnez les fichiers les plus larges et les plus étroits de la collection avant de définir la cible, plutôt qu’après avoir chargé huit mille enregistrements.

Les commentaires TOML sont le raisonnement dans une config : pourquoi une dépendance est épinglée, à quel ticket appartient un contournement, ce que signifie un nombre magique. NDJSON est du JSON par ligne et JSON n’a pas de syntaxe de commentaire, donc tout cela est absent du jeu de données.

C’est acceptable pour un inventaire et inacceptable comme migration. Personne qui demande quels paquets épinglent une version n’a besoin de la prose environnante ; toute personne qui remplace les fichiers TOML par quelque chose généré à partir de ces données la jetterait. Utilisez le flux pour répondre à des questions sur les configs, et laissez les configs là où elles sont.

Si vous n’avez qu’une seule config à lire, convertissez-la en JSON à la place. Le JSON indenté est lisible, jq le gère à l’identique, et un fichier d’une seule ligne est pire à toute fin sauf l’ajouter à un autre. NDJSON gagne sa place au moment où il y a beaucoup de fichiers et où ils vont dans quelque chose.

L’autre limite est la récurrence. Si l’inventaire doit être reconstruit selon un calendrier, le travail a sa place dans un script qui parcourt l’arborescence, analyse chaque fichier avec une vraie bibliothèque TOML et émet les lignes avec le chemin déjà attaché. Ce convertisseur est pour construire le jeu de données la première fois, décider si les questions auxquelles il répond valent la peine d’être automatisées, et le faire sans qu’aucun des fichiers quitte votre machine.