🥇10 sammu YAML-i zenini

Me kõik armastame Ansible'i, kuid Ansible on YAML. Konfiguratsioonifailide jaoks on mitmeid vormate: väärtuste loendid, paarid "parameeter-väärtus", INI-failid, YAML, JSON, XML ja paljud teised. Kuid mitmel põhjusel peetakse YAML-i tihti kõige keerulisemaks. Eriti, vaatamata selle värskendavale minimalismile ja muljetavaldavatele võimalustele hierarhiliste väärtustega töötamiseks, võib YAML-i süntaks olla pikaajaline, andes tunde, et see kuidagi ei sobi kokku Pythoniga.

Kui YAML teid ärritab, siis saate - ja peate! - astuma järgmised 10 sammu, et vähendada oma ärritust talutavale tasemele ja õppida YAML-i armastama. Nagu tõelisele nimekirjale kohane, nummerdame meie soovitused nullist, mediteerimise ja vaimsete praktikate võite lisada vastavalt soovile 😉

0. Sundige oma redigeerijat töötama

Pole tähtis, milline tekstiredaktor teil on - kindlasti on sellele olemas vähemalt üks plugin YAML-i töötlemiseks. Kui teil seda ei ole, leidke ja installige see viivitamatult. Otsimisele ja seadistamisele kulutatud aeg tasub end ära iga kord, kui peate YAML-i redigeerima.

Näiteks redigeerija Atom toetab YAML-i vaikekohaselt, kuid GNU Emacsi jaoks peate installima täiendavad paketid, näiteks yaml-mode.

Emacs YAML-režiimis ja tühikute kuvamisega.

Kui teie lemmikredaktoril ei ole YAML-i režiimi, saab osa probleemidest lahendada seadete kohandamisega. Näiteks GNOME'i vaikereeditor Gedit ei oma YAML-i režiimi, kuid toetab vaikimisi YAML-i süntaksi esiletõstmist ja võimaldab tühikute töötlemist kohandada:

Tühikute seadistamine Geditis.

Ja Geditile mõeldud plugin drawspaces näitab tühikuid punktidena, eemaldades segaduse sissetõmbe tasemetest.

Teisisõnu, kulutage aega oma lemmikredaktori uurimisele. Uurige, mida teie redaktor või selle arendajate kogukond pakub YAML-i töötlemiseks ja kasutage neid võimalusi. Te ei kahetse seda.

1. Kasutage linte (linter)

Ideaalis kasutavad programmeerimiskeeled ja märgistuskeeled ettearvatavat süntaksit. Arvutid saavad ettearvatavusega väga hästi hakkama, seega sündis juba 1978. aastal linte kontseptsioon. linterit. Kui see on 40 aasta jooksul teid mööda läinud ja te ei kasuta endiselt YAML-i linterit, siis on viimane aeg proovida yamllint'i.

Installi yamllint seda saab installida Linuxi vaikimenüüst. Näiteks, Red Hat Enterprise Linux 8 või Fedora see tehakse nii:

$ sudo dnf install yamllint

Seejärel käivitage lihtsalt yamllint, edastades sellele kontrollimiseks YAML-faili. Nii see välja näeb, kui edastate linterile faili, mis sisaldab viga:

$ yamllint errorprone.yaml
errorprone.yaml
23:10     viga    süntaksiviga: siinse väärtuste määramine pole lubatud
23:11     viga    lõpp-tühikud  (trailing-spaces)

Numbrid vasakul ei tähenda aega, vaid vea koordinaate: rea ja veeru numbri. Vea kirjeldus ei pruugi teile midagi öelda, kuid täpselt teate, kus see asub. Vaadake selle koha peale koodis ja tõenäoliselt on kõik selge.

Kui yamllint ei leia failist vigu, ei kuvata ekraanile midagi. Kui teid hirmutab selline vaikus ja soovite natuke rohkem tagasisidet, siis võite linterit käivitada tingimusliku käsuga echo kahekordse ampersand'i (&&) kaudu, nii:

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

POSIX-is kehtib, et kahekordne ampersand aktiveerub ainult siis, kui eelnev käsk tagastab 0. Ja yamllint tagastab täpselt leitud vigade arvu, seega toimib kogu see tingimuslik konstruktsioon.

2. Kirjutage Pythonis, mitte YAML-is

