🥇10 sammu YAML-i zenini

Me kõik armastame Ansible't, kuid Ansible on YAML. Konfiguratsioonifailide jaoks on olemas palju formaate: väärtuste loendid, paarid „parameeter-väärtus”, INI-failid, YAML, JSON, XML ja palju teisi. Kuid mitmel põhjusel peetakse YAML-i sageli eriti keeruliseks. Eelkõige, hoolimata selle värskendavast minimalismist ja muljetavaldavatest võimalustest hierarhiliste väärtustega töötamisel, võib YAML-i süntaks oma Pythonilaadse lähenemise tõttu taandele olla tülikas.

Kui YAML ajab teid närvi, saate – ja peaksite! – astuma järgmised 10 sammu, et oma ärritust talutavasse tasemesse alandada ja YAML-i armastama hakata. Nagu tõelisele loetelule kohane, numbreerime meie kümme nõuannet nullist, mediteerimise ja vaimsete praktikate lisamine on vabatahtlik 😉

0. Sundige oma redaktorit töötama

Ei ole tähtis, milline tekstiredaktor teil on – tõenäoliselt on sellele vähemalt üks plugin YAML-i töötluseks. Kui teil sellist ei ole, leidke ja installige see kohe. Aeg, mis kulub otsimisele ja seadistamisele, tasub end mitmekordselt ära iga kord, kui peate YAML-i redigeerima.

Näiteks toimetaja Atom toetab YAML-i vaikimisi, kuid GNU Emacs'i jaoks tuleb installida täiendavad paketid, näiteks yaml-mode.

Emacsi YAML-režiimis ja tühikute kuvamisel.

Kui teie lemmikredaktoris ei ole YAML-režiimi, saab osa probleemidest lahendada seadistustega töötades. Näiteks GNOME'i vaikimisi tekstiredaktor Gedit ei toeta YAML-režiimi, kuid tavalised YAML-i süntaksi esiletõstmine ja tühikute seadistamine on seda võimaldanud:

Geditis tühikute seadistamine.

Ja plugin drawspaces Geditile kuvab tühikud punktidena, kõrvaldades ebaselgused taande tasemete osas.

Teisisõnu, võtke aega oma lemmikredaktori uurimiseks. Uurige, mida see ise või selle arendusüritus pakub YAML-iga töötamiseks, ja kasutage neid võimalusi. Te ei kahetse seda.

1. Kasutage lintrit

Ideaalis kasutavad programmeerimiskeeled ja märgistuskeeled etteennustatavat süntaksit. Arvutid saavad etteennustatavuse hästi hakkama, seetõttu tekkis juba 1978. aastal kontseptsioon lintrist. Kui see 40 aasta jooksul teid mööda on läinud ja te siiani YAML-lintrit ei kasuta, on Õige aeg proovida yamllinti.

Paigaldada yamllint seda saab kasutada Linuxi vaikimisi pakihalduri kaudu. Näiteks Red Hat Enterprise Linux 8 või Fedora see tehakse nii:

$ sudo dnf install yamllint

K seejärel lihtsalt käivitate yamllint, edastades talle veekontrollimiseks YAML-faili. Näete, milline see välja näeb, kui edastate lintimisele vale faili:

$ yamllint errorprone.yaml
errorprone.yaml
23:10     viga    süntaksiviga: kaardistamise väärtused ei ole siin lubatud
23:11     viga    lisaruumid  (trailing-spaces)

Vasakul asuvad numbrid ei ole ajad, vaid vea koordinaadid: rida ja veeru number. Veakirjeldus võib teile mitte midagi öelda, kuid teate täpselt, kus see asub. Vaadake lihtsalt seda kohta koodis ja tõenäoliselt on kõik selge.

Kui yamllint ei leia failis vigu, ei kuvata ekraanile midagi. Kui selline vaikimine hirmutab ja soovite natuke rohkem tagasisidet, siis saate lintimist käivitada tingimusliku käsklusega echo topelt-amperandiga (&&), nii:

$ yamllint perfect.yaml && echo "OK"
OK

POSIX-is töötab topelt-amperand ainult siis, kui eelnev käsk tagastab 0. Ja yamllint tagastab just leitud vigade arvu, seetõttu see tingimuslik konstruktsioon töötab.

2. Kirjutage Pythonis, mitte YAML-is

Kui YAML tõeliselt häirib, ärge kirjutage sellel, sõnasõnaliselt. Olukordades, kus YAML on ainus formaat, mis rakenduse poolt tuntud, ei pea te sellegipoolest YAML-faili looma. Kirjutage selles, mis teile meeldib, ja seejärel konverteerige. Näiteks Pythonile on suurepärane teek pyyaml ja kaks viisi konverteerimiseks: automaatne konverteerimine ja konverteerimine skriptide kaudu.

Automaatne konverteerimine

