من TOML إلى JSON

كيف تتقابل الأنواع

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

مثال كامل

title = "My App"

[server]
host = "localhost"
port = 8080

[[users]]
name = "alice"
admin = true

يتحول إلى:

{
    "title": "My App",
    "server": {
        "host": "localhost",
        "port": 8080
    },
    "users": [
        {
            "name": "alice",
            "admin": true
        }
    ]
}

ما يدعمه المحلل من TOML وحدوده الحقيقية

المدعوم: ترويسات [الجداول] بما فيها أسماء الأقسام المنقّطة، و[[مصفوفات الجداول]]، وأزواج key = value في سطر واحد، والسلاسل الأساسية "..." مع محارف الهروب \n و\t و\"، والسلاسل الحرفية '...'، والأعداد الصحيحة والعشرية البسيطة، وtrue/false، والمصفوفات في سطر واحد (مع السماح بالتداخل)، وتعليقات # التي تشغل السطر كاملا، والتواريخ التي تمر كسلاسل نصية.

غير المدعوم، وما ينبغي فعله بدلا منه:

• السلاسل متعددة الأسطر (""" أو ''') والمصفوفات متعددة الأسطر توقف المحلل بخطأ. ضع القيمة في سطر واحد أولا.
• الجداول المضمّنة لا تفكك: يخرج point = { x = 1, y = 2 } على شكل السلسلة "{ x = 1, y = 2 }" لا ككائن. أعد كتابته كقسم [point] مستقل. أسطر الاعتماديات في Cargo.toml مثل serde = { version = "1.0" } هي الحالة الكلاسيكية.
• المفاتيح المنقّطة على يسار علامة المساواة تبقى مفتاحا مسطحا واحدا: ينتج server.host = "a" المفتاح "server.host" دون تداخل. استخدم ترويسة [server] بدلا من ذلك. أما [أسماء.الأقسام] المنقّطة في الترويسات فتتداخل بشكل صحيح.
• التعليقات بعد القيمة لا تحذف: يصبح port = 8080 # main السلسلة "8080 # main". أبق التعليقات في أسطر مستقلة.
• صيغ الأعداد غير العشرية البسيطة لا تتعرف: تخرج 1_000 و0xFF و5e2 و+99 وinf وnan كسلاسل بين علامات اقتباس. اكتب 1000 و255 و500 و99 بدلا منها.
• محارف الهروب \uXXXX في السلاسل الأساسية لا تفك. الصق الحرف الحقيقي بدلا منها.

لمستند TOML 1.0 كامل، استخدم محولا من سطر الأوامر مثل toml2json، أو حمّل الملف عبر tomllib في Python وأخرج JSON من هناك.

أين يفيد هذا

• فحص سريع لمقطع TOML بصيغة JSON أثناء تصحيح الأخطاء.
• تمرير قيم تهيئة بسيطة إلى أدوات الفحص أو السكربتات أو أدوات الجرد التي لا تقبل سوى JSON.
• توليد بيانات اختبار JSON من ملاحظات TOML الأسهل كتابة باليد.
• ترحيل ملفات تهيئة صغيرة ومسطحة، وهو حال كثير من ملفات config.toml في Hugo.

ملاحظات على رحلة الذهاب والإياب

• التعليقات لا تنجو أبدا: لا توجد في JSON صيغة تعليقات أصلا.
• تبقى التواريخ سلاسل نصية؛ وعلى الشيفرة اللاحقة إعادة تحليلها إلى كائنات تاريخ.
• الأعداد الكبيرة: تحفظ الأعداد الصحيحة كقيم 64 بت في نص JSON، لكن مستهلكي JavaScript يفقدون الدقة فوق 2^53. انتبه للطوابع الزمنية بالنانوثانية والمعرفات الرقمية.
• ترتيب المفاتيح يحافظ عليه هذا المحول كما كتب؛ وقد تعيد أدوات JSON أخرى ترتيب المفاتيح عند إخراج المستند من جديد.

الاتجاه المعاكس

التحويل من JSON إلى TOML هو الرحلة الأصعب، لأن في JSON بنى (تداخل مجهول عميق، وقيمة null) لا يملكها TOML أو يعالجها بشكل مختلف. تحتاج معظم سيناريوهات الذهاب والإياب إلى تعديلات يدوية في جانب TOML.