Kui YAML tõeliselt ärritab, kirjutage seda lihtsalt mitte, sõnasõnaliselt. Juhtub, et YAML on ainus formaat, mida rakendus toetab. Kuid isegi siis ei ole tingimata vajalik YAML-faili loomine. Kirjutage seda, mis teile meeldib, ja konverteerige see hiljem. Näiteks Pythonile on olemas suurepärane teek pyyaml ja tervelt kaks konverteerimise meetodit: automaatne konverteerimine ja skriptide kaudu konverteerimine.

Automaatne konverteerimine

Selle meetodi jaoks on andmefail samal ajal ka Python-i skript, mis genereerib YAML-i. See lähenemine sobib kõige paremini väikeste andmekogumite jaoks. Te kirjutate lihtsalt JSON-andmed Python-i muutuja, eeldades seda import-direktiiviga ja faili lõppu lisate kolm rida väljundi rakendamiseks.

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

Seejärel käivitage see fail Pythonis ja väljundiks on fail 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ärgistuskeel, mida kasutatakse märkistuskeelte loomiseks, nagu DocBook.
		GlossSee: märkistus
		GlossTerm: Standardiseeritud Üldine Märgistuskeel
		ID: SGML
		SortAs: SGML
	title: S
  title: näidis glossarium

See on täiesti korrektne YAML, kuid yamllint annab hoiatusi, et see ei alga —. Seda saab kergesti käsitsi parandada või väikeseid muudatusi teha Python-i skriptis.

Konverteerimine skriptide kaudu

Sell juhul kirjutame esmalt JSON-is ja seejärel käivitame eraldi Python-skripti, mis tagastab YAML-i. See meetod on eelmisest paremini skaleeritav, kuna konvertimine on eraldatud andmetest.

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

{
	"glossary": {
	  "title": "näidis sõnastik",
	  "GlossDiv": {
		"title": "S",
		"GlossList": {
		  "GlossEntry": {
			"ID": "SGML",
			"SortAs": "SGML",
			"GlossTerm": "Standardiseeritud Üldine Markup Keel",
			"Acronym": "SGML",
			"Abbrev": "ISO 8879:1986",
			"GlossDef": {
			  "para": "Meta-markup keel, mida kasutatakse märgenduskeelte, näiteks DocBook, loomiseks.",
			  "GlossSeeAlso": ["GML", "XML"]
			  },
			"GlossSee": "markup"
			}
		  }
		}
	  }
	}

Seejärel loome lihtsa konverteerimis-skripti ja salvestame selle nimega json2yaml.py. See skript impordib mõlemad moodulid - YAML ja JSON Pythonis ning laadib kasutaja määratud JSON-faili, viib läbi konverteerimise ja kirjutab andmed failiks 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 teele ja käivita seda vastavalt vajadusele:

$ ~/bin/json2yaml.py example.json

3. Parsige palju ja sageli

Mõnikord on probleemile hea vaadata teise nurga alt. Kui teil on raske näha andmete vahelisi seoseid YAML-is, võite need ajutiselt muuta millekski tuttavamaks.

Näiteks, kui Teile meeldivad sõnalist nimekirjad või JSON, siis saab YAML-i konverteerida JSON-iks vaid kahe käsu abil Python-i interaktiivses konsoolis. Oletame, et Teie YAML-fail on mydata.yaml, siis näeb see välja järgmiselt:

$ 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': 'Hea artikkel. Saaks paremini.'}

Selle kohta on saadaval suur hulk teisi näiteid. Samuti on internetis palju online-konvertereid ja kohalikke parsereid. Seega ärge kartke andmete ümbervormimist, kui näete neis vaid arusaamatut segu.

4. Loe spetsiifikatsioone

YAML-i juurde tagasi tulles on kasulik külastada yaml.org ja tutvuda spetsiifikatsioonidega. Kui teil on YAML-i osas raskusi, kuid spetsiifitseeritud käed ei ole veel ulatunud, siis on aeg see olukord parandada. Spetsiifikatsioonid on üllatavalt lihtsalt koostatud ja süntaksinõuded on illustreeritud suure hulga näidetega Peatükis 6.

5. Pseudokonfiguratsioonid