Sel juhul on andmefail ühtlasi ka Python-skript, mis genereerib YAML. See meetod sobib kõige paremini väikeste andmehulkade jaoks. Kirjutate lihtsalt JSON-andmed Pythonis muutujasse, eeldate seda import-märgisega ning lisate faili lõppu kolm rida väljundi teostamiseks.

#!/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

Käivitame nüüd selle faili Pythonis ja väljundiks saame faili output.yaml:

$ python3 ./example.json
$ cat output.yaml
glossary:
  GlossDiv:
	GlossList:
	  GlossEntry:
		Abbrev: ISO 8879:1986
		Acronym: SGML
		GlossDef:
		  GlossSeeAlso: [GML, XML]
		  para: meta-märgistus keel, mida kasutatakse selliste märgistuskeelte loomiseks nagu DocBook.
		GlossSee: märgistus
		GlossTerm: Üldine standardiseeritud märgistuskeel
		ID: SGML
		SortAs: SGML
	title: S
  title: näidis sõnastik

See on täiesti korrektne YAML, kuid yamllint annab hoiatuse, et see ei alga -. Mis siis, seda saab kergesti käsitsi parandada või Python-skripti veidi kohandada.

Skriptide kaudu konverteerimine

Selles olukorras kirjutame esmalt JSON-is ja seejärel käivitame konverterina eraldi Python-skripti, mis väljastab YAML-i. See meetod on võrreldes eelneva meetodiga paremini skaleeritav, kuna andmete konverteerimine on eraldatud.

Alguses loome JSON-faili example.json; näiteks võite selle võtta aadressilt json.org:

{
	"glossary": {
	  "title": "näidisglossaar",
	  "GlossDiv": {
		"title": "S",
		"GlossList": {
		  "GlossEntry": {
			"ID": "SGML",
			"SortAs": "SGML",
			"GlossTerm": "Standardiseeritud üldine märgistamise keel",
			"Acronym": "SGML",
			"Abbrev": "ISO 8879:1986",
			"GlossDef": {
			  "para": "Metamärgistuskeel, mida kasutatakse selliste märgistamiskeelte loomiseks nagu DocBook.",
			  "GlossSeeAlso": ["GML", "XML"]
			  },
			"GlossSee": "märgistamine"
			}
		  }
		}
	  }
	}

Seejärel loome lihtsa konverteerimis-skripti ja salvestame selle nimega json2yaml.py. See skript importib mõlemad moodulid — YAML ja JSON Pythonis ning laadib kasutaja määratud JSON-faili, viib läbi konverteerimise ja kirjutab andmed faili 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()

Salvesta see skript süsteemi teekonda ja käivita vastavalt vajadusele:

$ ~/bin/json2yaml.py example.json

3. Parsige tihti ja palju

Mõnikord on probleemile hea vaadata teisest küljest. Kui on raske ette kujutada andmete seoseid YAML-is, võite need ajutiselt konverteerida millegi tuttavama vastu.

Näiteks, kui teile meeldib töötada sõnastike loendite või JSON-iga, siis saab YAML-i muuta JSON-iks vaid kahe käsuga Python'i interaktiivses shell'is. Oletame, et teil on YAML-fail mydata.yaml, nii et vaadake, kuidas see välja näeb:

$ 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', 'city': 'Brooklyn', 'state': 'Wellington', 'postal': 6021, 'country': 'NZ'}}, 'words': 938, 'comments': 'Hea artikkel. Võiks olla parem.'}

Selle teema kohta on saadaval palju muid näiteid. Lisaks on olemas palju veebipõhiseid konvertereid ja kohalikke parsereid. Seega ärge kartke andmete ümberformaatimist, kui näete neid vaid segadusena.

4. Loe spetsifikatsioone

Kui naasete pärast pikka pausi YAML-i juurde, on kasulik külastada yaml.org ja lugeda spetsifikatsioone. Kui teil on YAML-iga raskusi, kuid spetsifikatsioonideni ei ole jõudnud, siis on aeg see olukord parandada. Spetsifikatsioonid on üllatavalt selgelt kirjutatud ja süntaksi nõudeid illustreeritakse hulga näidetega Peatükis 6.

5. Pseudokonfiguratsioonid

Raamatute või artiklite kirjutamisel on alati kasulik kõigepealt koostada eelnev plaan, vähemalt sisukorra kujul. Nii on ka YAML-i puhul. Tõenäoliselt kujutate ette, millised andmed tuleb YAML-faili salvestada, kuid ei saa täpselt aru, kuidas neid omavahel seostada. Seetõttu joonistage YAML-i koostamise enne välja pseudokonfiguratsioon.

Pseudokonfiguratsioon sarnaneb pseudokoodiga, kus ei pea muretsema struktuuri või sisu, «vanem-laps» suhete, pärimise ja pesastatuse üle. Sel juhul joonistate andmete iteratsioonid nii, nagu need teie peas ilmnevad.

