Mes commentaires vont-ils survivre ?

Oui — et c’est tout l’objet de cette page. Un formateur qui lit le document en valeur puis réécrit cette valeur **supprime tous les commentaires**, et le résultat est du YAML valide : rien ne vous prévient. Celui-ci conserve le document lui-même et ne change que sa disposition.

Qu’advient-il de mes ancres et de mes clés de fusion ?

Elles restent telles quelles. `base: &defaults` et `<<: *defaults` reviennent inchangées, toujours liées. Les déplier recopierait le bloc chez chaque utilisateur, allongeant le fichier et vous laissant deux endroits à modifier au lieu d’un.

Puis-je mettre en forme un fichier à plusieurs documents ?

Oui. `---` les sépare, chacun est mis en forme sur place et les séparateurs sont conservés. Cela compte parce qu’un manifeste Kubernetes est en général exactement cela, et qu’il était jusqu’ici refusé tout net.

Formateur YAML — commentaires et ancres survivent

Réindentez du YAML sans toucher à ce qu’il dit. Vos commentaires et vos ancres passent : le fichier reste celui que vous vouliez committer.

Ce que fait cet outil

Il réindente. Il ne réécrit pas.

# Base de production — prévenir l’astreinte avant de toucher
db:
    host: db.example.com   # bascule manuelle
    port: 5432

Indentation à deux espaces, et tout le reste exactement comme vous l’avez écrit : le commentaire au-dessus de db, celui après host, le style de guillemets de chaque scalaire.

La méthode évidente perd vos commentaires

La façon évidente d’écrire un formateur YAML est d’analyser le fichier en valeur puis de sérialiser cette valeur. Elle est aussi fausse, de deux manières qui ne laissent aucune trace.

Tous les commentaires disparaissent. Une valeur n’a pas de commentaires : ils vivent dans le document, pas dans les données. Un fichier de configuration que quelqu’un a documenté — pourquoi ce délai, qui appeler, ce qui casse si on y touche — revient muet, et la sortie est du YAML valide : rien ne dit ce qui a été perdu.

Les ancres sont dépliées. Ceci :

base: &defaults
  restart: always
  logging: json
web:
  <<: *defaults
worker:
  <<: *defaults

devient trois copies du même bloc, plus long que l’entrée, le lien entre elles envolé. La prochaine personne qui change restart devra les retrouver toutes les trois.

Ce formateur conserve le document et ne change que sa disposition.

Les valeurs ambiguës sont laissées telles quelles

country: NO reste country: NO.

Un lecteur YAML 1.2 y voit la chaîne NO ; un lecteur YAML 1.1 — PyYAML — y voit le booléen faux. Ajouter des guillemets trancherait la question, et cette question revient à l’auteur, pas à un formateur : un fichier écrit pour PyYAML voulait peut-être bien dire faux.

Les outils de conversion, eux, mettent des guillemets, et ils ont raison : ils partent d’une valeur dont ils savent que c’est une chaîne. Un formateur part d’un fichier, et un fichier ne dit rien.

Plusieurs documents dans un fichier

--- sépare les documents YAML, et un fichier peut en contenir autant qu’il veut. Chacun est mis en forme sur place et les séparateurs restent. C’est la forme de la plupart des manifestes Kubernetes : un flux, pas une erreur.

Les réglages

Indentation — deux espaces par défaut, ou ce que vous choisissez.

Trier les clés — alphabétiquement, récursivement, chaque commentaire suivant l’entrée à laquelle il était attaché. Utile pour comparer deux fichiers qui ont divergé ; laissez-le désactivé si l’ordre de vos clés signifie quelque chose, ce qui dans un fichier de configuration est souvent le cas.

Confidentiel par conception

Tout s’exécute localement dans votre navigateur en JavaScript. Vos données ne sont jamais envoyées sur un serveur, ce qui rend l’outil sûr pour des contenus sensibles, et il fonctionne hors ligne.

Formateur YAML — commentaires et ancres survivent

Entrée YAML

Sortie YAML