Nous aimons tous Ansible, mais Ansible est YAML. Il existe de nombreux formats pour les fichiers de configuration: listes de valeurs, paires paramètre-valeur, fichiers INI, YAML, JSON, XML et bien d'autres. Cependant, pour plusieurs raisons, parmi celles-ci, YAML est souvent considéré comme particulièrement difficile. En particulier, malgré son minimalisme rafraîchissant et ses capacités impressionnantes pour travailler avec des valeurs hiérarchiques, la syntaxe YAML peut être agaçante avec son approche d'indentation de type Python.
Si YAML vous exaspère, vous pouvez - et vous devez! - Suivez les 10 étapes suivantes pour réduire votre irritation à un niveau acceptable et aimez YAML. Comme il se doit sur cette liste, nos dix conseils seront numérotés à partir de zéro, nous ajoutons à volonté la méditation et les pratiques spirituelles ;-)
0. Faites travailler votre éditeur
Peu importe le type d'éditeur de texte dont vous disposez - pour lui, bien sûr, il existe au moins un plugin pour travailler avec YAML. Si vous n'en avez pas, recherchez et installez immédiatement. Le temps consacré à la recherche et à la configuration sera payant plusieurs fois à chaque fois que vous devrez modifier YAML.
Par exemple, l'éditeur
Atom prend en charge YAML par défaut, mais GNU Emacs devra installer des packages supplémentaires, par exemple, en
mode yaml .
Emacs en mode YAML et espaces d'affichage.Si votre éditeur préféré ne dispose pas du mode YAML, certains des problèmes peuvent être résolus en travaillant avec les paramètres. Par exemple, l'éditeur de texte Gedit standard pour GNOME n'a pas de mode YAML, mais il met par défaut en surbrillance la syntaxe YAML et vous permet de configurer l'indentation:
Paramètres d'indentation Gedit.Et le plugin
drawspaces pour Gedit affiche les espaces sous forme de points, éliminant les ambiguïtés avec les niveaux d'indentation.
En d'autres termes, prenez le temps d'étudier votre éditeur préféré. Découvrez ce que lui ou sa communauté de développement propose de travailler avec YAML et utilisez ces fonctionnalités. Vous ne le regretterez certainement pas.
1. Utilisez un linter (linter)
Idéalement, les langages de programmation et de balisage utilisent une syntaxe prévisible. Les ordinateurs font un bon travail de prévisibilité, donc en 1978, le concept du
linter est apparu . Si pendant 40 ans de son existence, il vous a dépassé et que vous n'utilisez toujours pas le YAML-linter, alors il est temps d'essayer yamllint.
Vous pouvez installer
yamllint à l'aide du gestionnaire de packages Linux standard. Par exemple, sur
Red Hat Enterprise Linux 8 ou
Fedora, cela se fait comme ceci:
$ sudo dnf install yamllint
Ensuite, vous exécutez simplement yamllint, en lui passant le fichier YAML pour vérification. Voici à quoi cela ressemble si vous passez un fichier d'erreur au linter:
$ yamllint errorprone.yaml errorprone.yaml 23:10 error syntax error: mapping values are not allowed here 23:11 error trailing spaces (trailing-spaces)
Les chiffres de gauche ne sont pas le temps, mais les coordonnées de l'erreur: numéro de ligne et de colonne. La description de l'erreur peut ne rien vous dire, mais vous savez exactement où elle se trouve. Il suffit de regarder cet endroit dans le code, et très probablement, tout deviendra clair.
Lorsque yamllint ne trouve pas d'erreurs dans le fichier, rien ne s'affiche. Si vous avez peur d'un tel silence et que vous souhaitez un peu plus de rétroaction, vous pouvez démarrer le linter avec la commande d'écho conditionnel via la double esperluette (&&), comme ceci:
$ yamllint perfect.yaml && echo "OK" OK
Dans POSIX, une double esperluette est déclenchée si et seulement si la commande précédente retourne 0. Et yamllint renvoie juste le nombre d'erreurs trouvées, donc toute cette construction conditionnelle fonctionne.
2. Écrivez en Python, pas en YAML
Si YAML vous fait vraiment chier, n'écrivez pas dessus littéralement. Il arrive que YAML soit le seul format perçu par l'application. Mais dans ce cas, il n'est pas nécessaire de créer un fichier YAML. Écrivez ce que vous aimez, puis convertissez. Par exemple, pour Python, il existe une excellente bibliothèque
pyyaml et deux méthodes de conversion complètes: l'auto-conversion et la conversion basée sur un script.
Auto-conversion
Dans ce cas, le fichier de données est également un script Python qui génère YAML. Cette méthode convient mieux aux petits ensembles de données. Vous écrivez simplement des données JSON dans une variable Python, préfixez-la avec la directive import et ajoutez trois lignes à la fin du fichier pour implémenter la sortie.
#!/usr/bin/python3 import yaml d={ "glossary": { "title": "example glossary", "GlossDiv": { "title": "S", "GlossList": { "GlossEntry": { "ID": "SGML", "SortAs": "SGML", "GlossTerm": "Standard Generalized Markup Language", "Acronym": "SGML", "Abbrev": "ISO 8879:1986", "GlossDef": { "para": "A meta-markup language, used to create markup languages such as DocBook.", "GlossSeeAlso": ["GML", "XML"] }, "GlossSee": "markup" } } } } } f=open('output.yaml','w') f.write(yaml.dump(d)) f.close
Maintenant, exécutez ce fichier en Python et le fichier de sortie est output.yaml:
$ python3 ./example.json $ cat output.yaml glossary: GlossDiv: GlossList: GlossEntry: Abbrev: ISO 8879:1986 Acronym: SGML GlossDef: GlossSeeAlso: [GML, XML] para: A meta-markup language, used to create markup languages such as DocBook. GlossSee: markup GlossTerm: Standard Generalized Markup Language ID: SGML SortAs: SGML title: S title: example glossary
C'est YAML absolument correct, mais yamllint vous avertira qu'il ne commence pas par ---. Eh bien, cela peut être facilement corrigé manuellement ou légèrement modifié le script Python.
Convertir via des scripts
Dans ce cas, nous écrivons d'abord en JSON, puis exécutons le convertisseur sous la forme d'un script Python distinct, qui produit YAML dans la sortie. Par rapport à la précédente, cette méthode évolue mieux car la conversion est séparée par les données.
Tout d'abord, créez le fichier JSON example.json, par exemple, vous pouvez le prendre sur
json.org :
{ "glossary": { "title": "example glossary", "GlossDiv": { "title": "S", "GlossList": { "GlossEntry": { "ID": "SGML", "SortAs": "SGML", "GlossTerm": "Standard Generalized Markup Language", "Acronym": "SGML", "Abbrev": "ISO 8879:1986", "GlossDef": { "para": "A meta-markup language, used to create markup languages such as DocBook.", "GlossSeeAlso": ["GML", "XML"] }, "GlossSee": "markup" } } } } }
Créez ensuite un convertisseur de script simple et enregistrez-le sous le nom json2yaml.py. Ce script importe les deux modules - YAML et JSON Python, et charge également le fichier JSON spécifié par l'utilisateur, effectue la conversion et écrit des données dans le fichier output.yaml.
#!/usr/bin/python3 import yaml import sys import json OUT=open('output.yaml','w') IN=open(sys.argv[1], 'r') JSON = json.load(IN) IN.close() yaml.dump(JSON, OUT) OUT.close()
Enregistrez ce script dans le chemin système et exécutez-le si nécessaire:
$ ~/bin/json2yaml.py example.json
3. Analysez beaucoup et souvent
Parfois, il est utile d’examiner le problème sous un angle différent. Si vous trouvez difficile d'imaginer les relations entre les données dans YAML, vous pouvez temporairement les transformer en quelque chose de plus familier.
Par exemple, si vous êtes à l'aise avec les listes de dictionnaires ou JSON, alors YAML peut être converti en JSON avec seulement deux commandes dans le shell interactif Python. Supposons que vous ayez un fichier YAML mydata.yaml, alors voici à quoi il ressemblerait:
$ python3 >>> f=open('mydata.yaml','r') >>> yaml.load(f) {'document': 34843, 'date': datetime.date(2019, 5, 23), 'bill-to': {'given': 'Seth', 'family': 'Kenlon', 'address': {'street': '51b Mornington Road\n', 'city': 'Brooklyn', 'state': 'Wellington', 'postal': 6021, 'country': 'NZ'}}, 'words': 938, 'comments': 'Good article. Could be better.'}
De nombreux autres exemples peuvent être trouvés à ce sujet. De plus, il existe de nombreux convertisseurs en ligne et analyseurs locaux. N'hésitez donc pas à reformater les données lorsque vous n'y voyez qu'un hachage incompréhensible.
4. Lire les spécifications
De retour à YAML après une longue pause, il est utile d’aller sur
yaml.org et de relire les spécifications. Si vous rencontrez des difficultés avec YAML, mais que vos mains n’ont pas atteint les spécifications, il est temps de corriger cette situation. Les spécifications sont étonnamment faciles à écrire et les exigences de syntaxe sont illustrées par un grand nombre d'exemples au
chapitre 6 .
5. Pseudoconfigs
Lors de la rédaction d'un livre ou d'un article, il est toujours utile de commencer par esquisser un plan préliminaire, au moins sous la forme d'une table des matières. Il en va de même avec YAML. Très probablement, vous imaginez quelles données vous devez écrire dans le fichier YAML, mais vous ne comprenez pas vraiment comment les relier les unes aux autres. Par conséquent, avant de sculpter YAML, dessinez une pseudo-configuration.
La pseudo-configuration est similaire au pseudo-code, où vous n'avez pas à vous soucier de la structure ou de l'indentation, des relations parent-enfant, de l'héritage et de l'imbrication. C'est donc ici: vous dessinez des itérations de données au fur et à mesure qu'elles surgissent dans votre tête.
Une pseudo-configuration listant les programmeurs (Martin et Tabitha) et leurs compétences (langages de programmation: Python, Perl, Pascal et Lisp, Fortran, Erlang, respectivement).Après avoir dessiné une pseudo-config sur une feuille de papier, analysez-la soigneusement et, si tout est en ordre, formatez-la comme un fichier YAML valide.
6. L'onglet ou le dilemme dilemme
Vous devez résoudre le dilemme
"tabulations ou espaces?" . Pas dans un sens global, mais uniquement au niveau de votre organisation, ou du moins un projet. Peu importe que vous utilisiez le post-traitement avec le script sed, que vous installiez des éditeurs de texte sur les machines des programmeurs ou que vous preniez des reçus sur le strict respect des instructions du linter sous la menace de licenciement, mais tous les membres de votre équipe qui se rapportent d'une manière ou d'une autre à YAML doivent Utilisez uniquement des espaces (comme requis par la spécification YAML).
Dans n'importe quel éditeur de texte normal, vous pouvez définir des tabulations de correction automatique sur un nombre spécifié d'espaces, de sorte que vous ne puissiez pas avoir peur des émeutes de
tabulations .
Comme tous les haineux de YAML le savent bien, la différence entre les tabulations et les espaces n'est pas visible à l'écran. Et lorsque quelque chose n'est pas visible, cela est généralement mémorisé en dernier, après avoir été trié, vérifié et éliminé tous les autres problèmes possibles. L'heure perdue pour rechercher une courbe de tabulation ou un bloc d'espaces crie simplement que vous devez de toute urgence créer une stratégie d'utilisation de l'un ou de l'autre, puis implémenter une vérification en béton armé de sa conformité (par exemple, via un crochet Git pour un passage forcé dans le linter).
7. Mieux vaut moins c'est mieux (ou plus c'est moins)
Certaines personnes aiment écrire en YAML car cela met l'accent sur la structure. Dans le même temps, ils utilisent activement l'indentation pour mettre en évidence les blocs de données. Il s'agit d'une sorte d'escroquerie pour simuler des langages de balisage qui utilisent des délimiteurs explicites.
Voici un exemple d'une telle structure de la
documentation Ansible :
# Employee records - martin: name: Martin D'vloper job: Developer skills: - python - perl - pascal - tabitha: name: Tabitha Bitumen job: Developer skills: - lisp - fortran - erlang
Pour certains, cette option aide à décomposer la structure YAML dans la tête; au contraire, elle agace les autres avec beaucoup d'indentation indésirable, à leur avis.
Mais si vous êtes le propriétaire d'un document YAML et êtes responsable de sa maintenance,
vous et vous seul devez déterminer comment utiliser l'indentation. Si vous êtes ennuyé par une grande indentation, gardez-les au minimum possible selon la spécification YAML. Par exemple, le fichier ci-dessus de la documentation Ansible peut être réécrit sans aucune perte comme ceci:
--- - martin: name: Martin D'vloper job: Developer skills: - python - perl - pascal - tabitha: name: Tabitha Bitumen job: Developer skills: - lisp - fortran - erlang
8. Utilisez des blancs
Si vous répétez constamment les mêmes erreurs lorsque vous remplissez le fichier YAML, il est logique d'y insérer un modèle vierge en tant que commentaire. La prochaine fois, il sera possible de copier simplement cette pièce et d'y saisir des données réelles, par exemple:
--- # - <common name>: # name: Given Surname # job: JOB # skills: # - LANG - martin: name: Martin D'vloper job: Developer skills: - python - perl - pascal - tabitha: name: Tabitha Bitumen job: Developer skills: - lisp - fortran - erlang
9. Utilisez autre chose
Si l'application ne vous tient pas dans une mainmise, il vaut peut-être la peine de changer YAML dans un autre format. Au fil du temps, les fichiers de configuration peuvent se développer eux-mêmes et il est préférable de les convertir en scripts simples en Lua ou en Python.
YAML est une grande chose que beaucoup de gens adorent pour son minimalisme et sa simplicité, mais c'est loin d'être le seul outil de votre arsenal. Alors parfois, vous pouvez le refuser. Il est facile pour YAML de trouver des bibliothèques d’analyse, donc si vous proposez des options de migration pratiques, vos utilisateurs survivront relativement facilement à cet échec.
Si vous ne pouvez pas vous passer de YAML, alors mettez ces 10 conseils en service et battez votre aversion pour YAML une fois pour toutes!