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: example glossary

Това е абсолютно коректен 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': 'Seth', 'family': 'Kenlon', 'address': {'street': '51b Mornington Roadn', 'city': 'Brooklyn', 'state': 'Wellington', 'postal': 6021, 'country': 'NZ'}}, 'words': 938, 'comments': 'Добра статия. Може да бъде по-добра.'}

Можете да намерите много други примери по тази тема. Освен това, съществуват много онлайн конвертори и локални парсери. Не се колебайте да преформатирате данните, когато виждате в тях само неразбория.

4. Четете спеките

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

5. Псевдоконфигurations

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

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

Псевдоконфиг с изброяване на програмисти (Martin и Tabitha) и техните умения (програмен език: 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 файла постоянно повтаряте едни и същи грешки, има смисъл да поставите в него шаблон-шаблон под формата на коментар. Тогава следващия път просто можете да копирате този шаблон и да впишете реалните данни, например:

---
# - <общо име>:
#   name: Псевдоним
#   job: РАБОТА
#   skills:
#   - ЕЗИК
- 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