ToolDeck

TOML

2 أدوات

TOML إلى JSONتحويل TOML إلى صيغة JSONمنسّق TOMLتنسيق والتحقق من صحة ملفات إعداد TOML

تتيح لك أدوات TOML في ToolDeck تنسيق ملفات إعدادات TOML والتحقق من صحتها وتحويلها مباشرةً في متصفحك — بدون تثبيت، ولا حساب، ولا رفع بيانات إلى أي خادم. يحلّل TOML Formatter مدخلات TOML ويُعيد تسلسلها بمسافة بادئة متسقة، وترتيب موحد للمفاتيح، وأخطاء تحقق مضمّنة تحدد مكان مشكلات بناء الجملة بدقة. أما TOML to JSON Converter فيحول مستندات TOML إلى ما يعادلها في JSON، مع الحفاظ على أنواع البيانات بما فيها التواريخ والأوقات والجداول المضمّنة ومصفوفات الجداول. تعمل كلتا الأداتين بالكامل على جانب العميل، مما يعني أن ملفات الإعداد الخاصة بك — التي كثيراً ما تحتوي على بيانات اعتماد قواعد البيانات ونقاط نهاية API وأسرار النشر — تبقى على جهازك. إذا كنت بحاجة إلى التحويل في الاتجاه العكسي، فإن JSON to TOML Converter الموجود في فئة JSON يتولى ذلك.

ما هي أدوات TOML؟

