تحويل TOML إلى JSON

ما محوِّل TOML إلى JSON؟

TOML صيغة إعدادات صُمّمت لتكون بيّنةً لمن يقرؤها: أقسام بين قوسين معقوفين، ومفاتيح وقيم يفصل بينها علامة يساوٍ، ولا مسافات بيضاء ذات دلالة يمكن أن تُخطئ فيها. وهي ما يستعمله Cargo في لغة رست، وملف pyproject.toml في بايثون، وعدد كبير من الأدوات الأخرى. أما JSON فهو ما تتبادله البرامج فيما بينها. والمحوِّل يُحيل أحدهما إلى الآخر، وهذا يفعل ذلك داخل متصفّحك.

والتحويل ليس مجرّد إعادة تسمية، وهنا يكمن ما يستحقّ الانتباه. فـ TOML يميّز أنواعًا من القيم أكثر ممّا يتّسع له JSON، فتُتلَف بعض المعلومات في العبور. وأكثر المحوِّلات تفعل ذلك صامتةً. أما هذا فيسرد كل قيمة اضطرّ إلى تسطيحها وأين كانت، لتقرّر أنت أيهمّك ذلك قبل أن تذهب المخرجات إلى أي مكان.

ويُفحص المحلّل مقابل مجموعة المطابقة الخاصة بمشروع TOML نفسه: 210 مستندات صالحة يجب أن تُنتج نتيجةً دقيقة، و499 يجب أن تُرفض. وهو يحلّل الـ210 جميعها تحليلًا صحيحًا، ويرفض كل الـ499 التي يستطيع رؤيتها فعلًا — والاستثناءات الستّ مستندات تحوي بايتات UTF-8 غير صالحة، ولا يمكن لمحلّل يقرأ حقل نصّ في متصفّح أن يلقاها أبدًا.

كيف تحوّل TOML إلى JSON

1. الصق نصّ TOML لديك. أي شيء صالح في TOML v1.0.0: جداول، ومصفوفات جداول، وجداول سطرية، ومفاتيح منقوطة، ونصوص متعدّدة الأسطر. وأزرار الأمثلة تحمّل واحدًا من كل حالة جديرة بالانتباه.
2. اقرأ JSON. يظهر في الحال بإزاحة مسافتين، ومعه زرّ للنسخ. وإن لم يُحلَّل المستند حصلت على القاعدة التي خُرقت، والسطر والعمود اللذين وقع فيهما ذلك.
3. انظر في لوحة الفقد أسفله. تسمّي كل قيمة عجز JSON عن تمثيلها بأمانة، مع مسارها. وفي ملف إعدادات عادي تقول إنه لم يُفقَد شيء، وذاك قياس لا مواساة.

ما لا يستطيع JSON حمله

لدى TOML أربعة أنواع متمايزة للتاريخ والوقت. فالتاريخ والوقت بإزاحةٍ يثبّت لحظةً بعينها؛ والتاريخ والوقت المحلّي بلا إزاحة؛ والتاريخ المحلّي يومٌ بلا وقت؛ والوقت المحلّي وقتٌ بلا يوم. والأربعة قيمٌ من الدرجة الأولى لكلٍّ منها صياغتها. أما JSON فليس فيه نوع للتاريخ أصلًا، فتصل الأربعة نصوصًا بين علامتَي اقتباس، لا تُميَّز عن نصّ يشبه التاريخ لا غير. حمّل المثال الثاني أعلاه لتسمّيَها اللوحة جميعًا.

ويفصل TOML كذلك الأعداد الصحيحة عن العشرية، وJSON لا يفعل. ولذلك نتيجتان. فالعدد العشري المكتوب 1.0 يخرج 1 ولم يعد يُميَّز عن العدد الصحيح إلى جواره. والعدد الصحيح ذو الـ64 بتًّا — وTOML يضمن المدى المُوقَّع كاملًا — لا ينجو: فأعداد الجافاسكربت دقيقة إلى نحو تسعة كوادرليونات فحسب، فيعود 9223372036854775807 وقد صار 9223372036854776000. والمثال الثالث يُظهر الأمرين.

