10 צעדים ל-YAML Zen

כולנו אוהבים את Ansible, אבל Ansible זה YAML. ישנם פורמטים רבים לקובצי תצורה: רשימות ערכים, צמדי פרמטרים-ערכים, קבצי INI, YAML, JSON, XML ועוד רבים אחרים. עם זאת, מכמה סיבות מכולן, YAML נחשבת לרוב לקשה במיוחד. בפרט, למרות המינימליזם המרענן והיכולות המרשימות שלו לעבודה עם ערכים היררכיים, תחביר YAML יכול להיות מעצבן עם הגישה דמוית ה-Python שלו להזחה.

אם YAML מעצבן אותך, אתה יכול - וכדאי לך! - בצע את 10 הצעדים הבאים כדי להפחית את התסכול שלך לרמה מקובלת ולהתאהב ב-YAML. כיאה לרשימה זו, עשרת העצות שלנו יספרו מאפס, נוסיף מדיטציה ותרגולים רוחניים כרצוננו 😉

0. תגרום לעורך שלך לעבוד

זה לא משנה איזה עורך טקסט יש לך, כנראה שיש לפחות תוסף אחד לעבודה עם YAML. אם אין לך אחד כזה, מצא והתקן אותו מיד. זמן החיפוש וההגדרה ישתלם פעמים רבות בכל פעם שתצטרך לערוך את YAML.

למשל, עורך אטום תומך ב-YAML כברירת מחדל, אבל עבור GNU Emacs תצטרך להתקין חבילות נוספות, למשל, yaml-mode.

Emacs במצב YAML והצגת רווחים.

אם לעורך המועדף עליך אין מצב YAML, ניתן לפתור חלק מהבעיות על ידי עבודה עם ההגדרות. לדוגמה, לעורך הטקסט הרגיל של GNOME Gedit אין מצב YAML, אבל כברירת מחדל הוא מדגיש את תחביר YAML ומאפשר לך להגדיר עבודה עם הזחה:

הגדרת כניסות בגדית.

תוסף מרחבי משיכה עבור Gedit, מציג רווחים כנקודות, מבטל אי בהירות עם רמות הזחה.

במילים אחרות, הקדישו זמן ללמידה על העורך האהוב עליכם. גלה מה יש לו או לקהילת הפיתוח שלו להציע לעבודה עם YAML, והשתמש בתכונות הללו. אתה בהחלט לא תצטער על זה.

1. השתמש בליטר

באופן אידיאלי, שפות תכנות ושפות סימון משתמשות בתחביר צפוי. מחשבים טובים בחיזוי, וזו הסיבה שהמושג של lintera. אם ב-40 שנות קיומו הוא חלף על פניכם ואתם עדיין לא משתמשים ב-YAML linter, אז זה הזמן לנסות את yamllint.

להתקנה ימלינט אתה יכול להשתמש במנהל החבילות הרגיל של לינוקס. לדוגמה, ב Red Hat Enterprise לינוקס 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 לא מוצא שגיאות בקובץ, שום דבר לא מודפס על המסך. אם שקט כזה מפחיד אותך ואתה רוצה עוד קצת פידבק, אז אתה יכול להפעיל את ה-linter עם פקודת ההד המותנית באמצעות אמפרסנד כפול (&&), כך:

$ 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. Pseudo-configs

בעת כתיבת ספר או מאמר, תמיד כדאי לשרטט תחילה מתווה ראשוני, לפחות בצורה של תוכן עניינים. זה אותו דבר עם YAML. סביר להניח שיש לך מושג אילו נתונים צריכים להיכתב בקובץ YAML, אבל אתה לא ממש מבין איך לחבר אותם אחד עם השני. לכן, לפני פיסול YAML, צייר פסאודו-קונפיג.

Pseudo-config דומה לפסאודו-קוד, שבו אינך צריך לדאוג לגבי מבנה או הזחה, יחסי הורים וילדים, ירושה וקינון. זה אותו דבר כאן: אתה מצייר איטרציות של הנתונים כשהם עולים בראש שלך.

תצורת פסאודו של מתכנתים (מרטין וטביטה) וכישוריהם (שפות תכנות: Python, Perl, Pascal ו-Lisp, Fortran, Erlang, בהתאמה).

לאחר ציור פסאודו-קונפיגורציה על פיסת נייר, נתח אותה בזהירות ואם הכל תקין, פרמט אותה בצורה של קובץ YAML חוקי.

6. דילמת הטאבים מול החללים

תצטרך לפתור את הדילמה "טאבים או רווחים?". לא במובן הגלובלי, אלא רק ברמת הארגון שלך, או לפחות פרויקט. זה לא משנה אם זה כרוך בשימוש לאחר עיבוד עם סקריפט sed, הגדרת עורכי טקסט במכונות של מתכנתים, או קבלה אוניברסלית על ציות קפדני להוראות ה-linter תחת איום בפיטורים, אבל כל חברי הצוות שלך אשר ב- כך או אחרת בהתייחסות ל-YAML יש להשתמש ברווחים בלבד (כפי שנדרש במפרט YAML).

בכל עורך טקסט רגיל, אתה יכול להגדיר טאבים לתיקון אוטומטי למספר מוגדר של רווחים, כך שמרד של חסידי מפתח Tab אתה לא צריך לפחד.

כפי שכל שונא 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