TOML (اختصار لـ Tom's Obvious, Minimal Language) هو تنسيق ملفات إعداد مبني على بناء جملة صريح وغير مبهم. أنشأه Tom Preston-Werner، أحد مؤسسي GitHub، وصدر للمرة الأولى عام 2013، وبلغ مواصفته 1.0 في يناير 2021. يُربط هذا التنسيق بوضوح بجدول تجزئة: يُعرِّف كل ملف TOML شجرة من أزواج المفتاح-القيمة مُنظَّمة في جداول (أقسام محددة بـ [أقواس مربعة]). على عكس YAML، لا يعتمد TOML على المسافة البادئة لتحديد البنية، مما يُزيل تماماً الفئة الكاملة من أخطاء التحليل المرتبطة بالمسافات البيضاء. وعلى عكس JSON، يدعم TOML التعليقات وأنواع التاريخ/الوقت الأصيلة والسلاسل النصية متعددة الأسطر — وهي ميزات تحتاجها ملفات الإعداد لكن JSON لم يُصمَّم في الأصل لتوفيرها.

تُغني أدوات TOML عن المهام الروتينية المتعلقة بقراءة ملفات TOML والتحقق من صحتها وتحويلها. تُوحِّد أدوات التنسيق المسافة البادئة وترتيب المفاتيح لتبقى ملفات الإعداد قابلة للقراءة من قِبل الفريق بأكمله، حتى حين يحرر عدة مساهمين الملف ذاته. تُترجم أدوات التحويل بين TOML وJSON، وهو أمر مفيد حين تتوقع مكتبة أو واجهة برمجية مدخلات JSON بينما مصدر الحقيقة هو إعداد TOML. يكشف التحقق عن أخطاء بناء الجملة — قوس إغلاق مفقود، أو مفتاح مكرر، أو قيمة تاريخ/وقت غير صالحة — قبل أن تتسبب في فشل التطبيق عند بدء تشغيله.

تظهر هذه المهام بصورة متكررة في مشاريع Rust (حيث يُمثل Cargo.toml بيان الحزمة)، وتغليف Python (إذ حل pyproject.toml محل setup.py كإعداد بناء قياسي في PEP 518 وPEP 621)، والمواقع الساكنة بـ Hugo (التي تستخدم TOML لإعداد الموقع بصورة افتراضية)، وأي إعداد بنية تحتية يُخزِّن الإعداد في ملفات TOML. توثَّق مواصفة TOML على toml.io، وتوجد مُحللات لكل لغة برمجية رئيسية.

لماذا تستخدم أدوات TOML على ToolDeck؟

تُحلِّل أدوات TOML في ToolDeck كل شيء داخل تبويب المتصفح باستخدام JavaScript. لا تُرسَل أي بيانات إعداد إلى خادم، ولا يلزم وجود حساب، وتعمل الأدوات في وضع عدم الاتصال بعد تحميل الصفحة الأولي.

🔒
خصوصية بالإعداد الافتراضي
كثيراً ما تحتوي ملفات الإعداد على قيم حساسة — عناوين URL لقواعد البيانات، ومفاتيح API، وأهداف النشر. تُعالج ToolDeck TOML بالكامل على جانب العميل، لذا لا يغادر شيء متصفحك. آمنة للمشاريع الخاصة وإعدادات البنية التحتية الداخلية.
⚡
ردود فعل فورية
الصق TOML وشاهد المخرجات المنسقة أو JSON فوراً. يتم الإبلاغ عن أخطاء بناء الجملة مع أرقام الأسطر وأوصافها. لا انتظار لتثبيت أداة CLI أو اكتمال خطوة بناء.
🔄
تحويل دقيق للأنواع
يحافظ محول TOML to JSON على الأنواع الخاصة بـ TOML مثل التواريخ والأوقات ذات الإزاحة، والتواريخ المحلية، والأوقات المحلية كسلاسل ISO 8601. تُحفظ دقة الأعداد الصحيحة والأعداد العشرية. تُربط مصفوفات الجداول بشكل صحيح بمصفوفات JSON من الكائنات.
🌐
لا يلزم تثبيت
تعمل على أي جهاز يحتوي على متصفح حديث. مفيدة حين تراجع طلب سحب على جهاز بدون بيئة التطوير المعتادة، أو حين تحتاج إلى التحقق بسرعة من ملف TOML خاص بأحد الزملاء.

حالات استخدام أدوات TOML

تظهر عمليات تنسيق TOML والتحقق منه وتحويله في مختلف الأدوار وأنواع المشاريع. يتعامل مطورو Rust مع Cargo.toml يومياً. يُهيئ مطورو Python عمليات البناء والأدوات عبر pyproject.toml. يُدير مهندسو DevOps إعداد التطبيقات الذي يُشحن بتنسيق TOML. تُظهر المهام أدناه أين توفر أدوات TOML المعتمدة على المتصفح الوقت مقارنةً بكتابة سكريبت لمرة واحدة أو تثبيت أداة CLI.

تنظيف Cargo.toml
بعد دمج عدة إضافات تبعيات، أصبح تنسيق Cargo.toml لمشروع Rust غير متسق. شغّله عبر TOML Formatter لتوحيد المسافة البادئة وترتيب المفاتيح قبل الإيداع.
تحويل pyproject.toml إلى JSON
يحتاج خط أنابيب CI إلى بيانات وصفية للبناء بتنسيق JSON، لكن مصدر الحقيقة هو pyproject.toml. استخدم TOML to JSON Converter لتوليد تمثيل JSON والتحقق من صحة الربط قبل البرمجة النصية للتحويل في خط الأنابيب.
ترحيل الإعداد
نقل تطبيق من إعداد يعتمد على JSON إلى TOML (أو العكس). يتيح لك TOML to JSON Converter مقارنة التمثيلين جنباً إلى جنب للتأكد من الحفاظ على أنواع البيانات والبنى المتداخلة ودلالات المصفوفات.
تصحيح أخطاء بناء الجملة
فشل ملف إعداد TOML في التحليل عند بدء تشغيل التطبيق برسالة خطأ مبهمة. الصقه في TOML Formatter للحصول على أرقام أسطر وأعمدة محددة لخطأ بناء الجملة، مع وصف لما توقعه المُحلل.
توليد التوثيق
كتابة توثيق يتضمن أمثلة إعداد بتنسيقي TOML وJSON. حوّل مثال TOML الأساسي عبر TOML to JSON Converter لتبقى النسختان متزامنتين بدون نسخ يدوي.
تعلم بناء جملة TOML
يستطيع المطورون الجدد على TOML التجريب مع التنسيق بكتابة TOML في TOML Formatter، ورؤية أخطاء التحقق في الوقت الحقيقي، ومقارنة البنية مع المخرجات المنسقة. هذا أسرع من قراءة المواصفات وحدها.

مرجع أنواع بيانات TOML

يُعرِّف TOML v1.0 أنواع البيانات التالية. يُربط كل نوع بتمثيل محدد عند التحويل إلى JSON. يشمل الجدول أدناه بناء الجملة والأمثلة وسلوك التحويل لكل نوع من أنواع TOML.

النوعبناء الجملةمثالربط JSON
String (سلسلة نصية)"..." أو '...'name = "TOML"سلسلة JSON. تدعم السلاسل الأساسية تسلسلات الهروب (\n, \t, \u). تعامل السلاسل الحرفية ('...') الشرطة المائلة العكسية كأحرف حرفية.
Integer (عدد صحيح)digits, 0x, 0o, 0bport = 8080رقم JSON. يدعم النظام السداسي عشر (0xDEAD) والثماني (0o755) والثنائي (0b1010) وفواصل الشرطة السفلية (1_000).
Float (عدد عشري)digits with . or epi = 3.14159رقم JSON. يدعم inf و-inf وnan (يُربط بـ null أو سلسلة في JSON لأن JSON لا يدعم NaN).
Boolean (منطقي)true / falseenabled = trueقيمة منطقية JSON. true وfalse بأحرف صغيرة فقط هما القيمتان الصالحتان.
Offset Date-TimeRFC 33392024-01-15T09:30:00Zسلسلة JSON (ISO 8601). تتضمن إزاحة المنطقة الزمنية. لا يوجد نوع تاريخ/وقت أصيل في JSON.
Local Date-Timedate T time2024-01-15T09:30:00سلسلة JSON. بدون معلومات المنطقة الزمنية. مفيدة لأوقات الساعة الحائطية.
Local DateYYYY-MM-DD2024-01-15سلسلة JSON. تاريخ بدون مكون الوقت.
Local TimeHH:MM:SS09:30:00سلسلة JSON. وقت بدون تاريخ أو منطقة زمنية.
Array (مصفوفة)[value, ...]ports = [8080, 8443]مصفوفة JSON. يمكن أن تكون مصفوفات TOML متغايرة الأنواع في TOML v1.0، لكنها كانت مقيدة بأنواع متجانسة في v0.5.
Table (جدول)tomlCategoryContent.r10Syntax[database]كائن JSON. تستخدم الجداول القياسية [أقواساً مربعة]. تستخدم الجداول المضمّنة أقواساً متعرجة في سطر واحد.

مواصفة TOML v1.0.0 (toml.io) هي الإصدار الثابت الحالي. تستخدم مصفوفات الجداول [[أقواساً مزدوجة]] لتعريف إدخالات جدول متكررة، تُربط بمصفوفات JSON من الكائنات.

كيف تختار أداة TOML المناسبة

تمتلك ToolDeck ثلاث أدوات تعمل مع ملفات TOML. اثنتان منها في فئة TOML، وواحدة في فئة JSON للتحويل في الاتجاه العكسي. اختر الأداة التي تناسب مهمتك.

  1. 1
    إذا كنت بحاجة إلى إعادة ضبط مسافة بادئة في ملف TOML، أو توحيد ترتيب المفاتيح، أو التحقق من صحة بناء جملة TOML مع تقارير أخطاء على مستوى السطر → TOML Formatter
  2. 2
    إذا كنت بحاجة إلى تحويل ملف إعداد TOML إلى JSON للاستخدام في واجهات برمجية أو سكريبتات أو أدوات تتوقع مدخلات JSON → TOML to JSON Converter
  3. 3
    إذا كنت بحاجة إلى تحويل مستند JSON إلى تنسيق TOML للمشاريع التي تستخدم TOML كمعيار إعداد → JSON to TOML Converter

للعمل اليومي مع TOML، يتولى TOML Formatter التنسيق والتحقق في خطوة واحدة — الصق TOML وسيُنتج إما مخرجات نظيفة أو يُخبرك تحديداً بمكان خطأ بناء الجملة. حين تحتاج إلى ربط TOML بـ JSON، يحافظ TOML to JSON Converter على جميع أنواع بيانات TOML بما فيها التواريخ والأوقات والجداول المتداخلة. للتحويل في الاتجاه العكسي (من JSON إلى TOML)، استخدم JSON to TOML Converter في فئة JSON. إذا كنت تصحح أخطاء إعداد يفشل في التحليل، ابدأ بـ TOML Formatter: رسائل خطأه تتضمن أرقام الأسطر وأوصاف الرمز المتوقع، وهي أكثر تحديداً مما تُبلغه معظم مُحللات TOML على مستوى التطبيق.

الأسئلة الشائعة

ما الفرق بين TOML وYAML؟
يستخدم TOML بناء جملة الأقواس المربعة الصريح للجداول ولا يعتمد على المسافة البادئة لتحديد البنية. يستخدم YAML المسافة البادئة لتعريف التسلسل الهرمي، مما يجعله حساساً لأخطاء المسافات البيضاء — مسافة واحدة في مكان خاطئ يمكن أن تُغيّر البنية المُحلَّلة كلياً. يحظر TOML أيضاً المفاتيح المكررة، بينما يستخدم YAML القيمة الأخيرة بصمت حين يظهر مفتاح مرتين. يُفضَّل TOML عموماً لإعداد التطبيقات، بينما YAML أكثر شيوعاً في بيانات Kubernetes وتعريفات خطوط أنابيب CI/CD حيث يكون دعمه للمستندات المتعددة والمراسي/الأسماء المستعارة مفيداً.
ما الفرق بين TOML وJSON؟
JSON هو تنسيق تبادل بيانات مُصمَّم للتواصل بين الآلات. TOML هو تنسيق إعداد مُصمَّم للبشر ليقرأوه ويحرروه. يدعم TOML التعليقات (الأسطر التي تبدأ بـ #)، وأنواع التاريخ/الوقت الأصيلة، والسلاسل النصية متعددة الأسطر، والجداول التي تُقلل عمق التداخل. لا يدعم JSON التعليقات، وليس لديه نوع تاريخ، ويتطلب تداخلاً صريحاً بأقواس متعرجة. JSON هو الاختيار الصحيح لحمولات API وتخزين البيانات؛ أما TOML فهو الاختيار الصحيح لملفات الإعداد التي يحررها البشر يدوياً.
هل يستطيع TOML تمثيل جميع بنى بيانات JSON؟
يستطيع TOML تمثيل معظم بنى JSON، لكن توجد حالات حافة. لا يدعم TOML قيم null — لا يوجد ما يعادل null في JSON بالنسبة لـ TOML. يجب أن تكون مفاتيح TOML سلاسل نصية، وهذا يتطابق مع مفاتيح كائنات JSON. كانت مصفوفات TOML مقيدة بأنواع متجانسة في v0.5، لكن TOML v1.0 يسمح بمصفوفات متغايرة الأنواع. قد تصبح كائنات JSON المتداخلة بعمق مطوّلة في TOML لأن كل مستوى تداخل يتطلب رأس جدول منفصلاً.
أي المشاريع تستخدم TOML للإعداد؟
يستخدم نظام بناء Cargo الخاص بـ Rust ملف Cargo.toml كبيان للحزمة. اعتمدت Python ملف pyproject.toml كملف إعداد البناء القياسي من خلال PEP 518 (2016) وPEP 621 (2020). يستخدم Hugo، مولد المواقع الساكنة، TOML لإعداد الموقع بصورة افتراضية. تستخدم InfluxDB ملف TOML لإعداد الخادم. درس نظام وحدات Go استخدام TOML لكنه اختار تنسيقه الخاص؛ غير أن كثيراً من مشاريع Go لا تزال تستخدم TOML لإعداد مستوى التطبيق عبر مكتبات مثل BurntSushi/toml وpelletier/go-toml.
كيف يتعامل TOML مع التعليقات؟
يدعم TOML التعليقات الكاملة للسطر وتعليقات نهاية السطر باستخدام الرمز #. كل ما يأتي بعد # حتى نهاية السطر يتجاهله المُحلل. لا يمكن أن تظهر التعليقات داخل السلاسل الأساسية متعددة الأسطر أو السلاسل الحرفية متعددة الأسطر. عند تحويل TOML إلى JSON، تُحذف التعليقات لأن JSON لا يدعم بناء جملة التعليقات. هذا يعني أن التحويل الدائري من TOML إلى JSON ثم العودة إلى TOML سيفقد جميع التعليقات من الملف الأصلي.
ما هي مصفوفات الجداول في TOML؟
تستخدم مصفوفات الجداول بناء جملة [[أقواس مزدوجة]] لتعريف إدخالات متكررة لبنية الجدول ذاتها. على سبيل المثال، ظهور [[servers]] مرتين يُنشئ مصفوفة بكائنين من نوع خادم. في JSON، يُربط هذا بمصفوفة من الكائنات. تُستخدم مصفوفات الجداول بكثرة لقوائم التبعيات وتعريفات الخوادم وإعدادات الإضافات حيث يمتلك كل إدخال المجموعة ذاتها من المفاتيح.
هل TOML حساس للمسافات البيضاء؟
TOML ليس حساساً للمسافة البادئة. المسافة البادئة جمالية بحتة ولا تؤثر على التحليل. غير أن TOML يتطلب أسطراً جديدة للفصل بين أزواج المفتاح-القيمة — لا يمكنك وضع زوجين من المفتاح-القيمة في السطر ذاته (باستثناء داخل الجداول المضمّنة). يجب أن تتلاءم الجداول المضمّنة في سطر واحد ولا يمكنها احتواء أسطر جديدة. يتجنب هذا التصميم أخطاء المسافة البادئة الشائعة في ملفات YAML.
ماذا يحدث لقيم تاريخ/وقت TOML عند التحويل إلى JSON؟
لا يوجد في JSON نوع تاريخ/وقت أصيل، لذا تُحوَّل قيم تاريخ/وقت TOML إلى سلاسل ISO 8601. تحتفظ التواريخ والأوقات ذات الإزاحة (مثل 2024-01-15T09:30:00Z) بإزاحة منطقتها الزمنية في تمثيل السلسلة. أما التواريخ والأوقات المحلية والتواريخ المحلية والأوقات المحلية فتُسلسَل كسلاسل بدون معلومات منطقة زمنية. التحويل غير مُفقد للبيانات بمعنى أن القيمة الأصلية يمكن تحليلها من السلسلة، لكن على مستهلك JSON أن يعرف أنه يجب معاملة هذه السلاسل كتواريخ لا كنص عشوائي.