أسرع طريقة لتحويل TOML إلى YAML هي yq -oy '.' file.toml. للتحويل اليدوي، قم بتعيين رؤوس الجداول [table] في TOML إلى كتل بمسافة بادئة في YAML، والمصفوفات في TOML إلى قوائم مسبوقة بشرطة، وضع دائمًا علامات اقتباس حول السلاسل النصية الغامضة لتجنب “مشكلة النرويج.”
تحويل سريع: استخدام واجهة سطر الأوامر yq
وصل TOML (لغة توم الواضحة والبسيطة) إلى إصداره v1.1.0 في ديسمبر 2025، لكن YAML يظل المعيار القياسي لخطوط أنابيب CI/CD وبيانات Kubernetes. تقوم أداة yq بالتحويل في أمر واحد.
تثبيت yq
| المنصة | الأمر |
|---|---|
| macOS/Linux | brew install yq |
| Windows | choco install yq |
| Python (pip) | pip install yq |
يُفضّل إصدار Go من مايك فاراه لسرعته. كما هو مُشير إليه في وثائق yq لمايك فاراه، تقوم الأداة بفك ترميز بنية TOML وإعادة ترميزها كـ YAML نظيف.
تشغيل التحويل
العرض في الطرفية:
yq -oy '.' your-config.toml
الحفظ في ملف:
yq -oy '.' your-config.toml > your-config.yaml
يحدد العلم -oy تنسيق الإخراج كـ YAML. يعمل هذا على معالجة أزواج المفاتيح والقيم والجداول المتداخلة والمصفوفات.
خريطة ترجمة البنية: من TOML إلى YAML
أشار المطور درو ديفولت إلى أنه بينما يُعدّ TOML شائعًا، إلا أن YAML يتعامل مع التداخل العميق بشكل أنظف. إليك التعيين الدقيق:
الجداول إلى مفاتيح بمسافة بادئة
يستخدم TOML رؤوسًا بأقواس مربعة؛ ويستخدم YAML المسافة البادئة.
| TOML | YAML |
|---|---|
[server] |
server: |
host = "127.0.0.1" |
host: 127.0.0.1 |
port = 8080 |
port: 8080 |
فرق جوهري: في TOML، المسافة البادئة تجميلية. في YAML، المسافة البادئة هيكلية — مسافة خاطئة واحدة تكسر التكوين بالكامل.
المصفوفات إلى قوائم مسبوقة بشرطة
TOML: ports = [ 8000, 8001 ]
YAML:
ports:
- 8000
- 8001
كما يشرح Knightli.com، يجعل “أسلوب الكتلة” في YAML القوائم مقروءة، بشرط أن يكون المحاذاة العمودية متسقة.
الجداول المضمنة والمفاتيح المنقوطة
| بنية TOML | المكافئ في YAML |
|---|---|
[a.b.c] (رأس منقط) |
a: ← b: ← c: (مسافة بادئة متداخلة) |
point = { x = 1, y = 2 } (جدول مضمن) |
point: ← x: 1 ← y: 2 |
حالات الاستخدام الواقعية
تكوين موقع Hugo الثابت
يقبل Hugo كلًا من hugo.toml و hugo.yaml و hugo.json. تبدأ معظم المشاريع بـ TOML (الافتراضي)، ثم تنتقل إلى YAML عندما يحتاج التكوين إلى التوافق مع منصات النشر مثل Netlify أو GitHub Actions. يشير Hammer Europe إلى أن أمر hugo يقرأ هذه الملفات لتحديد كيفية تحويل Markdown إلى موقع مباشر.
تغليف Python: من pyproject.toml إلى YAML لـ CI/CD
وّحدت مجتمع Python ملف pyproject.toml عبر PEP 518. تحتاج هذه الإعدادات غالبًا إلى الترجمة إلى YAML لسير عمل CI/CD في GitHub Actions. بالنسبة لسير عمل وكلاء الذكاء الاصطناعي، يُبلّغ CocoIndex أن تكوينات YAML المُحسّنة يمكن أن تقلل استخدام الرموز بنسبة تصل إلى 70%.
مشكلة النرويج ومزالق التحويل الأخرى
خطأ رمز الدولة NO
في YAML 1.1، يتم تحويل السلاسل النصية المجردة مثل NO و OFF و YES تلقائيًا إلى القيم المنطقية false أو true. يتجنب TOML ذلك بمتطلبة علامات اقتباس على جميع السلاسل النصية. عند التحويل، ضع دائمًا علامات اقتباس حول القيم الغامضة في YAML:
| القيمة | تفسير YAML 1.1 | الإصلاح |
|---|---|---|
NO |
false |
"NO" |
OFF |
false |
"OFF" |
YES |
true |
"YES" |
On |
true |
"On" |
يعالج YAML 1.2 (المواصفة الحالية) معظم هذه التحويلات، لكن العديد من المحللات لا تزال تستخدم سلوك 1.1 بشكل افتراضي.
أخطاء المسافة البادئة
ترفض محللات YAML الملفات ذات المسافة البادئة غير المتسقة. الأخطاء الشائعة:
- خلط الجداول والمسافات (يمنع YAML استخدام الجداول)
- استخدام 3 مسافات في كتلة و2 في أخرى
- عناصر قائمة غير محاذاة
التوليد المساعد بالذكاء الاصطناعي
تتيح أدوات مثل AgentBuilder وصف التكوين بلغة طبيعية وإخراج YAML مُتحقق منه. تساعد دورة “الوصف ← التوليد ← التحقق” هذه في تجنب أخطاء المسافة البادئة ومشكلة النرويج على حد سواء.
الخلاصة
استخدم yq -oy '.' file.toml للتحويل الآلي. للعمل اليدوي، قم بتعيين جداول TOML إلى مسافة بادئة YAML، والمصفوفات إلى قوائم مسبوقة بشرطة، وضع دائمًا علامات اقتباس حول السلاسل النصية التي يمكن الخلط بينها وبين القيم المنطقية. بعد أي تحويل، تحقق من صحة مخرجات YAML قبل النشر — مسافة بادئة خاطئة واحدة أو NO بدون علامات اقتباس يمكن أن تكسر خط الأنابيب بالكامل.
الأسئلة الشائعة
هل يدعم YAML التعليقات مثل TOML؟
نعم. كلاهما يستخدم # للتعليقات أحادية السطر. قد تتداخل تعليقات YAML مع تحليل السلاسل النصية متعددة الأسطر، لذا ضعها في أسطر منفصلة عند الشك.
ما هي ‘مشكلة النرويج’ في YAML؟
في YAML 1.1، يتم تحويل السلاسل النصية المجردة مثل NO (رمز دولة النرويج) تلقائيًا إلى القيمة المنطقية false. يتجنب TOML ذلك بمتطلبة علامات اقتباس على جميع قيم السلاسل النصية. عند تحويل TOML إلى YAML، ضع أي سلسلة نصية يحتمل أن تكون غامضة بين علامتي اقتباس.
أي تنسيق يتعامل بشكل أفضل مع التداخل العميق؟
YAML. يتطلب TOML تكرار رؤوس طويلة مثل [table.subtable.subsubtable] لكل مستوى، مما يصبح مطوّلاً. يمثل YAML نفس التسلسل الهرمي بمسافة بادئة — أكثر إيجازًا وقابلية للقراءة في الأعماق.
اترك تعليقاً