Pseudokonfiguratsioon, kus on loetletud programmeerijad (Martin ja Tabitha) ja nende oskused (programmeerimiskeeled: Python, Perl, Pascal ja Lisp, Fortran, Erlang, vastavalt).

Pseudokonfiguratsiooni paberile joonistades analüüsige seda hoolikalt ja kui kõik on korras, vormistage see kehtiva YAML-failina.

6. Dilemma «tühikut või tabulatsiooni»

Te peate otsustama dilemmas «tühikut või tabulatsiooni?». Mitte globaalses mõttes, vaid ainult teie organisatsiooni tasandil või vähemalt projekti tasandil. Ei ole oluline, kas selleks kasutatakse sed-skripti, programmide tekstiredaktorite seadistamist või ainult selleks, et kasutada nõuete järgimise rõhutamiseks ultimatume, et kõik teie meeskonna liikmed, kes tegelevad YAML-iga, peavad kindlasti kasutama ainult tühikuid (nagu YAML-i spetsifikatsioon nõuab).

Igas normaalses tekstiredaktoris saab seadistada automaatse tabulatsiooni asendamise määratud arvu tühikutega, seega ei ole vaja karta kapriisse tabulatsiooni pooldajaid. Tab pole millegi pärast muretseda.

Nagu iga YAML-i vihkaja hästi teab, ei paista ekraanil tabulatsiooni ja tühikute vahel vahet. Ja kui midagi ei paista, meenutatakse seda tavaliselt viimases järjekorras, peale seda, kui on välja peetud, kontrollitud ja kõrvaldatud kõik teised võimalikud probleemid. Tunni aeg, mis kulutatakse vale tabulatsiooni või tühikute ploki leidmiseks, kutsub hädasti esile vajalikkuse luua poliitika selle kasutamise osas ning seejärel rakendada selle järgimise stoilist kontrolli (nt Git-hook'i kaudu, et sundida linters läbi vaatama).

7. Parem vähem, aga paremini (või rohkem – see on vähem)

Mõned inimesed armastavad kirjutada YAML-is, kuna see toob esile struktuuri. Nad kasutavad aktiivselt sisestusi, et eristada andmebloke. See on omamoodi petmine, et jäljendada, nagu markeerimiskeel, kus kasutatakse selgeid eraldajaid.

Siin on sellise struktuursuse näide Ansible'i dokumentatsioonist:

# Employee records
-  martin:
        name: Martin D'vloper
        job: Developer
        skills:
            - python
            - perl
            - pascal
-  tabitha:
        name: Tabitha Bitumen
        job: Developer
        skills:
            - lisp
            - fortran
            - erlang

Mõnele inimesele aitab selline variandistruktuur YAML-i peas paremini seada, teisi aga ärritab see liigsete, nende arvates, sisestustega.

Kuid kui olete YAML-dokumendi omanik ja vastutate selle üle, siis teie ja ainult teie peate määrama, kuidas kasutada sisestusi. Kui suured sisestused teid ärritavad, siis viige need miinimumini, mis on võimalikult väike YAML-i spetsifikatsiooni kohaselt. Näiteks võib ülaltoodud fail Ansible'i dokumentatsioonist kirjutada ümber järgmiselt:

---
- martin:
   name: Martin D'vloper
   job: Developer
   skills:
   - python
   - perl
   - pascal
- tabitha:
   name: Tabitha Bitumen
   job: Developer
   skills:
   - lisp
   - fortran
   - erlang

8. Kasutage mallide

Kui täidate YAML-faili ja kordate pidevalt samu vigu, on mõistlik lisada sinna malli näidis kommentaarina. Siis järgmine kord saate lihtsalt see mall kopeerida ja sinna reaalsed andmed sisestada, näiteks:

---
# - <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. Kasutage midagi muud

Kui rakendus ei hoia teid enda küljes, siis võib-olla tasub YAML asendada mõne teise formaadiga. Aja jooksul võivad konfiguratsioonifailid muutuda ja siis on parem need lihtsalt lihtsateks Lua või Python skriptideks ümber kujundada.

YAML on suurepärane asi, mida paljud hindavad minimalistlikkuse ja lihtsuse tõttu, kuid see pole kaugeltki ainus tööriist teie arsenalis. Seega mõnikord võib sellest loobuda. YAML-i jaoks on lihtne leida parsimisraamatukogusid, seega kui pakute mugavaid migratsioonivõimalusi, taluvad teie kasutajad selle loobumist suhteliselt valulikult.

Kuid kui YAML-ist ei pääse, siis võtke kasutusele need 10 nõuannet ja võitke oma vastumeelsus YAML-i vastu kord ja kõik!

Allikas: habr.com