10 стъпки към YAML Zen

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

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

0. Накарайте вашия редактор да работи

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

Например редактор Атом поддържа YAML по подразбиране, но за GNU Emacs ще трябва да инсталирате допълнителни пакети, например, yaml-режим.

Emacs в режим YAML и показване на интервали.

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

Задаване на отстъпи в Gedit.

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

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

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

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

установят ямлинт Можете да използвате собствения Linux мениджър на пакети. Например в Red Hat Enterprise Linux 8 г. или Fedora прави се така:

$ 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 pyyaml и цели два начина за конвертиране: самоконвертиране и конвертиране чрез скриптове.

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

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

#!/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": "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()

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

$ ~/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.org и прочетете отново спецификациите (спецификациите). Ако имате затруднения с YAML, но ръцете ви не са достигнали спецификацията, тогава е време да коригирате тази ситуация. Спецификациите са изненадващо лесни за писане, а изискванията за синтаксис са илюстрирани с много примери в Глава 6.

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

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

Pseudoconfig е като псевдокод, където не е нужно да се притеснявате за структура или отстъп, връзки родител-дете, наследяване и влагане. Така е и тук: рисувате повторения на данните, както се появяват в главата ви.

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

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

6. Дилемата за раздели или интервали

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

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

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

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 веднъж завинаги!

Източник: www.habr.com