منسق YAML

اجعل بنية YAML أسهل للقراءة

قد تخفي ملفات YAML المضغوطة أو غير المنتظمة علاقات الأب والابن وعناصر القوائم والقيم النصية. يعرض هذا المنسق بنية متسقة لتفحص الإعدادات قبل استخدامها في البناء أو النشر أو الطلبات أو سير العمل الآلي.

يغيّر التنسيق طريقة العرض ولا يثبت أن YAML يطابق مخططاً أو عقداً خاصاً بالتطبيق. قارن المفاتيح والقيم وترتيب القوائم والاقتباسات والتعليقات والنوع الصريح مع المصدر بعد التنسيق.

استخدم عينة صغيرة ممثلة عند التعلم. احتفظ بالنص الأصلي والنسخة المنسقة ونتيجة parser أو schema منفصلة حتى تعرف إن كانت المشكلة في المسافة البادئة أو صياغة YAML أو الترميز أو قواعد التطبيق.

عندما يتحكم YAML في سلوك الإنتاج، راجع diff مع أداة أو مراجع آخر. قد يحتوي الملف المقروء على قيمة خطرة أو نوع غير متوقع أو alias أو مفتاح يفسره التطبيق بطريقة مختلفة.

التنسيق ليس تدقيق YAML

يمثل YAML الخرائط والقوائم والقيم النصية والتعليقات والمراسي والمرادفات وعلامات المستند من خلال المسافات البادئة وعلامات الترقيم. وقد تغيّر مسافة في المستوى الخطأ الشجرة، كما قد تغيّر القيمة المقتبسة أو غير المقتبسة تفسير parser لها.

يقرأ المنسق قدراً كافياً من الصياغة لترتيب النص والمسافات. لكنه لا يثبت توافق النتيجة مع JSON Schema أو OpenAPI أو Kubernetes أو إعدادات CI أو أي قاعدة تطبيق أخرى.

لدى YAML أنماط متعددة للقيم النصية وإصدارات مختلفة للـ parser. قد يختلف تفسير النص العادي والسلاسل المقتبسة والقيم المنطقية والأرقام وnull والكتل متعددة الأسطر والمراسي والوسوم. احتفظ بالمصدر واختبر parser المستخدم فعلياً.

التعليقات مفيدة للقارئ لكنها ليست عادة بيانات للتطبيق. إذا كان المسار يحتاج الاحتفاظ بها، فتحقق من ذلك باستخدام parser وserializer الفعليين.

كيفية تنسيق YAML

1. ألصق مستند YAML كاملاً أو جزءاً موثقاً في حقل المصدر. أزل النصوص غير المرتبطة وأغلفة لغة البرمجة من عينة الاختبار.
2. شغّل المنسق وافحص الخرائط وعلامات القوائم والمسافات البادئة والاقتباسات والتعليقات والكتل متعددة الأسطر. اعتبر الفشل سبباً لفحص الإدخال، لا دليلاً على رسالة parser محددة.
3. قارن النص المنسق بالأصل. تأكد من أن أسماء المفاتيح والقيم وترتيب القوائم والمراسي والمرادفات وعلامات المستند والتعليقات تحمل المعنى المقصود.
4. بعد التنسيق شغّل parser أو schema validator أو linter أو اختبار التطبيق المطلوب في المشروع. التنسيق وحده لا يثبت الصحة أو التوافق.
5. في إعدادات الإنتاج أزل الأسرار والمعلومات الشخصية من العينة، واحتفظ بالملف الأصلي لمقارنة مضبوطة والتراجع.

طريقة التنسيق

• قراءة بنية YAML

  يقرأ الأداة نص YAML ويحدد الخرائط وعناصر القوائم وأنماط القيم والتعليقات وحدود المستند التي يمكن ترتيبها.

• تطبيق المسافات البادئة

  يضيف المنسق فواصل أسطر ومسافات بادئة متسقة حتى تظهر المفاتيح الأبناء. هذه المسافات للعرض وليست قاعدة schema جديدة.

• الحفاظ على القيم التقنية

  يجب إبقاء السلاسل المقتبسة والقيم المنطقية والأرقام والمراسي والمرادفات والكتل والتعليقات مرتبطة بعينة المصدر. راجع diff عندما تكون القيم أو الأنواع مهمة.

قراءة النتيجة المنسقة

النتيجة الناجحة هي ترتيب مقروء لـ YAML المدخل. تأكد من أن الشجرة والقيم وترتيب القوائم والتعليقات وأنماط القيم تطابق المصدر.

يعني الفشل أن مسار المنسق الموثق لم يتعامل مع الإدخال. لا تستنتج قاعدة parser أو موضع خطأ دقيقاً بلا دليل من runtime مطابق.

إذا فشل الملف لاحقاً في schema أو linter أو اختبار التطبيق، فهذه مشكلة عقد منفصل. التنسيق لا يضيف مفاتيح مطلوبة ولا يثبت أمان النشر.

أخطاء شائعة

اعتبار المسافات البادئة تحققاً من schema قد يخفي مفاتيح مفقودة أو أنواعاً خاطئة أو قيماً يرفضها التطبيق.

إزالة الاقتباسات من تاريخ أو نقطتين أو قيمة منطقية أو رقم يبدأ بصفر قد تغيّر تفسير parser للقيمة.

ترتيب الخرائط أو القوائم لأسباب بصرية قد يغيّر إعداداً حساساً للترتيب أو يخفي الترتيب الأصلي في المراجعة.

نسخ جزء من الملف دون anchors أو aliases أو علامة المستند أو سياق المسافة قد يجعل الاختبار مختلفاً عن ملف الإنتاج.

القيود

القدرة الموثقة هي تنسيق YAML. لا تثبت صحة schema أو توافق linter أو سلامة الأسرار أو صحة التحويل أو توافق التطبيق.

يجب اختبار تحويل القيم والمفاتيح المكررة والمراسي والمرادفات والكتل متعددة الأسطر وإصدارات YAML والاحتفاظ بالتعليقات مع parser وserializer المستهدفين.

لا تلصق إعدادات إنتاج سرية إن لم تسمح سياسة التعامل بذلك؛ فقد تحتوي النسخة المنسقة على كلمات مرور أو رموز أو نقاط نهاية داخلية.

Examples

Frequently asked questions

References

• مواصفة YAML 1.2.2
• منسق YAML في Ali Hub