كيف تصبح جداول TOML كائنات JSON: [جدول] و[[صفيف]] ومفاتيح منقطة

من أين جاء التعشيش؟ — ملف TOML ذو مظهر مسطح تم تحويله إلى ملف JSON متداخل بعمق، والعناوين التي تسببت في ذلك

يمكن أن يظهر ملف TOML مسطحًا تقريبًا لأن الأقواس تحمل التداخل. `[a.b.c]` يفتح الجداول المتوسطة، لذا يصبح `d = 1` أسفله `{"a":{"b":{"c":{"d":1}}}}`. تجعل الأقواس JSON التسلسل الهرمي مرئيًا والذي يعبر عنه TOML من خلال مسار الجدول النشط.

ToolAcre يقوم بتفويض تحليل بناء الجملة إلى smol-toml ثم يقوم بتطبيع القيم التي لا يمكن لـ JSON حملها. هذه ليست إعادة كتابة على أساس الخط. تصبح الجداول والمفاتيح المنقطة ومصفوفات الجداول كائنات ومصفوفات عادية قبل تسلسل JSON، ولهذا السبب لا تتوفر هجاءها وتعليقاتها في الإخراج.

رؤوس [الجدول] - كيف يفتح الرأس كائنًا متداخلاً وكيف يقوم [a.b.c] بإنشاء كائنات وسيطة ضمنيًا

يفتح رأس القوس المفرد الجدول. `[owner]` يوجه المهام التالية إلى `owner`؛ `[owner.contact]` يقوم بإنشاء أو إدخال كائن الاتصال المتداخل. لا تحتاج الكائنات الوسيطة إلى رؤوس منفصلة. يأتي وجودها من مقاطع المسار الموجودة في الرأس.

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

[[صفيف الجداول]] - لماذا يقوم الرأس المزدوج المتكرر بإلحاق كائنات بمصفوفة، والترتيب الذي يحافظ عليه

يقوم الرأس ذو القوس المزدوج بإلحاق جدول بمصفوفة. يصبح القسمان `[[server]]` `server: [{...},{...}]` بترتيب المصدر. تنتمي الحقول الموجودة أسفل كل رأس إلى عضو الصفيف هذا حتى يبدأ رأس آخر، مما يجعل التكوين المتكرر واضحًا في JSON.

الترتيب داخل المصفوفة عبارة عن بيانات ويتم الحفاظ عليه. قد يتم فرز عرض مفتاح الكائن لاحقًا عند تحديد الخيار، ولكن لا يتم إعادة ترتيب أعضاء المصفوفة أبدًا. قد يؤدي الخلط بين الاثنين إلى تغيير أولوية الخادم أو تسلسل البرنامج المساعد بدلاً من مجرد تنسيق المستند.

المفاتيح المنقطة والجداول المضمنة — a.b = 1 و { x = 1 } طريقتان أخريان للتعبير عن نفس التداخل

توفر التعيينات المنقطة تدوينًا آخر للمسار: `a.b.c = true` ينتج عنه نفس شكل الكائن المتداخل مثل رؤوس الجدول المقابلة. تصبح الجداول المضمنة مثل `point = { x = 1, y = 2 }` كائنات متداخلة على الفور. يمكن أن تصف هذه النماذج أشجارًا متشابهة بينما تبدو مختلفة تمامًا بالنسبة للمراجع.

يقوم JSON بتسجيل المفاتيح والقيم الناتجة فقط، وليس الترميز TOML الذي قام بتأليفها. لذلك لا يمكن للتحويل مرة أخرى استعادة الاختيار الأصلي بين الرؤوس والمفاتيح المنقطة والجداول المضمنة. يختار الكاتب TOML التسلسل الصحيح الخاص به من الشجرة.

الأنواع التي يتم ترحيلها والأنواع التي لا يتم ترحيلها - يتم تعيين الأعداد الصحيحة والعوامات والقيم المنطقية والسلاسل مباشرةً؛ تصبح أوقات التاريخ سلاسل وJSON فارغة لا تحتوي على TOML مصدر

