10 стъпки към YAML дзен

Всички обичаме Ansible, но Ansible е YAML. Съществуват множество формати за конфигурационни файлове: списъци с стойности, двойки „параметър-стойност“, INI файлове, YAML, JSON, XML и много други. Обаче, по няколко причини, от всички тях YAML често се счита за особено труден. В частност, въпреки освежаващия си минимализъм и впечатляващите възможности за работа с йерархични стойности, синтаксисът на YAML може да бъде досаден с подхода си, наподобяващ Python, към отстъпите.

Ако YAML ви дразни, можете – и трябва! – да предприемете 10 стъпки, за да намалите раздразнението си до приемливо ниво и да заобичате YAML. Както е при всеки истински списък, нашата десетка съвети ще бъде номерирана от нула, медитацията и духовните практики добавяме по желание 😉

0. Накарайте редактора си да работи

Независимо какъв текстов редактор имате – със сигурност съществува поне един плъгин за работа с YAML. Ако нямате такъв, незабавно намерете и инсталирайте. Времето, прекарано в търсене и настройване, ще се изплати многократно всеки път, когато трябва да редактирате YAML.

Например, редакторът Atom поддържа YAML по подразбиране, но за GNU Emacs е необходимо да се инсталират допълнителни пакети, например, yaml-mode.

Emacs в режим YAML с визуализация на отстъпите.

Ако в любимия ви редактор няма YAML режим, част от проблемите могат да се решат чрез настройки. Например, стандартният текстов редактор Gedit за GNOME няма YAML режим, но по подразбиране подчертава синтаксиса на YAML и позволява да се настройват отстъпите:

Настройка на отстъпите в Gedit.

Плъгинът drawspaces за Gedit показва отстъпите като точки, премахвайки неяснотите с нивата на отстъпа.

С други думи, отделете време да се запознаете с любимия си редактор. Разберете какво предлага той самият или неговата разработваща общност за работа с YAML, и използвайте тези възможности. Определено няма да съжалявате.

1. Използвайте линтер (linter)

В идеалния случай езиците за програмиране и езиците за маркиране използват предсказуем синтаксис. Компютрите се справят добре с предсказуемостта, така че концепцията за линтерсе появи още през 1978 г. Ако през последните 40 години е минала покрай вас и все още не ползвате YAML линтер, то е най-доброто време да пробвате yamllint.

Инсталиране yamllint може с помощта на стандартния пакетен мениджър на Linux. Например, в Red Hat Enterprise Linux 8 или Fedora това се прави така:

$ sudo dnf install yamllint

След това просто стартирате yamllint, предавайки му YAML-файл за проверка. Ето как изглежда, ако подадете на линтера файл с грешка:

$ yamllint errorprone.yaml
errorprone.yaml
23:10     грешка    синтактична грешка: мапинг стойности не е позволен тук
23:11     грешка    остатъчни интервали  (trailing-spaces)

Числата вляво – това не е време, а координати на грешката: номер на реда и колона. Описанието на грешката може да не означава нищо, но определено знаете къде се намира. Просто погледнете на това място в кода и най-вероятно всичко ще стане ясно.

Когато yamllint не намери грешки във файла, на екрана не се извежда нищо. Ако тази тишина ви плаши и искате малко повече обратна връзка, можете да стартирате линтера с условна команда echo чрез двойни амперсанди (&&), ето как:

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

В POSIX двойната амперсанд работи само тогава, когато предишната команда връща 0. А yamllint точно връща броя на намерените грешки, затова цялата тази условна конструкция и работи.

2. Пишете на Python, а не на YAML

Ако наистина ви дразни YAML, просто не пишете на него, в буквалния смисъл. Понякога YAML е единственият формат, който приложението може да възприема. Но дори в този случай не е задължително да създавате YAML-файл. Пишете на това, което ви харесва, и след това конвертирайте. Например, за Python има отлична библиотека pyyaml и цели два начина за конвертиране: самоконвертиране и конвертиране с помощта на скриптове.

Самоконвертиране

В този случай файлът с данни е едновременно и 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: примерен глосар

Това е напълно коректен YAML, но yamllint ще издаде предупреждение, че не започва с —. Е, това може лесно да се поправи ръчно или малко да се доработи Python-скриптът.

Конвертиране чрез скриптове