وأوضح دليل على أن هذه مشكلة حقيقية لا تدقيقًا زائدًا هو مجموعة اختبارات مشروع TOML نفسه. فمخرجاتها المتوقّعة ليست JSON عاديًّا: بل كل قيمة مفردة ملفوفة في كائن يحمل نوعها، عبر ثماني وسوم. فحتى من كتبوا اختبارات المطابقة لم يستطيعوا التعبير عن قيم TOML بـ JSON، فابتكروا ترميزًا يقول ما هي كل قيمة. ولوحة الفقد في هذا المحوِّل هي الاعتراف نفسه، مقدَّمًا حيث يمكنك التصرّف بناءً عليه.

لماذا لا يوجد هنا زرّ من JSON إلى TOML

في الاتجاه المعاكس مشكلة لا حلّ أمينًا لها، ويحسن قولها بدل إخفائها خلف ميزة نصف عاملة. فـ TOML ليس فيه null. ولا توجد أي طريقة لكتابته في القواعد كلها — لا كلمة مفتاحية، ولا قيمة فارغة، ولا شيء. فالمفتاح إما له قيمة وإما غائب.

فمستند JSON يحوي null لا يمكن تحويله. والخياران إما حذف المفتاح، وهذا يغيّر معنى المستند في صمت، وإما كتابة شيء يبدو null وهو في الحقيقة النصّ ذو الأحرف الأربعة، وهذا أسوأ. وليس أيٌّ منهما تحويلًا. والأداة التي تعرض ذلك الزرّ عليها أن تختار أحدهما، وهي في الغالب لا تخبرك أيّهما اختارت.

وثمّة مشكلات أصغر في الاتجاه نفسه — فـ JSON يسمح بمفتاح فارغ، وبمصفوفات مختلفة الأشكال لا تعبّر عنها صياغة جداول TOML تعبيرًا نظيفًا — لكن null هو الذي لا جواب له البتّة. فإن احتجت السير في ذلك الاتجاه، فالأمين أن تقرّر أولًا ما تعنيه تلك القيم الخالية في إعداداتك، فأنت وحدك تعرف.

أمور أخرى يحسن معرفتها

TOML أشدّ صرامةً ممّا يبدو، وهذا المحلّل يلتزم بذلك. فلا يجوز تعريف مفتاح مرتين، ولا إعادة فتح جدول بترويسة ثانية، والجدول السطريّ يُغلَق فور كتابته، فلا يستطيع قسمٌ لاحق أن يضيف إليه. والتواريخ تُتحقَّق لا تفيض، فـ 2026-02-30 خطأ لا الثاني من آذار. والأعداد الصحيحة لا تقبل أصفارًا في المقدّمة. وكل قاعدة من هذه تختبرها مجموعة المطابقة، وكل واحدة خطأ حقيقيّ تُجنَّبه في ملف إعدادات.

ولا تنجو التعليقات ولا التنسيق. فليس في JSON صياغة للتعليقات، فيذهب كل ما بعد علامة # ومعه أسطرك الفارغة، وترتيب مفاتيحك داخل الجدول، واختيارك لعلامات الاقتباس. وهذا من صميم صيغة الوجهة لا نقصٌ في الأداة، ولهذا كان تحويل إعدادات مصونة يدويًّا إلى JSON رحلةً بلا عودة في الغالب.

ويقبل المحلّل TOML v1.0.0، وهي النسخة الصادرة. أما مسوّدة 1.1.0 غير المكتملة فتضيف أشياء لا تُقبل هنا — منها الفواصل الأخيرة في الجداول السطرية — وذلك عن قصد: فالمحوِّل الذي يقبل مسوّدةً لم يُصدرها أحد سيقرأ براحة ملفاتٍ ترفضها الأدوات الحقيقية.

لماذا هي مجانية؟

التحليل والتحويل كلاهما يجري داخل متصفّحك. فلا يُرفع شيء ممّا تلصقه ولا يُسجَّل ولا يُخزَّن — وإغلاق التبويب هو كل الحذف اللازم. وهذا مهمّ هنا، لأن ملفات الإعدادات هي بالضبط ما يحمل اسم مضيف أو مسارًا أو مفتاحًا تفضّل ألّا تسلّمه لخادم شخص غريب.

بلا حساب، وبلا تسجيل، وبلا حدٍّ لحجم المستند، وبلا علامة مائية على أي شيء تنسخه.