Raamatu või artikli kirjutamisel on alati kasulik kõigepealt koostada esialgne plaan, vähemalt sisukorra kujul. Sama kehtib ka YAML-i puhul. Tõenäoliselt teate, millised andmed tuleb YAML-faili salvestada, kuid ei tea täpselt, kuidas nad omavahel seonduda. Seetõttu, enne kui hakata YAML-i sepistama, joonistage pseudokonfiguratsioon.

Pseudokonfiguratsioon sarnaneb pseudokoodiga, kus ei pea muretsema struktuuri või sisestuste, vanemate ja lasteseoste, pärimise ja pesakonna üle. Nii on ka siin: joonistate andmete iteratsioonid, kui need Teie mõtetesse jsse tulevad.

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

Pärast pseudokonfiguratsiooni joonistamist paberile analüüsige seda põhjalikult ja kui kõik on korras, vormistage see korrektseks YAML-failiks.

6. Dilemma "tabulatsioon või tühikud"

Te peate lahendama dilemmat "tabulatsioon või tühikud?". Mitte globaalsetes mõtetes, vaid ainult teie organisatsiooni või vähemalt projekti tasandil. Pole tähtis, kas selleks kasutatakse jälgimiskirju, seadistatakse tekstiredaktoreid programmeerijate masinates või nõutakse striktselt kinnitusi linteri juhiste järgimise kohta, kuid kõik teie tiimi liikmed, kes puutuvad YAML-iga kokku, peavad kindlasti kasutama ainult tühikuid (nagu YAML-i spetsifikatsioon nõuab).

Igas normaalses tekstiredaktoris on võimalik seadistada automaatne tabulatsiooni asendamine määratud tühikute arvuga, seega ei pea kartma tabulatsiooni toetajate ülestõusu. Tab nupu suhtes.

Kuidas igasugustele YAML-i vaenuvägedele on hästi teada, ekraanil ei ole vahet tabulatsiooni ja tühikute vahel. Ja kui midagi ei ole nähtav, siis tavaliselt meenutatakse seda viimases järjekorras, pärast seda, kui on vaadatud, kontrollitud ja kõrvaldatud kõik muud võimalikud probleemid. Tund, mis on raisatud vale tabulatsiooni või tühikubloki leidmiseks, lihtsalt karjub, et teil on kiiresti vaja luua poliitika kas selle või teise kasutamiseks ja seejärel rakendada raudbetooni kontrolli selle järgimise üle (näiteks läbi Git-huki, et sundida linteri kasutamist).

7. Vähem on rohkem (või rohkem on vähem)

Mõned inimesed eelistavad kirjutada YAML-is, kuna see toob esile struktuuri. Nad kasutavad aktiivselt sissetõmbeid, et eristada andmeplokke. See on omamoodi petmine markeerimiskeelte jäljendamiseks, kus kasutatakse silmnähtavaid eraldajaid.

Siin on näide sellisest struktureerituse näitest 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 see variant mõelda YAML-i struktuurile, teisi aga häirib see liigsete, nende arvates, sissetõmmete tõttu.

Kui aga te olete YAML-dokumendi omanik ja vastutate selle hoolduse eest, siis ainult teie peate määrama, kuidas sissetõmbeid kasutada. Kui suured sissetõmbed teid häirivad, vähendage need miinimumini, mis on vastavalt YAML-i spetsifikatsioonile võimalik. Näiteks võib eespool mainitud faili Ansible'i dokumentatsioonist ilma igasuguste kaotusteta ümber kirjutada 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 malle

Kui täidate YAML-faili ja teete pidevalt samu vigu, on mõistlik lisada sinna malli kommentaarina. Sel juhul saab järgmine kord lihtsalt selle malli 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 kinni, siis võib-olla tasub YAMLi asemel valida mõni teine formaat. Aja jooksul võivad konfiguratsioonifailid end ületada ja siis on parem need muuta lihtsateks skriptideks Lua-s või Pythonis.

YAML on suurepärane asi, mida paljud hindavad minimalismi ja lihtsuse tõttu, kuid see pole ainus tööriist teie arsenalis. Nii et mõnikord võib sellest loobuda. YAMLi jaoks on lihtne leida parsimise teeke, seega kui pakute mugavaid migreerimisvõimalusi, suudavad teie kasutajad sellist loobumist suhteliselt valutult taluda.

Kuid kui YAMList on täiesti võimatu loobuda, siis võtke need 10 nõuannet kasutusele ja võitke oma vastumeelsus YAMLi vastu kord ja kõik!

Allikas: habr.com