10 خطوات لتطبيق YAML Zen

كلنا نحب Ansible ، لكن Ansible هي YAML. هناك العديد من التنسيقات لملفات التكوين: قوائم القيم ، وأزواج قيم المعلمات ، وملفات INI ، و YAML ، و JSON ، و XML ، وغيرها الكثير. ومع ذلك ، ولعدة أسباب ، من بينها جميعًا ، غالبًا ما يُعتبر YAML صعبًا بشكل خاص. على وجه الخصوص ، على الرغم من بساطتها المنعشة وإمكانياتها المثيرة للإعجاب للعمل مع القيم الهرمية ، يمكن أن يكون بناء جملة YAML مزعجًا من خلال نهجها الشبيه بـ Python في المسافة البادئة.

إذا كان YAML يزعجك ، يمكنك - ويجب عليك ذلك! - اتخذ الخطوات العشر التالية لتقليل تهيجك إلى مستوى مقبول وتحب YAML. كما يليق بهذه القائمة ، سيتم ترقيم نصائحنا العشر من البداية ، ونضيف التأمل والممارسات الروحية حسب الرغبة 😉

0. اجعل المحرر الخاص بك يعمل

لا يهم محرر النصوص الذي لديك ، فمن المحتمل أن يكون هناك مكون إضافي واحد على الأقل من YAML له. إذا لم يكن لديك واحد ، فابحث عنه وثبته على الفور. الوقت الذي تقضيه في البحث والتعديل سيؤتي ثماره عدة مرات في كل مرة تحتاج فيها إلى تعديل YAML.

على سبيل المثال ، المحرر ذرة يدعم YAML افتراضيًا ، لكن بالنسبة إلى GNU Emacs ، سيتعين عليك تثبيت حزم إضافية ، على سبيل المثال ، yaml- وضع.

إيماكس في وضع YAML وتظهر المساحات.

إذا كان المحرر المفضل لديك لا يحتوي على وضع YAML ، فيمكن حل بعض المشكلات من خلال العمل مع الإعدادات. على سبيل المثال ، محرر النصوص الافتراضي لـ GNOME ، Gedit ، لا يحتوي على وضع YAML ، ولكنه يبرز بشكل افتراضي بناء جملة YAML ويسمح لك بتخصيص المسافة البادئة:

وضع المسافات البادئة في Gedit.

مكوّن إضافي مساحات بالنسبة لـ Gedit ، فإنه يعرض المسافات كنقاط ، مما يزيل الغموض مع مستويات المسافة البادئة.

بمعنى آخر ، خذ الوقت الكافي لتعلم المحرر المفضل لديك. اكتشف ما يجب أن يقدمه هو أو مجتمع التطوير الخاص به للعمل مع YAML ، واستفد من هذه الفرص. أنت بالتأكيد لن تندم.

1. استخدم لينتر

من الناحية المثالية ، تستخدم لغات البرمجة ولغات الترميز بناء جملة يمكن التنبؤ به. أجهزة الكمبيوتر جيدة في القدرة على التنبؤ ، وهذا هو سبب ظهور هذا المفهوم في عام 1978 لينتر. إذا مرت 40 عامًا من وجودها وما زلت لا تستخدم YAML linter ، فقد حان الوقت لتجربة yamllint.

لتثبيت يملينت يمكنك استخدام مدير حزم Linux الأصلي. على سبيل المثال ، في ريد هات إنتيربريس لينوكس 8 أو فيدورا يتم ذلك على النحو التالي:

$ sudo dnf install yamllint

يمكنك بعد ذلك ببساطة تشغيل yamllint ، وتمريره إلى ملف YAML لاختباره. إليك ما سيبدو عليه الأمر إذا قمت بتمرير ملف به خطأ إلى Linter:

$ 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. اكتب ما تريد ، ثم حوّل. على سبيل المثال ، توجد مكتبة رائعة لبايثون 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 ، على سبيل المثال ، 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 ، لكن يديك لم تصل إلى المواصفات ، فقد حان الوقت لتصحيح هذا الموقف. المواصفات سهلة الكتابة بشكل مدهش ، ومتطلبات بناء الجملة موضحة بالعديد من الأمثلة في الفصل السابع عشر.

5. Pseudoconfigs

عند كتابة كتاب أو مقال ، من الأفضل دائمًا رسم مخطط أولي أولاً ، على الأقل في شكل جدول محتويات. نفس الشيء مع YAML. على الأرجح ، لديك فكرة عن البيانات التي يجب كتابتها في ملف YAML ، لكنك لا تفهم حقًا كيفية ربطها ببعضها البعض. لذلك ، قبل نحت YAML ، ارسم تكوينًا زائفًا.

يشبه Pseudoconfig مثل الكود الزائف حيث لا داعي للقلق بشأن البنية أو المسافة البادئة ، والعلاقات بين الوالدين والطفل ، والميراث ، والتداخل. لذا فهي هنا: ترسم تكرارات للبيانات كما تظهر في رأسك.

يسرد Pseudoconfig المبرمجين (Martin و Tabitha) ومهاراتهم (لغات البرمجة: Python و Perl و Pascal و Lisp و Fortran و Erlang ، على التوالي).

بعد رسم شكل زائف على قطعة من الورق ، قم بتحليله بعناية ، وإذا كان كل شيء على ما يرام ، فنسقه كملف YAML صالح.

6. معضلة علامات التبويب أو المسافات

عليك أن تحل معضلة "علامات تبويب أم مسافات؟". ليس بالمعنى الشامل ، ولكن فقط على مستوى مؤسستك ، أو على الأقل مشروع. لا يهم ما إذا كان هذا يتضمن معالجة لاحقة بنص 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 إلى تنسيق آخر. بمرور الوقت ، يمكن أن تتخطى ملفات التكوين نفسها ، ومن الأفضل تحويلها إلى نصوص لوا أو بايثون بسيطة.

يعد YAML شيئًا رائعًا يحبه الكثير من الناس بسبب بساطته وبساطته ، ولكنه بعيد كل البعد عن الأداة الوحيدة في ترسانتك. لذلك في بعض الأحيان يمكنك رفضه. من السهل العثور على مكتبات تحليلية لـ YAML ، لذلك إذا كنت تقدم خيارات ترحيل ملائمة ، فسوف ينجو المستخدمون من هذا الرفض بدون ألم نسبيًا.

إذا كنت لا تستطيع الاستغناء عن YAML ، فاستخدم هذه النصائح العشر في الخدمة وتغلب على كرهك لـ YAML مرة واحدة وإلى الأبد!

المصدر: www.habr.com