Wszyscy lubimy Ansible, ale Ansible to YAML. Istnieje wiele formatów plików konfiguracyjnych: listy wartości, pary „parametr-wartość”, pliki INI, YAML, JSON, XML i wiele innych. Jednak z kilku powodów YAML często uważany jest za szczególnie trudny. W szczególności, mimo jego orzeźwiającego minimalizmu i imponujących możliwości pracy z wartościami hierarchicznymi, składnia YAML może być irytująca ze względu na swoje podejście do wcięć przypominające Pythona.
Jeśli YAML cię denerwuje, możesz – i powinieneś! – podjąć 10 poniższych kroków, aby zmniejszyć swoje frustracje do akceptowalnego poziomu i pokochać YAML. Jak przystało na prawdziwą listę, nasze dziesięć wskazówek będzie numerowane od zera, medytację i praktyki duchowe dodajemy według uznania 😉
0. Spraw, aby Twój edytor działał
Nie ma znaczenia, jaki edytor tekstowy masz – na pewno istnieje przynajmniej jeden plugin do pracy z YAML. Jeśli go nie masz, natychmiast znajdź i zainstaluj. Czas poświęcony na poszukiwanie i konfigurację zwróci się wielokrotnie za każdym razem, gdy będziesz musiał edytować YAML.
Na przykład, edytor domyślnie obsługuje YAML, a dla GNU Emacs trzeba zainstalować dodatkowe pakiety, takie jak .
Emacs w trybie YAML i wyświetlania spacji.
Jeżeli Twój ulubiony edytor nie ma trybu YAML, część problemów można rozwiązać, dostosowując ustawienia. Na przykład, domyślny edytor tekstowy GNOME Gedit nie ma trybu YAML, ale domyślnie podświetla składnię YAML i umożliwia dostosowanie pracy z wcięciami:
Konfiguracja wcięć w Gedit.
A plugin dla Gedit wyświetla spacje w postaci kropek, eliminując niejasności związane z poziomami wcięcia.
Innymi słowy, poświęć czas na poznanie swojego ulubionego edytora. Dowiedz się, co on sam lub jego społeczność deweloperska oferują do pracy z YAML i skorzystaj z tych możliwości. Na pewno się nie zawiedziesz.
1. Używaj lintera
W idealnym świecie języki programowania i języki znaczników powinny używać przewidywalnej składni. Komputery dobrze radzą sobie z przewidywalnością, dlatego już w 1978 roku powstała koncepcja Jeśli przez 40 lat ta koncepcja umknęła ci i nadal nie korzystasz z lintera YAML, czas spróbować yamllint.
Zainstalować można zainstalować za pomocą wbudowanego menedżera pakietów Linux. Na przykład, w 8 lub robi się to tak:
$ sudo dnf install yamllint
Następnie po prostu uruchamiasz yamllint, przekazując mu plik YAML do sprawdzenia. Oto jak to wygląda, gdy przekażesz linterowi plik z błędem:
$ yamllint errorprone.yaml
errorprone.yaml
23:10 błąd błąd składni: wartości mapowania nie są tutaj dozwolone
23:11 błąd zbędne spacje (trailing-spaces)
Liczby po lewej stronie to nie czas, a współrzędne błędu: numer wiersza i kolumny. Opis błędu może nic nie mówić, ale dokładnie wiesz, gdzie się znajduje. Po prostu spójrz na to miejsce w kodzie, a prawdopodobnie wszystko stanie się jasne.
Kiedy yamllint nie znajduje błędów w pliku, nic nie jest wyświetlane. Jeśli przeraża cię taka cisza i chcesz nieco więcej informacji zwrotnej, możesz uruchomić linter z warunkową komendą echo przez podwójny ampersand (&&), tak:
$ yamllint perfect.yaml && echo "OK"
OK
W POSIX podwójny ampersand działa tylko wtedy, gdy poprzednia komenda zwraca 0. A yamllint zwraca liczbę znalezionych błędów, dlatego cała ta konstrukcja warunkowa działa.
2. Pisz w Pythonie, a nie w YAML
Jeśli naprawdę denerwuje cię YAML, po prostu nie pisz w nim, w dosłownym sensie. Czasami YAML jest jedynym formatem akceptowanym przez aplikację. Ale nawet wtedy nie ma potrzeby tworzenia pliku YAML. Pisz w tym, co lubisz, a potem konwertuj. Na przykład, dla Pythona jest doskonała biblioteka i dwa sposoby konwersji: konwersja bezpośrednia i konwersja przez skrypty.
Konwersja bezpośrednia
W tym przypadku plik z danymi jest jednocześnie skryptem Pythona, który generuje YAML. Ten sposób najlepiej nadaje się dla małych zestawów danych. Po prostu zapisujesz dane JSON w zmiennej Pythona, poprzedzasz to dyrektywą import, a na końcu pliku dodajesz trzy linijki do realizacji wyjścia.
#!/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
Teraz uruchamiamy ten plik w Pythonie i na wyjściu otrzymujemy plik 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
To absolutnie poprawny YAML, ale yamllint wyda ostrzeżenie, że nie zaczyna się od —. Cóż, można to łatwo naprawić ręcznie lub nieco poprawić skrypt Pythona.
Konwersja przez skrypty
W tym przypadku najpierw piszemy w JSON, a następnie uruchamiamy konwerter w postaci osobnego skryptu Pythona, który na wyjściu generuje YAML. W porównaniu do poprzedniego ten sposób lepiej skalowalny, ponieważ konwersja jest oddzielona od danych.
Na początek stwórz plik JSON example.json, można go na przykład pobrać z :
{
"glossary": {
"title": "przykładowy słownik",
"GlossDiv": {
"title": "S",
"GlossList": {
"GlossEntry": {
"ID": "SGML",
"SortAs": "SGML",
"GlossTerm": "Standard Generalized Markup Language",
"Acronym": "SGML",
"Abbrev": "ISO 8879:1986",
"GlossDef": {
"para": "Meta-język znaczników, stosowany do tworzenia języków znaczników, takich jak DocBook.",
"GlossSeeAlso": ["GML", "XML"]
},
"GlossSee": "markup"
}
}
}
}
}
Następnie stwórz prosty skrypt konwertera i zapisz go pod nazwą json2yaml.py. Ten skrypt importuje oba moduły - YAML i JSON Pythona, a także ładuje określony przez użytkownika plik JSON, wykonuje konwersję i zapisuje dane do pliku 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()
Zapisz ten skrypt w ścieżce systemowej i uruchamiaj w razie potrzeby:
$ ~/bin/json2yaml.py example.json
3. Parsuj dużo i często
Czasami warto spojrzeć na problem z innej perspektywy. Jeśli trudno ci wyobrazić sobie relacje między danymi w YAML, możesz tymczasowo przekonwertować je na coś bardziej znajomego.
Na przykład, jeśli wygodnie ci pracować ze słownikami lub z JSON, to YAML można przekonwertować na JSON jedynie dwiema komendami w interaktywnej powłoce Pythona. Załóżmy, że masz plik YAML mydata.yaml, oto jak to będzie wyglądać:
$ 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': 'Dobry artykuł. Mógłby być lepszy.'}
Na ten temat można znaleźć mnóstwo innych przykładów. Oprócz tego dostępnych jest wiele konwerterów online i lokalnych parserów. Więc nie wahaj się przeformatować danych, gdy widzisz w nich tylko niezrozumiałą mieszaninę.
4. Czytaj specyfikacje
Wracając do YAML po długiej przerwie, warto odwiedzić i przeczytać specyfikacje. Jeśli masz trudności z YAML, ale jeszcze nie zabrałeś się za specyfikacje, to czas to zmienić. Specyfikacje są zaskakująco dobrze napisane, a wymagania dotyczące składni ilustrowane są licznymi przykładami w .
5. Pseudokonfiguracje
Pisząc książkę lub artykuł, zawsze warto najpierw naszkicować wstępny plan, chociażby w formie spisu treści. To samo dotyczy YAML. Prawdopodobnie wiesz, jakie dane powinny znaleźć się w pliku YAML, ale nie do końca rozumiesz, jak je ze sobą powiązać. Dlatego zanim zaczniesz tworzyć YAML, narysuj pseudo-konfigurację.
Pseudo-konfiguracja przypomina pseudokod, w którym nie trzeba martwić się o strukturę czy wcięcia, relacje „rodzic-potomek”, dziedziczenie i zagnieżdżanie. Tak i tutaj: rysujesz iteracje danych w miarę ich pojawiania się w twojej głowie.
Pseudo-konfiguracja z listą programistów (Martin i Tabitha) oraz ich umiejętności (języków programowania: Python, Perl, Pascal i Lisp, Fortran, Erlang, odpowiednio).
Po narysowaniu pseudo-konfiguracji na kartce papieru, dokładnie ją przeanalizuj i, jeśli wszystko jest w porządku, przekształć ją w walidowany plik YAML.
6. Dylemat „tabulacja czy spacje”
Będziesz musiał rozwiązać dylemat . Nie w ogólnym sensie, lecz na poziomie twojej organizacji, albo przynajmniej projektu. Nieważne, czy przy tym używany będzie post-processing skryptem sed, konfiguracja edytorów tekstowych na komputerach programistów, czy też zbiorowe podpisy na przestrzeganie wskazówek lintera pod groźbą zwolnienia, wszyscy członkowie twojego zespołu, którzy w jakikolwiek sposób mają do czynienia z YAML, muszą bezwzględnie używać tylko spacji (jak tego wymaga specyfikacja YAML).
W każdym normalnym edytorze tekstowym można ustawić automatyczne zastępowanie tabulacji na określoną liczbę spacji, więc nie ma co obawiać się buntu zwolenników klawisza Tab nie ma się co obawiać.
Jak dobrze wiadomo każdemu, kto nienawidzi YAML, na ekranie nie widać różnicy między tabulacją a spacjami. A gdy czegoś nie widać, zazwyczaj przypomina się o tym w ostatniej chwili, po przelotnym przejrzeniu, sprawdzeniu i wyeliminowaniu wszystkich innych możliwych problemów. Godzina czasu stracona na szukanie uszkodzonej tabulacji lub bloku spacji głośno woła o to, byś pilnie stworzył politykę użycia tego lub innego, a następnie wdrożył solidne kontrole jej przestrzegania (np. przez Git hook do wymuszenia wykonywania lintera).
7. Lepiej mniej, ale lepiej (lub więcej – to mniej)
Niektórzy ludzie lubią pisać w YAML, ponieważ podkreśla on strukturę. W tym celu aktywnie wykorzystują wcięcia, aby wyróżnić bloki danych. To swoiste oszustwo, które imituje języki znaczników, w których używane są wyraźne separatory.
Oto przykład takiej strukturalności z :
# Employee records
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
Dla niektórych taka opcja pomaga uporządkować w myślach strukturę YAML, podczas gdy innych irytuje masą zbędnych, ich zdaniem, wcięć.
Jednak jeśli jesteś właścicielem dokumentu YAML i odpowiadasz za jego utrzymanie, to ty i tylko ty musisz określić, jak używać wcięć. Jeśli irytują cię duże wcięcia, ogranicz je do minimum, które tylko jest możliwe zgodnie ze specyfikacją YAML. Na przykład, powyższy plik z dokumentacji Ansible można przepisać w ten sposób, bez żadnych strat:
---
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
8. Używaj szablonów
Jeśli podczas wypełniania pliku YAML stale powtarzasz te same błędy, warto wstawić do niego szablon w postaci komentarza. Następnym razem wystarczy po prostu skopiować ten szablon i wpisać w niego rzeczywiste dane, na przykład:
---
# - <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. Użyj czegoś innego
Jeśli aplikacja nie trzyma cię za gardło, może warto zmienić YAML na inny format. Z biegiem czasu pliki konfiguracyjne mogą przerastać siebie i wówczas lepiej przekształcić je w proste skrypty w Lua lub Pythonie.
YAML to wspaniała rzecz, którą wielu lubi za minimalizm i prostotę, ale nie jest to jedyne narzędzie w twoim arsenale. Dlatego czasami można go odstawić. Łatwo znaleźć biblioteki do parsowania YAML, więc jeśli zaproponujesz wygodne opcje migracji, twoi użytkownicy dość bezboleśnie przeżyją taką zmianę.
Jeśli jednak bez YAML się nie obędzie, to skorzystaj z tych 10 porad i pokonaj swoją niechęć do YAML raz na zawsze!
Źródło: habr.com
