Nous apprécions tous Ansible, mais Ansible, c'est du 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, le YAML est souvent considéré comme particulièrement difficile parmi tous ces formats. En particulier, malgré son minimalisme rafraîchissant et ses impressionnantes capacités de manipulation des valeurs hiérarchiques, la syntaxe YAML peut agacer avec sa manière d'aborder les indentations, semblable à Python.
Si YAML vous exaspère, vous pouvez – et vous devez ! – entreprendre les 10 étapes suivantes pour réduire votre frustration à un niveau acceptable et apprendre à aimer YAML. Comme il se doit dans une véritable liste, notre top 10 sera numéroté à partir de zéro, à vous de rajouter méditation et pratiques spirituelles si vous le souhaitez 😉
0. Faites fonctionner votre éditeur
Peu importe l'éditeur de texte que vous utilisez – il existe certainement au moins un plugin pour travailler avec YAML. Si vous n'en avez pas, trouvez et installez-le immédiatement. Le temps que vous dépenserez à chercher et à configurer sera largement compensé chaque fois que vous aurez besoin d'éditer du YAML.
Par exemple, l'éditeur prend en charge YAML par défaut, tandis que pour GNU Emacs, vous devrez installer des paquets supplémentaires, par exemple, .
Emacs en mode YAML et affichant les espaces.
Si votre éditeur préféré ne dispose pas d'un mode YAML, certains problèmes peuvent être résolus en ajustant les paramètres. Par exemple, l'éditeur de texte par défaut de GNOME, Gedit, n'a pas de mode YAML, mais il met en surbrillance par défaut la syntaxe du YAML et permet de configurer les indentations :
Configuration des indentations dans Gedit.
Et le plugin pour Gedit affiche les espaces sous forme de points, éliminant toute ambiguïté concernant les niveaux d'indentation.
En d'autres termes, prenez le temps d'explorer votre éditeur préféré. Découvrez ce qu'il propose ou ce que sa communauté de développeurs offre pour travailler avec YAML, et utilisez ces fonctionnalités. Vous ne le regretterez pas.
1. Utilisez un linter
Idéalement, les langages de programmation et de balisage utilisent une syntaxe prévisible. Les ordinateurs gèrent bien la prévisibilité, c'est pourquoi le concept de a vu le jour en 1978. Si cette notion vous a échappé pendant 40 ans et que vous n'utilisez toujours pas de linter pour YAML, c'est le moment d'essayer yamllint.
Installer vous pouvez utiliser le gestionnaire de paquets Linux par défaut. Par exemple, dans 8 ou cela se fait comme suit :
$ sudo dnf install yamllint
Ensuite, vous exécutez simplement yamllint en lui passant le fichier YAML à vérifier. Voici à quoi cela ressemble lorsque vous passez le linter un fichier avec une erreur :
$ yamllint errorprone.yaml
errorprone.yaml
23:10 erreur erreur de syntaxe : les valeurs de mappage ne sont pas autorisées ici
23:11 erreur espaces de fin (trailing-spaces)
Les chiffres à gauche ne sont pas des heures, mais les coordonnées de l'erreur : numéro de ligne et numéro 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 il est fort probable que tout devienne clair.
Lorsque yamllint ne trouve pas d'erreurs dans le fichier, rien n'est affiché à l'écran. Si ce silence vous effraie et que vous souhaitez un peu plus de retour, vous pouvez exécuter le linter avec une commande echo conditionnelle via un double ampersand (&&), comme ceci :
$ yamllint perfect.yaml && echo "OK"
OK
Dans POSIX, le double ampersand ne s'exécute que lorsque la commande précédente retourne 0. Or, yamllint retourne le nombre d'erreurs trouvées, donc toute cette structure conditionnelle fonctionne.
2. Écrivez en Python, pas en YAML
Si YAML vous rends vraiment fou, ne l'écrivez tout simplement pas, au sens propre. Parfois, YAML est le seul format que l'application accepte. Mais même dans ce cas, il n'est pas nécessaire de créer un fichier YAML. Écrivez dans le format que vous aimez, puis convertissez-le. Par exemple, pour Python, il existe une excellente bibliothèque et deux manières de le convertir : la conversion autonome et la conversion via des scripts.
Conversion autonome
Dans ce cas, le fichier de données est également un script Python qui génère du YAML. Cette méthode est la mieux adaptée pour des ensembles de données petits. Vous écrivez simplement des données JSON dans une variable Python, précédez cela de la directive import, et à la fin du fichier, ajoutez trois lignes pour réaliser 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, nous exécutons ce fichier en Python et nous obtenons à la sortie le fichier output.yaml :
$ python3 ./example.json
$ cat output.yaml
glossary:
GlossDiv:
GlossList:
GlossEntry:
Abbrev: ISO 8879:1986
Acronym: SGML
GlossDef:
GlossSeeAlso: [GML, XML]
para: Un langage de méta-marque, utilisé pour créer des langages de balisage tels que DocBook.
GlossSee: balisage
GlossTerm: Langage de balisage généralisé standard
ID: SGML
SortAs: SGML
title: S
title: glossaire d'exemple
C'est un YAML absolument correct, mais yamllint émettra un avertissement qu'il ne commence pas par —. Eh bien, cela peut être facilement corrigé manuellement ou légèrement amélioré dans le script Python.
Conversion via scripts
In this case, we first write in JSON, and then we run the converter as a separate Python script, which outputs YAML. Compared to the previous method, this one scales better, as the conversion is separated from the data.
First, let's create a JSON file example.json; for example, it can be taken from :
{
"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"
}
}
}
}
}
Then we will create a simple converter script and save it as json2yaml.py. This script imports both the YAML and JSON Python modules, loads the user-specified JSON file, performs the conversion, and writes the data to the output.yaml file.
#!/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()
Save this script in the system path and run it as needed:
$ ~/bin/json2yaml.py example.json
3. Parse a lot and often
Sometimes it's useful to look at a problem from a different angle. If you find it hard to visualize the relationships between data in YAML, you can temporarily convert it into something more familiar.
For example, if you prefer working with dictionary lists or JSON, you can convert YAML to JSON with just two commands in the Python interactive shell. Suppose you have a YAML file mydata.yaml, here's how it looks:
$ 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 Roadn', 'city': 'Brooklyn', 'state': 'Wellington', 'postal': 6021, 'country': 'NZ'}}, 'words': 938, 'comments': 'Good article. Could be better.'}
There are many other examples on this topic. Additionally, there are numerous online converters and local parsers available. So don't hesitate to reformat data when you see only an incomprehensible jumble.
4. Read the specs
Returning to YAML after a long break, it's useful to visit and reread the specifications. If you have difficulties with YAML, but haven't gotten around to the specifications, it's time to correct that. The specs are surprisingly well-written, and the syntax requirements are illustrated with many examples in .
5. Pseudoconfigs
Lors de l'écriture d'un livre ou d'un article, il est toujours utile de commencer par esquisser un plan préliminaire, même sous la forme d'une table des matières. Il en va de même pour le YAML. Vous savez probablement quels sont les données à inclure dans le fichier YAML, mais vous comprenez moins comment les lier entre elles. Donc, avant de créer votre YAML, dessinez un pseudo-config.
Le pseudo-config ressemble à du pseudo-code, où il n'est pas nécessaire de se soucier de la structure, des indentations, de la relation « parent-enfant », de l'héritage et de l'imbrication. Ici, vous dessinez les itérations des données au fur et à mesure qu'elles apparaissent dans votre esprit.
Pseudo-config énumérant les programmeurs (Martin et Tabitha) et leurs compétences (langages de programmation : Python, Perl, Pascal et Lisp, Fortran, Erlang, respectivement).
Après avoir dessiné le pseudo-config sur une feuille de papier, examinez-le attentivement et, si tout est en ordre, mettez-le au format d'un fichier YAML valide.
6. Le dilemme « tabulation ou espaces »
Vous devez résoudre le dilemme . Pas dans un sens global, mais seulement au niveau de votre organisation, ou au moins de votre projet. Peu importe si une post-traitement avec un script sed est utilisé, si les éditeurs de texte sont configurés sur les machines des programmeurs, ou si des reçus stricts sur le respect des directives du linter sont exigés sous peine de licenciement, tous les membres de votre équipe qui sont à un moment ou un autre concernés par le YAML doivent obligatoirement utiliser des espaces (comme stipulé par la spécification YAML).
Dans tout éditeur de texte normal, il est possible de configurer l'auto-remplacement de la tabulation par un nombre défini d'espaces, donc il n'y a pas lieu de craindre une révolte des partisans de la touche Tab .
Comme chacun sait, il n'y a pas de différence visible entre les tabulations et les espaces à l'écran. Et quand quelque chose n'est pas visible, cela est généralement oublié en dernier, après avoir examiné et résolu tous les autres problèmes possibles. Une heure perdue à chercher une tabulation tordue ou un bloc d'espaces crie qu'il est urgent de créer une politique d'utilisation de l'un ou l'autre, puis de mettre en place un contrôle strict de son respect (par exemple, via un hook Git pour forcer le passage à travers le linter).
7. Mieux vaut peu mais bon (ou beaucoup – c'est moins)
Certain people enjoy writing in YAML because it highlights structure. They actively use indentation to distinguish data blocks, which is somewhat of a trick to mimic markup languages that use explicit delimiters.
Here is an example of such structuring from :
# Employee records
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
For some, this option helps organize the structure of YAML in their minds, while for others, it is irritating due to the excessive indentation they deem unnecessary.
But if you are the owner of a YAML document and responsible for its maintenance, then you and only you should determine how to use indentation. If large indentations annoy you, reduce them to the minimum allowed according to the YAML specification. For example, the above file from Ansible documentation can be rewritten like this without any loss:
---
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
8. Use templates
If you constantly make the same mistakes when filling out a YAML file, it makes sense to insert a template-comment into it. Then next time, you can simply copy this template and fill in the real data, for example:
---
# - <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. Use something else
If the application doesn't hold you captive, it might be worth switching from YAML to another format. Over time, configuration files can outgrow themselves, and it is better to convert them to simple scripts in Lua or Python.
YAML is a great tool that many appreciate for its minimalism and simplicity, but it is by no means the only tool in your arsenal. So sometimes you can do without it. There are easy-to-find parsing libraries for YAML, so if you offer convenient migration options, your users will relatively painlessly endure such a transition.
If you can't do without YAML, then take these 10 tips to heart and overcome your dislike for YAML once and for all!
Source : habr.com
