Všetci milujeme Ansible, ale Ansible je YAML. Pre konfiguračné súbory existuje množstvo formátov: zoznamy hodnôt, páry „parametr-hodnota“, INI súbory, YAML, JSON, XML a mnohé ďalšie. Napriek tomu sa z rôznych dôvodov z všetkých týchto formátov YAML často považuje za obzvlášť náročný. Predovšetkým, aj keď má osviežujúci minimalizmus a impozantné schopnosti pri práci s hierarchickými hodnotami, syntax YAML môže byť frustrujúca svojím prístupom k odsádzaniu, ktorý sa podobá na Python.
Ak vás YAML vytáča, môžete - a mali by ste! - urobiť nasledujúcich 10 krokov, aby ste znížili svoje roztrhnutie na prijateľnú úroveň a zamilovali sa do YAML. Ako sa patrí na pravý zoznam, našich desať tipov bude číslovaných od nuly, meditáciu a duchovné praktiky pridávame podľa želania 😉
0. Prinúťte svoj editor pracovať
Nezáleží na tom, aký máte textový editor – určite existuje aspoň jeden plugin na prácu s YAML. Ak ho nemáte, okamžite ho nájdite a nainštalujte. Čas strávený jeho hľadaním a nastavením sa mnohonásobne vyplatí zakaždým, keď budete musieť upravovať YAML.
Napríklad editor podporuje YAML predvolene, ale pre GNU Emacs je potrebné nainštalovať ďalšie balíčky, napríklad .
Emacs v režime YAML a zobrazovanie medzier.
Ak vo vašom obľúbenom editore nie je režim YAML, niektoré problémy môžete vyriešiť nastaveniami. Napríklad predvolený textový editor GNOME Gedit nemá režim YAML, ale predvolene zvýrazňuje syntax YAML a umožňuje nastaviť prácu s odsadzovaním:
Nastavenie odsadení v Gedit.
A plugin pre Gedit zobrazuje medzery ako body, čím eliminuje nejasnosti s úrovňami odsadenia.
Inými slovami, venujte čas štúdiu svojho obľúbeného editora. Zistite, čo váš editor alebo jeho vývojárska komunita ponúka pre prácu s YAML, a využite tieto možnosti. Určite to nebudete ľutovať.
1. Použite linter (linter)
Ideálne programovacie jazyky a značkovacie jazyky používajú predvídateľnú syntax. Počítače sa s predvídateľnosťou dobre vyrovnávajú, a preto už v roku 1978 vznikla koncepcia . Ak vás za 40 rokov jeho existencie obchádzala a stále nepoužívate YAML linter, je najvyšší čas vyskúšať yamllint.
Nainštalovať môžete to urobiť prostredníctvom štandardného manažéra balíkov Linux. Napríklad v 8 alebo to sa robí takto:
$ sudo dnf install yamllint
Potom jednoducho spustíte yamllint, pričom mu odovzdáte YAML súbor na kontrolu. Takto to vyzerá, ak odovzdáte linteru súbor s chybou:
$ yamllint errorprone.yaml
errorprone.yaml
23:10 error syntax error: mapping values are not allowed here
23:11 error trailing spaces (trailing-spaces)
Čísla vľavo nie sú čas, ale súradnice chyby: číslo riadku a stĺpca. Opis chyby vám nemusí veľa povedať, ale presne viete, kde sa nachádza. Stačí sa pozrieť na toto miesto v kóde a pravdepodobne všetko bude jasné.
Keď yamllint nenájde žiadne chyby v súbore, na obrazovku sa nič nevypíše. Ak vás taká ticho desí a chcete trochu viac spätnej väzby, môžete spúšťať linter s podmieneným príkazom echo cez dvojitý ampersand (&&), takto:
$ yamllint perfect.yaml && echo "OK"
OK
V POSIX dvojitý ampersand funguje iba vtedy, keď predchádzajúci príkaz vráti 0. A yamllint presne vracia počet nájdených chýb, takže celá táto podmienená konštrukcia funguje.
2. Píšte v Pythone, nie v YAML
Ak vás YAML naozaj štvú, jednoducho ho nepíšte, v doslovnom zmysle. Niekedy je YAML jediný formát, ktorý aplikácia akceptuje. Ale aj v takom prípade nie je nutné vytvárať YAML súbor. Píšte v čom sa vám páči a potom konvertujte. Napríklad pre Python existuje vynikajúca knižnica a celých dvoch spôsobov konverzie: samokonverziou a konverziou cez skripty.
Samokonverzia
V tomto prípade je súbor s údajmi zároveň aj Python skript, ktorý generuje YAML. Tento spôsob je najvhodnejší pre malé množstvá údajov. Jednoducho napíšete JSON údaje do premennej Python, predtým pridáte príkaz import a na konci súboru pridáte tri riadky na generovanie výstupu.
#!/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
Teraz spúšťame tento súbor na Pythone a na výstupe dostávame súbor 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
Toto je úplne korektný YAML, ale yamllint vydá varovanie, že nezačína s —. Nuž, to sa dá ľahko opraviť ručne alebo mierne upraviť Python skript.
Konverzia prostredníctvom skriptov
V tomto prípade najprv píšeme do JSON-u a potom spustíme konvertor ako samostatný Python skript, ktorý na výstupe dáva YAML. V porovnaní s predchádzajúcim tento spôsob lepšie škáluje, pretože konverzia je oddelená od dát.
Najskôr vytvorme JSON súbor example.json, ktorý si môžete stiahnuť z :
{
"glossary": {
"title": "príklad glosára",
"GlossDiv": {
"title": "S",
"GlossList": {
"GlossEntry": {
"ID": "SGML",
"SortAs": "SGML",
"GlossTerm": "Štandardný zjednodušený značkovací jazyk",
"Acronym": "SGML",
"Abbrev": "ISO 8879:1986",
"GlossDef": {
"para": "Meta-značkovací jazyk, ktorý sa používa na vytváranie značkovacích jazykov, ako je DocBook.",
"GlossSeeAlso": ["GML", "XML"]
},
"GlossSee": "značkovanie"
}
}
}
}
}
Potom vytvoríme jednoduchý konverzný skript a uložíme ho pod názvom json2yaml.py. Tento skript importuje oba moduly — YAML a JSON Python, načíta súbor JSON zadaný užívateľom, vykoná konverziu a zapíše údaje do súboru 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()
Uložte tento skript do systémovej cesty a spúšťajte ho podľa potreby:
$ ~/bin/json2yaml.py example.json
3. Parsujte veľa a často
Niekedy je užitočné na problém pozrieť sa z iného uhla. Ak máte ťažkosti predstaviť si vzťahy medzi údajmi v YAML, môžete ich dočasne pretransformovať na niečo zrozumiteľnejšie.
Napríklad, ak sa vám ľahšie pracuje so slovníkovými zoznamami alebo s JSON, môžete YAML previesť na JSON iba dvoma príkazmi v interaktívnej konzole Python. Predpokladajme, že máte YAML súbor mydata.yaml, takto to bude vyzerať:
$ 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': 'Dobrý článok. Mohlo by to byť lepšie.'}
Na túto tému nájdete množstvo ďalších príkladov. Okrem toho existuje množstvo online konvertorov a lokálnych parserov. Takže sa nebojte preformátovať údaje, keď vidíte, že sú len nezrozumiteľnou zmesou.
4. Čítajte špecifikácie
Keď sa po dlhom čase vraciate k YAML, je dobré navštíviť a prečítať si špecifikácie. Ak máte ťažkosti s YAML, ale na špecifikácie ste sa ešte nedostali, je čas túto situáciu napraviť. Špecifikácie sú prekvapivo ľahko napísané a požiadavky na syntax sú ilustrované mnohými príkladmi v .
5. Falošné konfigurácie
Pri písaní knihy alebo článku je vždy užitočné najprv načrtnúť predbežný plán, aspoň vo forme obsahu. Rovnako je to aj s YAML. Pravdepodobne máte predstavu o tom, aké údaje je potrebné zapísať do súboru YAML, ale nie ste si celkom istí, ako ich prepojiť navzájom. Preto predtým, ako začnete vytvárať YAML, nakreslite pseudokonfiguráciu.
Pseudokonfigurácia je podobná pseudokódu, kde sa nemusíte zaoberať štruktúrou alebo odsadením, vzťahmi „rodič-potomek“, dedičstvom a vnorením. Tak je to aj tu: kreslíte iterácie údajov tak, ako sa vám objavujú v hlave.
Pseudokonfigurácia s uvedením programátorov (Martin a Tabitha) a ich zručností (programovacie jazyky: Python, Perl, Pascal a Lisp, Fortran, Erlang, príslušne).
Keď nakreslíte pseudokonfiguráciu na papieri, dôkladne ju analyzujte a ak je všetko v poriadku, spracujte ju do platného súboru YAML.
6. Dilema „tabulátor alebo medzery“
Budete musieť vyriešiť dilemu . Nie v globálnom zmysle, ale len na úrovni vašej organizácie, alebo aspoň projektu. Nezáleží na tom, či sa pri tom použije post-procesovanie skriptom sed, nastavenie textových editorov na strojoch programátorov alebo hromadné odoberanie potvrdení o prísnom dodržiavaní pokynov lintra pod hrozbou prepustenia, ale všetci členovia vášho tímu, ktorí sa nejakým spôsobom dotýkajú YAML, musia bezpodmienečne používať len medzery (podľa toho, čo vyžaduje špecifikácia YAML).
V akomkoľvek normálnom textovom editore môžete nastaviť automatickú výmenu tabulácie na zadaný počet medzier, preto sa nemusíte obávať vzbury prívržencov klávesy Tab môžete sa báť.
Ako dobre je každému nenávistníkovi YAML známe, na obrazovke nie je vidieť rozdiel medzi tabulátorom a medzerami. A keď niečo nie je vidieť, o tom sa väčšinou pamätá na poslednú chvíľu, po tom, čo sa prešlo, skontrolovalo a odstránilo všetky ostatné možné problémy. Hodina času strávená hľadaním zlého tabulátora alebo bloku medzier jednoducho volá po tom, že musíte naliehavo vytvoriť politiku používania toho alebo iného a potom realizovať tvrdú kontrolu jej dodržiavania (napríklad cez Git hook pre povinné prechod cez linter).
7. Radšej menej a lepšie (alebo viac – to je menej)
Niektorí ľudia radi píšu v YAML, pretože zdôrazňuje štruktúru. Pri tom aktívne používajú odsadenia, aby vyznačili bloky údajov. Je to taký svojrázny podvod na napodobenie značkovacích jazykov, v ktorých sú použité explicitné oddeľovače.
Tu je príklad takejto štruktúrovanosti z :
# Employee records
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
Niekomu tento prístup pomáha ujasniť si štruktúru YAML, iných naopak rozčuľuje množstvom zbytočných, podľa ich názoru, odsadení.
Ale ak ste vlastníkom YAML dokumentu a zodpovedáte za jeho údržbu, tak iba vy musíte určovať, ako používať odsadenia. Ak vás rozčuľujú veľké odsadenia, zmenšite ich na minimum, ktoré je možné podľa špecifikácie YAML. Napríklad, vyššie uvedený súbor z dokumentácie Ansible bez akýchkoľvek strát možno prepísať takto:
---
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
8. Používajte šablóny
Ak pri vypĺňaní súboru YAML neustále opakujete tie isté chyby, má zmysel vložiť do neho šablónu vo forme komentára. Potom nabudúce môžete jednoducho skopírovať túto šablónu a zapísať do nej reálne údaje, napríklad:
---
# - <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. Použite niečo iné
Ak vás aplikácia nedrží pevne v hrsti, možno by ste mali prejsť na iný formát. Postupom času môžu konfiguračné súbory presiahnuť seba a je lepšie previesť ich na jednoduché skripty v Lua alebo Pythone.
YAML je skvelá vec, ktorú mnohí majú radi pre minimalizmus a jednoduchosť, ale nie je to jediný nástroj vo vašom arzenáli. Takže niekedy sa mu možno vzdať. Pre YAML je ľahké nájsť knižnice na spracovanie, takže ak navrhnete pohodlné možnosti migrácie, vaši používatelia si bez bolesti zvyknú na takýto odchod.
Ak však bez YAML nemôžete obísť, tak si osvojte týchto 10 rád a navždy porazte svoju averziu voči YAML!
Zdroj: habr.com
