ترحيل التكوين JSON إلى TOML: ما الذي يتم تحويله وما الذي يحتاج إلى إنسان

عصر setup.cfg وsettings.json على وشك الانتهاء - مشروع يدمج التكوين في pyproject.toml والكتل JSON التي تحتاج إلى النقل

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

يتطلب ToolAcre كائنًا جذرًا لإخراج TOML. تم رفض مصفوفة جذر أو سلسلة أو رقم أو قيمة منطقية أو خالية لأن مستند TOML عبارة عن جدول. يمنع فحص الشكل المبكر هذا الغلاف المخترع من الظهور كتكوين معتمد من التطبيق.

يعد دمج التكوين اختيارًا للمشروع، وليس نهاية عامة للتنسيقات القديمة

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

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

ما يثبته هذا المحول حول TOML بدلاً من دعم التنسيق العام

يتم تحويل السلاسل والأرقام المحدودة والقيم المنطقية والكائنات المتداخلة والمصفوفات المدعومة بـ smol-toml ميكانيكيًا. يمكن أن تصبح صفائف الكائنات صفائف من الجداول؛ يمكن أن تصبح الكائنات المتداخلة رؤوس الجدول. يتم اختبار Unicode والخطوط الجديدة المفلتة في رحلات ذهابًا وإيابًا للقيم العادية.

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

ما يتم تحويله ميكانيكيًا، بما في ذلك المصفوفات التي يقبلها الكاتب TOML

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

قرر ما يعنيه null قبل قبول أي تغيير. قد يعني ذلك وراثة افتراضي، أو مسح حقل بشكل صريح، أو عدم توفير أي قيمة. يمكن أن يؤدي حذف المفتاح أو استبدال نص فارغ إلى تغيير دلالات التطبيق، لذا قم بحلها وفقًا لنموذج التكوين الموثق للوجهة.

حيث يحتاج النمط إلى إنسان - الاختيار بين رؤوس [الجدول] والمفاتيح المنقطة والجداول المضمنة وتجميع المفاتيح ذات الصلة حتى تتم قراءة الملف بشكل جيد

لا توضح الشجرة ما إذا كان المشرفون يفضلون `[tool.linter]` أو المفاتيح المنقطة أو الجداول المضمنة. يختار المُسلسل بناء جملة صالحًا، بينما يختار الإنسان التجميع الذي يجعل الملكية والخيارات ذات الصلة واضحة. يمكن لمفاتيح الفرز أن تجعل المخرجات حتمية ولكنها قد تفصل بين المفاهيم التي تنتمي معًا.

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

مثال عملي: تكوين JSON الخاص بـ linter إلى TOML - تحويل القيمتين الفارغتين وحلهما وإعادة تجميع النتيجة تحت رأس [tool.linter]

تحويل `{"tool":{"linter":{"lineLength":100,"preview":null,"exclude":["dist",null]}}}`. تم قبول الكائن الجذر. تم حذف `preview`؛ يصبح عضو الصفيف الفارغ سلسلة فارغة؛ تحذيرات تسمية كلا المسارين. يتم إجراء تسلسل للكائن المتداخل المتبقي ضمن الجداول TOML التي اختارها الكاتب.

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

ما لا يغطيه هذا - ما إذا كانت الأداة المستهدفة تقرأ فعليًا TOML، وأسماء مفاتيحها المحددة، والتي لا يمكن أن تخبرك بها إلا وثائقها

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

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

الخلاصة: قم بالتحويل أولاً، ثم قم بالتحرير لسهولة القراءة - وكيف تقوم لوحة محولات Syntax بالجزء الميكانيكي في متصفحك

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

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

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