В този случай първо пишем в JSON, а след това стартираме конвертора под формата на отделен Python скрипт, който на изхода дава YAML. В сравнение с предишния, този метод е по-добре мащабируем, тъй като конвертирането е отделено от данните.

За начало, нека създадем JSON файл example.json; например, можете да го вземете от json.org:

{
	"glossary": {
	  "title": "примерен глосар",
	  "GlossDiv": {
		"title": "S",
		"GlossList": {
		  "GlossEntry": {
			"ID": "SGML",
			"SortAs": "SGML",
			"GlossTerm": "Стандартен генерализован маркерен език",
			"Acronym": "SGML",
			"Abbrev": "ISO 8879:1986",
			"GlossDef": {
			  "para": "Метамаркерен език, използван за създаване на маркерни езици като DocBook.",
			  "GlossSeeAlso": ["GML", "XML"]
			  },
			"GlossSee": "маркиране"
			}
		  }
		}
	  }
	}

След това ще създадем прост скрипт-конвертор и ще го запазим под името 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()

Запазете този скрипт в системния път и го стартирайте при необходимост:

$ ~/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': 'Сет', 'family': 'Кенлон', 'address': {'street': '51b Mornington Roadn', 'city': 'Бруклин', 'state': 'Уелингтън', 'postal': 6021, 'country': 'NZ'}}, 'words': 938, 'comments': 'Добър артикул. Може да бъде по-добър.'}

По темата можете да намерите много други примери. Освен това, има множество онлайн конвертори и местни парсери. Така че не се колебайте да преформатирате данните, когато виждате в тях само неразбираема мизерия.

4. Четете спецификациите

Връщайки се към YAML след дълга пауза, полезно е да посетите yaml.org и да прочетете спецификациите (специфики). Ако имате затруднения с YAML, но все още не сте прочели спецификацията, е време да поправите това. Спецификациите са удивително лесно написани и изискванията към синтаксиса са илюстрирани с множество примери в Глава 6.

5. Псевдоконфигурации

Когато пишете книга или статия, винаги е полезно първо да съставите предварителен план, поне в формата на съдържание. По същия начин е и с YAML. Най-вероятно имате представа какви данни да запишете в YAML файла, но не разбирате много как да ги свържете помежду им. Затова, преди да започнете с YAML, нарисувайте псевдоконфиг.

Псевдоконфигът е подобен на псевдокод, където не е нужно да се притеснявате за структурата или отстъпите, отношенията 'родител-дете', наследяването и вложеността. Тук също: рисувате итерации на данни, докато те идват в главата ви.

Псевдоконфиг с изброяване на програмистите (Мартин и Табита) и техните умения (езици за програмиране: Python, Perl, Pascal и Lisp, Fortran, Erlang, съответно).

След като нарисувате псевдоконфига на бума, внимателно го анализирайте и, ако всичко е наред, оформете го в валиден YAML файл.

6. Дилемата 'табулация или интервали'

Ще трябва да решите дилемата 'табулация или интервали?'. Не в глобален смисъл, а само на ниво вашата организация или поне проект. Не е важно дали ще се използва пост-обработка със скрипт sed, конфигуриране на текстовите редактори на компютрите на програмистите или колективно събиране на подписки за строго спазване на указанията на линтера под заплаха от уволнение, но всички членове на вашия екип, които имат нещо общо с YAML, задължително трябва да използват само интервали (както изисква спецификацията на YAML).

Във всеки нормален текстов редактор може да се настрои автоматично заместване на табулации с определен брой интервали, така че бунтът на привържениците на клавиша Tab не трябва да ви плаши.

Както е добре известно на всеки ненавистник на YAML, на екрана не се вижда разлика между табулации и интервали. А когато нещо не е видимо, за него обикновено се сещат в последния момент, след като са прегледали, проверили и премахнали всички останали възможни проблеми. Час, прекаран в търсене на некоректна табулация или блок от интервали, просто извиква необходимостта да създадете политика за използването на единия или другия, а след това да реализирате солидна проверка за нейното спазване (например, през Git hook за принудително преминаване през линтер).

7. По-добре е по-малко, но качествено (или повече – но качеството е по-малко)

Някои хора обичат да пишат на YAML, тъй като той подчертава структурата. Те активно използват отстъпи, за да отделят блоковете данни. Това е своеобразно измама за имитиране на езици за маркиране, при които се използват явни разделители.

Ето пример за такава структурираност от документацията на Ansible:

# 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