Мы ўсе любім Ansible, але Ansible - гэта YAML. Для канфігурацыйных файлаў існуе маса фарматаў: спісы значэнняў, пары "параметр-значэнне", INI-файлы, YAML, JSON, XML і мноства іншых. Аднак па некалькіх прычынах з усіх іх YAML часта лічыцца асабліва цяжкім. У прыватнасці, нягледзячы на яго асвяжальны мінімалізм і ўражальныя магчымасці для працы з іерархічнымі значэннямі, сінтаксіс YAML можа раздражняць сваім Python-вобразным падыходам да водступаў.
Калі вас раз'юшвае YAML, вы можаце - і павінны! – зрабіць 10 наступных крокаў, каб знізіць сваё раздражненне да прымальнага ўзроўню і пакахаць YAML. Як і пакладзена сапраўднаму спісу, наша дзясятка парад будзе нумаравацца з нуля, медытацыю і духоўныя практыкі дадаем па жаданні 😉
0. Прымусьце ваш рэдактар працаваць
Усё роўна, які ў вас тэкставы рэдактар – для яго напэўна існуе хаця б адна плягін для працы з YAML. Калі ў вас такога няма, неадкладна знайдзіце і ўсталюеце. Выдаткаваны на пошук і наладу час будзе шматкроць акупляцца кожны раз, калі вам давядзецца рэдагаваць YAML.
Напрыклад, рэдактар падтрымлівае YAML па змаўчанні, а вось для GNU Emacs давядзецца ўсталяваць дадатковыя пакеты, напрыклад, .
Emacs у рэжыме YAML і адлюстравання прабелаў.
Калі ў вашым каханым рэдактары няма рэжыму YAML, то частка праблем можна вырашыць, папрацаваўшы з наладамі. Напрыклад, штатны для GNOME тэкставы рэдактар Gedit не мае рэжыму YAML, але па змаўчанні падсвятляе сінтаксіс YAML і дазваляе наладзіць працу з водступамі:
Настройка водступаў у Gedit.
А плягін для Gedit адлюстроўвае прабелы ў выглядзе кропак, ухіляючы невыразнасці з узроўнямі водступу.
Іншымі словамі, выдаткуйце час на вывучэнне свайго каханага рэдактара. Высветліце, што ен сам ці яго супольнасць распрацоўкі прапануюць для працы з YAML, і выкарыстоўвайце гэтыя магчымасці. Вы сапраўды аб гэтым не пашкадуеце.
1. Выкарыстоўвайце лінтэр (linter)
У ідэале мовы праграмавання і мовы разметкі выкарыстоўваюць прадказальны сінтаксіс. Кампутары добра спраўляюцца з прадказальнасцю, таму яшчэ ў 1978 году ўзнікла канцэпцыя. . Калі за 40 гадоў свайго існавання яна прайшла міма вас і вы да гэтага часу не карыстаецеся YAML-лінтарам, той самы час паспрабаваць yamllint.
ўсталяваць можна з дапамогай штатнага мэнэджара пакетаў Linux. Напрыклад, у 8 або гэта робіцца так:
$ sudo dnf install yamllint
Затым вы проста запускаеце yamllint, перадаючы яму YAML-файл для праверкі. Вось як гэта выглядае, калі перадаць лінтару файл з памылкай:
$ yamllint errorprone.yaml
errorprone.yaml
23:10 error syntax error: mapping values are not allowed here
23:11 error trailing spaces (trailing-spaces)
Лічбы злева - гэта не час, а каардынаты памылкі: нумар радка і слупка. Апісанне памылкі можа вам ні пра што не казаць, затое вы сапраўды ведаеце, дзе яна знаходзіцца. Проста паглядзіце на гэтае месца ў кодзе, і, хутчэй за ўсё, усё стане зразумела.
Калі yamllint не знаходзіць памылак у файле, на экран нічога не выводзіцца. Калі вас палохае такая цішыня і хочацца крыху больш зваротнай сувязі, то можна запускаць лінтэр з умоўнай камандай echo праз падвойны амперсанд (&&), вось так:
$ yamllint perfect.yaml && echo "OK"
OK
У POSIX падвойны амперсанд спрацоўвае тады і толькі тады, калі папярэдняя каманда вяртае 0. А yamllint як раз вяртае колькасць знойдзеных памылак, таму ўся гэтая ўмоўная канструкцыя і працуе.
2. Пішыце на Python, а не на YAML
Калі вас рэальна раз'юшвае YAML, проста не пішыце на ім, у літаральным сэнсе. Бывае, што YAML - гэта адзіны фармат, які ўспрымаецца дадаткам. Але і ў гэтым выпадку неабавязкова ствараць YAML-файл. Пішыце на тым, што вам падабаецца, а потым канвертуйце. Напрыклад, для Python ёсць выдатная бібліятэка і цэлых два спосабу канвертавання: самаканвертаванне і канвертаванне праз скрыпты.
Самаканвертаванне
У гэтым выпадку файл з дадзенымі заадно з'яўляецца і Python-скрыптам, які генеруе YAML. Гэты спосаб лепш за ўсё падыходзіць для невялікіх набораў даных. Вы проста пішыце JSON-дадзеныя ў зменную Python, папярэднічаеце гэта дырэктывай import, а ў канцы файла дадаеце тры радкі для рэалізацыі высновы.
#!/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
Цяпер запускаем гэты файл на Python-е і на выхадзе атрымліваем файл 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
Гэта абсалютна карэктны YAML, але yamllint выдасць папярэджанне, што ён не пачынаецца з -. Што ж, гэта можна лёгка паправіць уручную ці злёгку дапрацаваць Python-скрыпт.
Канвертаванне праз скрыпты
У гэтым выпадку спачатку пішам на JSON-е, а затым запускаем канвертар у выглядзе асобнага Python-скрыпту, які на вынахадзе дае YAML. У параўнанні з папярэднім гэты спосаб лепш маштабуецца, паколькі канвертаванне аддзелена дадзеных.
Для пачатку створым JSON-файл example.json, напрыклад, яго можна ўзяць на :
{
"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"
}
}
}
}
}
Затым створым просты скрыпт-канвертар і захаваем яго пад імем json2yaml.py. Гэты скрыпт імпартуе абодва модулі - YAML і JSON Python, а таксама загружае паказаны карыстальнікам файл JSON, выконвае канвертаванне і піша дадзеныя ў файл 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()
Захавайце гэты скрыпт у system path і запускайце па меры неабходнасці:
$ ~/bin/json2yaml.py example.json
3. Парсіце шмат і часта
Часам на праблему карысна зірнуць пад іншым кутом. Калі вам цяжка ўявіць узаемасувязі паміж дадзенымі ў YAML, можна часова пераўтварыць іх у нешта больш звыклае.
Напрыклад, калі вам зручна працаваць са слоўнікавымі спісамі або з JSON, то YAML можна пераўтварыць у JSON усяго дзвюма камандамі ў інтэрактыўнай абалонцы Python. Дапушчальны, у вас есць YAML-файл mydata.yaml, тады вось як гэта будзе выглядаць:
$ 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': 'Good article. Could be better.'}
На гэтую тэму можна знайсці шмат іншых прыкладаў. Акрамя таго, у наяўнасці мноства анлайн-канвертараў і лакальных парсераў. Так што не саромейцеся перафарматаваць дадзеныя, калі бачыце ў іх толькі незразумелую мешаніну.
4. Чытайце спякі
Вяртаючыся да YAML пасля доўгага перапынку, карысна зайсці на і перачытаць спецыфікацыі (спякі). Калі ў вас цяжкасці з YAML, але да спецыфікацыі рукі так і не дайшлі, то час гэтую сітуацыю выпраўляць. Спекі на здзіўленне лёгка напісаны, а патрабаванні да сінтаксісу ілюструюцца вялікай колькасцю прыкладаў у .
5. Псеўдаканфігі
Пры напісанні кнігі ці артыкулы заўсёды карысна спачатку накідаць папярэдні план, хаця б у выглядзе зместа. Гэтак жа і з YAML. Хутчэй за ўсё, вы ўяўляеце, якія дадзеныя трэба запісаць у файл YAML, але не вельмі разумееце, як звязаць іх сябар з сябрам. Таму перш чым ляпіць YAML, намалюйце псеўдаканфіг.
Псеўдаконфіг падобны на псеўдакод, дзе не трэба клапаціцца аб структуры або водступах, адносінах «бацька-нашчадак», атрыманні ў спадчыну і ўкладзенасці. Так і тут: вы малюеце ітэрацыі дадзеных па меры таго, як яны ўзнікаюць у вас у галаве.
Псеўдаканфіг з пералікам праграмістаў (Martin і Tabitha) і іх навыкаў (моў праграмавання: Python, Perl, Pascal і Lisp, Fortran, Erlang, адпаведна).
Намаляваўшы псеўдаконфіг на лісце паперы, уважліва прааналізуйце яго і, калі ўсё ў парадку, аформіце ў выглядзе валіднага YAML-файла.
6. Дылема "табуляцыя або прабелы"
Вам давядзецца вырашыць дылему . Не ў глабальным сэнсе, а толькі на ўзроўні вашай арганізацыі, ці хаця б праекта. Усё роўна, ці будзе пры гэтым выкарыстоўвацца пост-апрацоўка скрыптам sed, налада тэкставых рэдактараў на машынах праграмістаў ці ж пагалоўнае ўзяцце распісак аб строгім выкананні ўказанняў літара пад пагрозай звальнення, але ўсе чальцы вашай каманды, якія так ці інакш дакранаюцца YAML, у абавязковым парадку павінны выкарыстоўваць толькі прабелы (як таго патрабуе спецыфікацыя YAML).
У любым нармальным тэкставым рэдактары можна наладзіць аўтазамену табуляцыі на зададзеную колькасць прабелаў, таму бунту прыхільнікаў клавішы Таб можна не баяцца.
Як добра вядома кожнаму ненавісніку YAML, на экране не відаць розніцы паміж табуляцыяй і прабеламі. А калі чагосьці не відаць, пра гэта, як правіла, успамінаюць у апошнюю чаргу, пасля таго, як перабралі, праверылі і ўхілілі ўсе астатнія магчымыя праблемы. Гадзіна часу, забіты на пошук крывой табуляцыі або блока прабелаў, проста лямантуе аб тым, што вам над тэрмінова стварыць палітыку выкарыстання таго ці іншага, а затым рэалізаваць жалезабетонную праверку яе захавання (напрыклад, праз Git-хук для прымусовага прагону праз лінтэр).
7. Лепш менш ды лепш (ці больш - гэта менш)
Некаторыя людзі любяць пісаць на YAML, паколькі ён падкрэслівае структуру. Пры гэтым яны актыўна выкарыстоўваюць водступы, каб вылучаць блокі дадзеных. Гэта такое свайго роду жульніцтва для імітацыі моў разметкі, у якіх выкарыстоўваюцца відавочныя падзельнікі.
Вось прыклад такой структураванасці з :
# Employee records
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
Камусьці такі варыянт дапамагае раскласці ў галаве структуру YAML, іншых ён наадварот ятрыць масай непатрэбных, на іх погляд, водступаў.
Але калі вы з'яўляецеся ўладальнікам YAML-дакумента і адказваеце за яго суправаджэнне, то вы і толькі вы павінны вызначаць, як выкарыстоўваць водступы. Калі вас ятраць вялікія водступы, звядзіце іх да мінімуму, які толькі магчымы паводле спецыфікацыі YAML. Напрыклад, вышэйпрыведзены файл з дакументацыі Ansible без якіх бы там ні было страт можна перапісаць вось так:
---
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
8. Выкарыстоўвайце нарыхтоўкі
Калі пры запаўненні файла YAML вы ўвесь час паўтараеце адны і тыя ж памылкі, мае сэнс уставіць у яго шаблон-нарыхтоўку ў выглядзе каментара. Тады наступным разам можна будзе проста скапіяваць гэтую нарыхтоўку і ўпісаць туды рэальныя дадзеныя, напрыклад:
---
# - <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. Выкарыстоўвайце нешта іншае
Калі прыкладанне не трымае вас мёртвай хваткай, то, магчыма, варта змяніць YAML на іншы фармат. З часам канфігурацыйныя файлы могуць перарастаць сябе і тады лепш пераўтварыць іх у простыя скрыпты на Lua ці Python.
YAML - выдатная штука, якую многія любяць за мінімалізм і прастату, але гэта далёка не адзіны інструмент у вашым арсенале. Таму часам ад яго можна адмовіцца. Для YAML лёгка знайсці бібліятэкі парсінгу, таму, калі вы прапануеце зручныя варыянты міграцыі, вашы карыстальнікі адносна бязбольна перажывуць такую адмову.
Калі ж без YAML ніяк не абысціся, то вазьміце на ўзбраенне гэтыя 10 парад і пераможаце сваю непрыязнасць да YAML раз і назаўжды!
Крыніца: habr.com