يتم تعيين السلاسل والأعداد الصحيحة الآمنة والعوامات والقيم المنطقية والمصفوفات والجداول مباشرةً. الأنواع الزمنية الأربعة لـ TOML لا تصبح: سلاسل المصدر الشبيهة بـ RFC 3339، والتاريخ المحلي والوقت المحلي والتاريخ المحلي والتوقيت المحلي، ويسمى التحذير كل مسار ونوع. يقتبس الكاتب لاحقًا تلك السلاسل بدلاً من إعادة إنشاء الرموز المميزة للتاريخ والوقت.

يمكن أن تتجاوز الأعداد الصحيحة ذات البتات TOML 64 نطاق الأعداد الصحيحة الآمنة لـ JavaScript. يقوم smol-toml بإرجاع قيم مثل BigInt عند الحاجة؛ ToolAcre يحولها إلى سلاسل عشرية ويحذر بدلاً من تقريب الأرقام. يؤدي هذا إلى الحفاظ على التدقيق الإملائي على حساب تغيير النوع JSON.

مثال عملي: تم تحويل قائمة pyproject.toml — [مشروع] و[project.optional-تبعيات] وقائمة [[tool.plugins]] إلى JSON مع تتبع كل مستوى

حاول `name = "demo"`، `[project]`، `dependencies = ["a", "b"]`، `[project.optional]`، `test = ["vitest"]`، ثم جدولين `[[tool.plugins]]` بأسماء مميزة. JSON يضع الاسم في الجذر، ويتداخل المشروع واختياريًا، وينتج مصفوفة مكونات إضافية أسفل الأداة.

أضف `released = 1979-05-27` و`huge = 9223372036854775807`. الأول يصبح السلسلة `1979-05-27`؛ ويصبح الثاني سلسلة عشرية. يحدد كلا التحذيرين المسارات التي تم تغييرها، مما يجعل الأنواع غير JSON قابلة للمراجعة بدلاً من السماح بإجبار التاريخ أو الرقم الصامت.

ما لا يغطيه هذا - تحويل JSON مرة أخرى إلى TOML الاصطلاحية مع تجميع رؤوس معقول، والذي يتضمن اختيارات النمط التي لا تحددها أي قاعدة بشكل كامل

JSON-to-TOML مدعوم للكائن الجذر، ولكنه لا يعيد إنشاء اختيارات المؤلف الاصطلاحية أو تعليقاته. يتم حذف المفاتيح ذات القيمة الخالية؛ null داخل المصفوفة يصبح سلسلة فارغة للحفاظ على المواضع. يتم رفض المصفوفة الجذرية أو العددية أو الخالية لأن المستند TOML يجب أن يكون جدولاً.

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

كتابة JSON مرة أخرى إلى TOML مدعومة، ولكن لا يتم إرجاع التعليقات وأنواع التاريخ والوقت وأسلوب المؤلف

اقرأ الرؤوس TOML كمسارات والأقواس المزدوجة كعمليات إلحاق. يُعد العرض JSON مفيدًا لتتبع الشجرة الناتجة، بينما تعرض التحذيرات أوقات التاريخ والأعداد الصحيحة العريضة التي تعبر حدود النوع. لا تستدعي العملية بدون فقدان البيانات عند ظهور أي تحذير.

لترحيل التكوين، احتفظ بالأصل بجانب المخرجات المحولة. تحقق من القيم أولاً، ثم قم بتحرير مؤسسة TOML للقراء والأداة المستهدفة. تقوم محولات بناء الجملة بتنفيذ خطوة التحليل والكتابة الميكانيكية؛ لا يمكنه تحديد التجميع الخاص بالمشروع أو المفاتيح المقبولة أو ما إذا كان التطبيق يدعم هذا الملف.

يجب أن تفصل المقارنة النهائية بين ثلاثة أسئلة يسهل خلطها معًا. أولاً، هل نجت القيم التي تم تحليلها؟ ثانيًا، هل أصبح أي نوع TOML فقط عبارة عن سلسلة JSON أو اختفى أي نوع فارغ؟ ثالثًا، هل تم تنظيم TOML المتسلسل حديثًا بطريقة يمكن للمشرف أن يفهمها؟ يمكن التحقق من الأولين مقابل القيم والتحذيرات؛ والثالث يحتاج إلى مراجعة بشرية. يؤدي الاحتفاظ بهذه الشيكات منفصلة إلى منع تسمية التسلسل الصحيح تقنيًا بالترحيل الصحيح عند تغيير أنواعه أو هيكله التأليفي.