10 قدم برای YAML Zen

همه ما 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. از لینتر استفاده کنید

در حالت ایده آل، زبان های برنامه نویسی و زبان های نشانه گذاری از نحو قابل پیش بینی استفاده می کنند. رایانه ها در قابلیت پیش بینی خوب هستند، به همین دلیل است که مفهوم لینترا. اگر در 40 سال عمر خود از کنار شما گذشته است و هنوز از لنتر YAML استفاده نمی کنید، وقت آن است که یامللینت را امتحان کنید.

نصب کنید یاملینت می توانید از مدیریت بسته استاندارد لینوکس استفاده کنید. به عنوان مثال، در Red Hat Enterprise لینوکس 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 را برگرداند، یک علامت دوتایی فعال می‌شود.

2. در پایتون بنویسید نه YAML

اگر YAML واقعاً شما را عصبانی می کند، فقط به معنای واقعی کلمه در آن ننویسید. این اتفاق می افتد که YAML تنها قالبی است که برنامه درک می کند. اما حتی در این مورد نیز نیازی به ایجاد فایل YAML نیست. روی چیزی که دوست دارید بنویسید و سپس تبدیل کنید. به عنوان مثال، یک کتابخانه عالی برای پایتون وجود دارد پیامل و دو روش تبدیل: خود تبدیل و تبدیل از طریق اسکریپت.

خود تبدیلی

در این مورد، فایل داده نیز یک اسکریپت پایتون است که YAML را تولید می کند. این روش برای مجموعه داده های کوچک مناسب است. شما به سادگی داده های JSON را در یک متغیر پایتون می نویسید، مقدمه آن را با یک دستور 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

حالا این فایل را در پایتون اجرا می کنیم و فایل 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 به شما هشدار می دهد که با - شروع نمی شود. خوب، این را می توان به راحتی به صورت دستی یا کمی در اسکریپت پایتون اصلاح کرد.

تبدیل از طریق اسکریپت

در این مورد، ابتدا با JSON می نویسیم و سپس مبدل را به عنوان یک اسکریپت جداگانه پایتون اجرا می کنیم که 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 تبدیل کنید. فرض کنید شما یک فایل 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، یک شبه پیکربندی بکشید.

شبه پیکربندی شبیه به شبه کد است، جایی که لازم نیست نگران ساختار یا تورفتگی، روابط والدین و فرزند، وراثت و تودرتو باشید. اینجا هم همین‌طور است: شما تکرارهایی از داده‌ها را همانطور که در ذهن شما ایجاد می‌شوند ترسیم می‌کنید.

برنامه نویسان فهرست بندی شبه پیکربندی (مارتین و تابیتا) و مهارت های آنها (به ترتیب زبان های برنامه نویسی: Python، Perl، Pascal و Lisp، Fortran، Erlang).

پس از رسم شبه کانفیگ بر روی یک کاغذ، آن را به دقت تجزیه و تحلیل کنید و اگر همه چیز درست است، آن را در قالب یک فایل YAML معتبر فرمت کنید.

6. معضل Tabs در مقابل فضاها

شما باید معضل را حل کنید "برگه ها یا فاصله ها؟". نه به معنای جهانی، بلکه فقط در سطح سازمان شما یا حداقل یک پروژه. مهم نیست که از پس پردازش با یک اسکریپت sed استفاده می شود، تنظیم ویرایشگرهای متن در دستگاه های برنامه نویس، یا دریافت رسیدهایی مبنی بر انطباق دقیق با دستورالعمل های linter تحت تهدید اخراج، مهم نیست، اما همه اعضای تیم شما که در یک برنامه راه یا روش دیگری که به 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 غلبه کنید!

منبع: www.habr.com