We all love Ansible, but Ansible is YAML. There are many formats for configuration files: lists of values, key-value pairs, INI files, YAML, JSON, XML, and many others. However, for several reasons, among all of them, YAML is often considered particularly challenging. In particular, despite its refreshing minimalism and impressive capabilities for handling hierarchical values, YAML's syntax can be frustrating with its Python-like indentation approach.
If YAML frustrates you, you can ā and should! ā take the following 10 steps to lower your irritation to an acceptable level and come to love YAML. As a proper list should be, our ten tips will be numbered starting from zero, and you can add meditation and spiritual practices at your discretion š
0. Get your editor to work
It doesn't matter what text editor you have ā there is likely at least one plugin available for working with YAML. If you donāt have one, find and install it immediately. The time spent searching for and configuring it will pay off multiple times each time you need to edit YAML.
For example, the editor supports YAML by default, whereas for GNU Emacs, you need to install additional packages, such as .
Emacs in YAML mode and displaying spaces.
If your favorite editor doesnāt have a YAML mode, some issues can be resolved by adjusting the settings. For instance, GNOME's default text editor Gedit doesnāt have a YAML mode, but it does highlight YAML syntax by default and allows you to adjust indentation settings:
Adjusting indentation in Gedit.
And the plugin for Gedit displays spaces as dots, eliminating confusion with indentation levels.
In other words, take the time to learn your favorite editor. Find out what it or its development community offers for working with YAML, and make use of those features. You definitely wonāt regret it.
1. Use a linter
Ideally, programming languages and markup languages use predictable syntax. Computers handle predictability well, which is why the concept of a emerged back in 1978. If youāve missed it in the 40 years of its existence and still don't use a YAML linter, now is the time to try yamllint.
Installeer kan worden gedaan met de standaard package manager van Linux. Bijvoorbeeld in 8 of zo doe je dat:
$ sudo dnf install yamllint
Daarna voer je gewoon yamllint uit, waarbij je het YAML-bestand voor controle doorgeeft. Zo ziet het eruit als je de linter een bestand met een fout doorgeeft:
$ yamllint errorprone.yaml
errorprone.yaml
23:10 fout syntaxisfout: mappingwaarden zijn hier niet toegestaan
23:11 fout achterlopende spaties (trailing-spaces)
De cijfers links zijn geen tijd, maar de coƶrdinaten van de fout: regel- en kolomnummer. De beschrijving van de fout zegt je misschien niets, maar je weet precies waar deze zich bevindt. Kijk gewoon op die plek in de code, en waarschijnlijk is alles dan duidelijk.
Wanneer yamllint geen fouten in het bestand vindt, wordt er niets weergegeven. Als je bang bent voor die stilte en een beetje meer feedback wilt, kun je de linter uitvoeren met een voorwaardelijke echo-opdracht via de dubbele ampersand (&&), zo:
$ yamllint perfect.yaml && echo "OK"
OK
In POSIX werkt de dubbele ampersand alleen als het voorafgaande commando 0 retourneert. En yamllint retourneert precies het aantal gevonden fouten, dus deze voorwaardelijke constructie werkt.
2. Schrijf in Python, niet in YAML
Als YAML je echt irriteert, schrijf er dan gewoon niet in, letterlijk. Soms is YAML het enige formaat dat door de applicatie wordt geaccepteerd. Maar zelfs dan is het niet noodzakelijk om een YAML-bestand te maken. Schrijf in wat je leuk vindt en converteer het daarna. Bijvoorbeeld, voor Python is er een geweldige bibliotheek en er zijn zelfs twee manieren om te converteren: zelfconverteren en converteren via scripts.
Zelfconverteren
In dit geval is het gegevensbestand tegelijkertijd ook een Python-script dat YAML genereert. Deze methode is het beste voor kleine datasets. Je schrijft gewoon JSON-gegevens in een Python-variabele, begint met de import-directive, en aan het einde van het bestand voeg je drie regels toe voor de uitvoer.
#!/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
Laten we nu dit bestand op Python draaien en we krijgen als output het bestand output.yaml:
$ python3 . /example.json
$ cat output.yaml
glossary:
GlossDiv:
GlossList:
GlossEntry:
Abbrev: ISO 8879:1986
Acronym: SGML
GlossDef:
GlossSeeAlso: [GML, XML]
para: Een meta-markup-taal, gebruikt om opmaak talen zoals DocBook te creƫren.
GlossSee: markup
GlossTerm: Standard Generalized Markup Language
ID: SGML
SortAs: SGML
title: S
title: voorbeeld glossarium
Dit is absoluut geldig YAML, maar yamllint zal een waarschuwing geven dat het niet begint met ā. Nou, dit kan eenvoudig handmatig worden gecorrigeerd of je kunt het Python-script lichtjes aanpassen.
Converteren via scripts
In dit geval schrijven we eerst in JSON, en vervolgens draaien we de converter als een aparte Python-script die YAML produceert. Vergeleken met de vorige methode is deze beter schaalbaar, omdat de conversie van data is gescheiden.
Laten we beginnen met het aanmaken van een JSON-bestand example.json, dat bijvoorbeeld kan worden gehaald van :
{
"glossary": {
"title": "voorbeeld woordenlijst",
"GlossDiv": {
"title": "S",
"GlossList": {
"GlossEntry": {
"ID": "SGML",
"SortAs": "SGML",
"GlossTerm": "Standard Generalized Markup Language",
"Acronym": "SGML",
"Abbrev": "ISO 8879:1986",
"GlossDef": {
"para": "Een meta-markup taal, gebruikt om markup talen zoals DocBook te creƫren.",
"GlossSeeAlso": ["GML", "XML"]
},
"GlossSee": "markup"
}
}
}
}
}
Laten we vervolgens een eenvoudige converter-script maken en deze opslaan als json2yaml.py. Dit script importeert zowel de YAML- als JSON-modules van Python, laadt het door de gebruiker opgegeven JSON-bestand, voert de conversie uit en schrijft de gegevens naar het output.yaml-bestand.
#!/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()
Bewaar dit script in het systeem pad en voer het uit wanneer nodig:
$ ~/bin/json2yaml.py example.json
3. Parse veel en vaak
Soms is het nuttig om een probleem vanuit een ander perspectief te bekijken. Als je moeite hebt om de relaties tussen gegevens in YAML voor te stellen, kun je ze tijdelijk omzetten naar iets meer vertrouwd.
Als je bijvoorbeeld gewend bent om met woordenlijsten of met JSON te werken, kun je YAML heel gemakkelijk in JSON omzetten met slechts twee commando's in de interactieve Python-shell. Stel dat je een YAML-bestand mydata.yaml hebt, dan zou het er als volgt uitzien:
$ 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': 'Goed artikel. Kan beter zijn.'}
Er zijn tal van andere voorbeelden over dit onderwerp te vinden. Bovendien zijn er veel online converters en lokale parsers beschikbaar. Dus wees niet bang om gegevens te herformatteren wanneer je ze alleen als een onduidelijke mix ziet.
4. Lees specificaties
Als je na een lange pauze terugkeert naar YAML, is het nuttig om de informatie op te bekijken en de specificaties opnieuw door te lezen. Als je moeite hebt met YAML, maar de specificaties nog niet onder ogen hebt gezien, is het tijd om die situatie recht te zetten. De specificaties zijn verrassend gemakkelijk geschreven, en de syntaxisvereisten worden geĆÆllustreerd met veel voorbeelden in .
5. Pseudoconfigs
Bij het schrijven van een boek of artikel is het altijd nuttig om eerst een voorlopig plan op te stellen, zelfs als het maar een inhoudsopgave is. Hetzelfde geldt voor YAML. Je hebt waarschijnlijk een idee van welke gegevens je in het YAML-bestand moet opnemen, maar begrijpt niet goed hoe je ze met elkaar moet verbinden. Dus voordat je aan de slag gaat met YAML, teken eerst een pseudoconfiguratie.
Een pseudoconfiguratie lijkt op pseudocode, waar je je geen zorgen hoeft te maken over de structuur of inspringingen, de 'ouder-kind' relaties, overerving en geneste structuren. Op dezelfde manier teken je hier datalussen naarmate ze in je hoofd ontstaan.
Een pseudoconfiguratie met een opsomming van programmeurs (Martin en Tabitha) en hun vaardigheden (programmeertalen: Python, Perl, Pascal en Lisp, Fortran, Erlang, respectievelijk).
Nadat je de pseudoconfiguratie op papier hebt getekend, analyseer deze dan zorgvuldig en als alles in orde is, maak het dan om in een geldig YAML-bestand.
6. De dilemma 'tabs of spaties'
Je moet de dilemma . Niet in de globale zin, maar alleen op het niveau van jouw organisatie, of althans van het project. Het maakt niet uit of hierbij post-processing wordt gebruikt met een sed-script, teksteditor-instellingen op de machines van programmeurs of collectieve handtekeningen waarin wordt bevestigd dat de regels van de linter strikte naleving vereisen onder dreiging van ontslag, maar alle leden van jouw team die op de een of andere manier met YAML te maken hebben, moeten verplicht alleen spaties gebruiken (zoals de YAML-specificatie vereist).
In elke normale teksteditor kun je de automatische vervangfunctie instellen om tabs te vervangen door een vast aantal spaties, zodat je je geen zorgen hoeft te maken over de opstand van de supporters van de Tab toets.
Zoals elke YAML-hater goed weet, is er op het scherm geen verschil tussen tabs en spaties. En wanneer iets niet zichtbaar is, wordt het meestal als laatste herinnerd, nadat alle andere mogelijke problemen zijn opgehaald, gecontroleerd en verholpen. Een uur verspild aan het zoeken naar een kromme tab of een blok spaties schreeuwt om de noodzaak dat je dringend een beleid moet opstellen voor het gebruik van het een of het ander, en vervolgens een degelijke controle moet implementeren (bijvoorbeeld via een Git-hook voor verplicht linten).
7. Minder is beter (of meer is minder)
Sommige mensen houden ervan om in YAML te schrijven, omdat het de structuur benadrukt. Ze gebruiken actief inspringingen om datablokken te markeren. Dit is een soort truc om markeertalen na te bootsen die expliciete scheidingstekens gebruiken.
Hier is een voorbeeld van die gestructureerdheid uit :
# Employee records
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
Voor sommigen helpt deze aanpak om de structuur van YAML in hun hoofd te ordenen, terwijl anderen zich ergeren aan de overvloed aan overbodige inspringingen, naar hun mening.
Maar als jij de eigenaar bent van een YAML-document en verantwoordelijk voor het onderhoud ervan, dan ben jij de enige die moet bepalen hoe de inspringingen gebruikt worden. Als grote inspringingen je storen, beperk ze dan tot het minimum dat mogelijk is volgens de YAML-specificatie. Bijvoorbeeld, het bovenstaande bestand uit de documentatie van Ansible kan zonder enige verliezen als volgt worden herschreven:
---
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
8. Gebruik sjablonen
Als je bij het invullen van een YAML-bestand steeds dezelfde fouten maakt, kan het nuttig zijn om er een sjablooncommentaar in op te nemen. Dan kun je de volgende keer gewoon dit sjabloon kopiƫren en daar de echte gegevens in invullen, bijvoorbeeld:
---
# - <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. Gebruik iets anders
Als de applicatie je niet dwingt, kan het de moeite waard zijn om YAML te vervangen door een ander formaat. In de loop der tijd kunnen configuratiebestanden zichzelf overschrijden en kan het beter zijn om ze om te zetten in eenvoudige scripts in Lua of Python.
YAML is een geweldig hulpmiddel dat velen waarderen om zijn minimalisme en eenvoud, maar het is niet het enige instrument in je arsenaal. Dus soms kan je er afstand van doen. Voor YAML zijn er gemakkelijk parserbibliotheken te vinden, dus als je handige migratie-opties aanbiedt, zullen je gebruikers deze overgang relatief soepel doormaken.
Als je echter niet om YAML heen kunt, neem dan deze 10 tips ter hand en overwonnen je afkeer van YAML voorgoed!
Bron: habr.com
