في المرة الأولى التي عضتني فيها TOML، لم يكن بناء الجملة. لقد كان الترتيب. كان لدي كائن إعدادات JSON من خدمة Node قديمة، وأردت أن يكون config.toml من أجل إعادة كتابة Rust، وفعلت ما يفعله الجميع في المرة الأولى: لقد كتبت الجداول يدويًا. وبعد عشر دقائق، كان المحلل اللغوي يلقي خطأً لم أفهمه، مشيرًا إلى سطر يبدو جيدًا تمامًا. كانت المشكلة هي وجود ثلاثة مفاتيح أسفل أ [table] الرأس الذي ينتمي فوقه. لدى TOML قاعدة لا تتبعها JSON، وبمجرد أن تتعثر عليها، لن تنساها أبدًا.
أنا أبني تولز.ديفلقد قمت بشحن رف طويل من محولات التنسيق هناك، لذلك كتبت محول JSON إلى TOML لإزالة فئة الخطأ بأكملها. إذا قمت بلصق JSON، فستحصل على TOML الذي يتم إعادة تحليله إلى نفس البيانات، ويتم التعامل مع الطلب نيابةً عنك. هذا الدليل هو الشيء الذي كنت أتمنى لو قرأته بعد ظهر ذلك اليوم: ما هو TOML، حيث يختلف JSON وTOML، وكيفية التحويل بينهما دون فقدان أي شيء يهمك.
ليرة تركية؛DR: TOML هو تنسيق تكوين مكتوب تستخدمه Cargo وPoetry وHugo والكثير من أدوات Rust and Go. يعد تحويل JSON إلى TOML أمرًا ميكانيكيًا في الغالب، ولكن هناك ثلاثة أشياء تحتاج إلى حكم: ترتيب الجدول (المفاتيح قبل الجداول الفرعية، دائمًا)، وكيفية كتابة صفائف من الكائنات (صفائف الجداول مقابل الجداول المضمنة)، وما يحدث لـ JSON
null، والتي TOML ليس لديها وسيلة للتعبير عنها. ال محول JSON إلى TOML يجعل الثلاثة جميعًا واضحين ويعمل بالكامل في متصفحك.
ما هو TOML، ولماذا أقوم بتحويل JSON إليه؟
يرمز TOML إلى Tom'؛s لغة واضحة وبسيطة. يُقرأ كملف INI قديم، ولكن على عكس INI، فهو يحتوي على مواصفات حقيقية مع قيم مكتوبة وتواريخ من الدرجة الأولى وقواعد نحوية محددة. هذه المواصفات هي سبب فوزها: تنسيق التكوين الذي يمكن للشخص قراءته في لمحة، وأن الجهاز يوزع بنفس الطريقة في كل مرة، دون أي غموض حول ما إذا كان ذلك ممكنًا port = 8080 هي سلسلة أو رقم. إنه رقم، لأن TOML يقول ذلك.
يمكنك الوصول إلى تحويل JSON إلى TOML عندما يعطيك الجهاز JSON وتريد الأداة TOML. يحدث هذا أكثر مما تعتقد. تقوم واجهة برمجة التطبيقات بإرجاع نقطة الإعدادات كـ JSON وتحتاج إليها pyproject.toml. لديك قديم config.json وأنت تنقل المشروع إلى المكدس الذي يقرأ config.toml. لقد قمت بإنشاء بعض البيانات برمجيًا، وخرجت باسم JSON لأن هذا هو ما JSON.stringify تنتج، والمستهلك هو Cargo أو Hugo أو خدمة Go باستخدام مكتبة TOML. في كل حالة البيانات متطابقة. فقط التسلسل يختلف.
الاتجاه العكسي موجود أيضًا، لكنه مهمة مختلفة. إذا كنت تسير في الاتجاه الآخر، فإن منسق JSON يستحق أن يكون منفتحًا على التحقق من سلامة العقل JSON أولاً، و محول JSON إلى YAML يغطي تنسيق التكوين الشائع الآخر. يدور هذا الدليل حول انتقال JSON إلى TOML.
كيف يقوم المحول بتعيين JSON على TOML؟
لا يوجد سوى عدد قليل من الأشكال في JSON، ولكل منها موطن في TOML. إن فهم التعيين هو معظم فهم الأداة.
جسون كائن يصبح TOML طاولة. كائن المستوى الأعلى هو الجدول الجذر، ولهذا السبب يصر المحول على أن يكون الإدخال كائنًا. تصبح الكائنات المتداخلة [table] الرؤوس ذات مسار منقط، لذلك { "database": { "pool": { "max": 10 } } } يصبح أ [database.pool] القسم مع max = 10 بداخله.
جسون مجموعة من الكائنات يصبح TOML مجموعة من الجداول، مكتوب بين قوسين [[name]] رأس، كتلة واحدة لكل عنصر. هذا هو نمط TOML الاصطلاحي لقائمة السجلات: قائمة الخوادم، وقائمة التبعيات، وقائمة أهداف البناء. كل عنصر يحصل على خاصته [[servers]] كتلة.
كل العددية الخرائط مباشرة. تصبح سلسلة JSON سلسلة TOML أساسية بعلامات اقتباس مزدوجة، مع هروب أحرف التحكم. يصبح رقم JSON عددًا صحيحًا لـ TOML إذا كان رقمًا صحيحًا ويتعويم بخلاف ذلك. يصبح JSON منطقيًا true أو false. هذه هي الحالات السهلة، ولا يخطئ المحول أبدًا.
جسون مجموعة من العددية يصبح مصفوفة TOML مضمنة: ["admin", "editor"] يبقى ["admin", "editor"]. تتم أيضًا كتابة المصفوفات المختلطة والمصفوفات المتداخلة بشكل مضمن، لأن هذا هو المكان الوحيد الذي تناسبه.
لماذا يهم ترتيب المفاتيح كثيرًا في TOML؟
هذه هي القاعدة التي تجذب الجميع، لذا يجدر ذكرها بوضوح. في TOML، داخل أي جدول، يجب أن تظهر جميع أزواج المفاتيح/القيمة الخاصة بهذا الجدول '؛ قبل أي من رؤوس الجدول الفرعي. إذا كتبت أ [server] الرأس، ثم بعض المفاتيح، ثم مفتاح آخر ينتمي إلى الجدول الجذر، يقرأ المحلل اللغوي هذا المفتاح الضال كجزء من [server] بدلاً من ذلك. في أفضل الأحوال، يهبط في المكان الخطأ؛ في أسوأ الحالات، يفشل الملف في التحليل.
ليس لدى JSON مثل هذه القاعدة. في JSON، ترتيب المفاتيح ليس مهمًا حتى، وتختلط الكائنات والكميات القياسية بحرية داخل نفس الأقواس. لذا فإن تحويل JSON إلى TOML الساذج الذي يوجه الكائن بترتيب الإدراج وينبعث كل مفتاح أثناء سيره سينتج TOML مكسورًا في اللحظة التي يتبع فيها العدد العددي كائنًا متداخلًا.
يحل المحول ذلك عن طريق إجراء تمريرتين فوق كل جدول. أولاً، يقوم بإصدار جميع المفاتيح البسيطة والكميات القياسية والمصفوفات المضمنة. عندها فقط يتم إصدار رؤوس الجدول الفرعي ومصفوفة الجداول، وتتكرر في كل منها. يتم الحفاظ على ترتيب المفاتيح الخاص بك داخل كل مجموعة، وهو ما تريده، ولكن إعادة الترتيب المطلوبة بين المجموعتين تحدث تلقائيًا. ليس عليك أبدًا التفكير في الأمر، ولن تحصل أبدًا على الخطأ الذي حصلت عليه.
متى يجب أن تكون مصفوفات الكائنات جداول مقابل مضمنة؟
هذا هو الاختيار الحقيقي الوحيد. يمكن كتابة مجموعة من الكائنات بطريقتين في TOML، وكلاهما صالح.
الأول هو مجموعة من الجداول، نموذج القوس المزدوج. إنه مطول وقابل للقراءة، كتلة واحدة لكل سجل، وهذا هو الشكل الذي يبدو عليه معظم TOML في البرية. إذا كنت قد رأيت Cargo.toml مع عدة [[bin]] الإدخالات، لقد رأيت هذا.
[[servers]]
name = "web"
ip = "10.0.0.1"
[[servers]]
name = "api"
ip = "10.0.0.2"
والثاني هو الجدول المضمن داخل مصفوفة عادية، والتي تحزم كل كائن في سطر واحد.
servers = [
{ name = "web", ip = "10.0.0.1" },
{ name = "api", ip = "10.0.0.2" },
]
كلاهما ذهابًا وإيابًا لنفس البيانات. أيهما تريد يعتمد على الهدف وعلى الذوق. مصفوفات الجداول التي يمكن قراءتها بشكل أفضل للسجلات التي سيقوم الإنسان بتحريرها، وهي التقليد لمعظم تكوين الأدوات. الجداول المضمنة أكثر إحكاما وأقرب إلى شكل JSON الأصلي، والذي يفضله بعض الأشخاص عندما تكون القائمة قصيرة أو تكون الكائنات صغيرة. يقوم المحول افتراضيًا بتحويل صفائف الجداول ويمنحك التبديل للتبديل. إذا لم تكن متأكدًا، فاتركه في الوضع الافتراضي: هذا هو الشكل الذي يبدو عليه ملف TOML عادةً.
ماذا يحدث لـ JSON null في TOML؟
TOML ليس له قيمة فارغة. لا توجد كلمة رئيسية، ولا قيمة فارغة، ولا شيء. هذا قرار تصميم متعمد من خلال التنسيق، وهو المكان الوحيد الذي يكون فيه JSON to TOML ضائعًا حقًا.
لذلك يجب على المحول أن يقوم بالاختيار، ويتيح لك القيام بذلك. افتراضيا، المفتاح الذي قيمته null يتم إسقاطها، وتقوم الأداة بإدراج المفاتيح المسقطة في ملاحظة أسفل الإخراج بحيث لا يختفي أي شيء بصمت. إذا كنت تفضل الاحتفاظ بالمفتاح، فيمكنك التبديل إلى كتابة null كسلسلة فارغة، مما يحافظ على المفتاح على حساب تغيير نوعه. ولا مثالي، لأنه لا توجد إجابة مثالية. ما يهم هو أن الاختيار مرئي وليس مدفونًا.
يتم دائمًا إسقاط القيم الخالية داخل المصفوفات، مع تحذير، لأن مصفوفة TOML لا يمكن أن تحتوي على قيمة فارغة على الإطلاق. إذا كان JSON الخاص بك لديه [1, null, 3]، سوف يكون TOML [1, 3] وستخبرك الأداة أنها أزالت واحدًا. إذا كانت هذه القيم الخالية تحمل معنى، فهذه إشارة لإعادة تشكيل البيانات قبل التحويل وليس بعده.
لماذا فقد رقمي رقمه العشري، أو حصل على واحد؟
هذا يفاجئ الأشخاص الذين يهتمون بالأنواع. JSON لا يميز 5 من 5.0. كلاهما يحللان نفس IEEE 754 المزدوج، وبحلول ذلك الوقت JSON.parse تم الانتهاء من عدم وجود أثر للصفر الزائد. لذلك عندما يرى المحول الرقم 5ليس من الممكن أن تعرف أنك تقصد العوامة، ومنذ ذلك الحين 5 هو رقم صحيح يكتب عددًا صحيحًا TOML.
من ناحية أخرى، يميز TOML الأعداد الصحيحة عن العوامات، وتهتم بعض الأدوات بالفرق. إذا كنت بحاجة إلى قيمة مكتوبة على شكل عوامة، فإن الإصلاح هو إعطائها جزءًا كسريًا في المصدر 5.1 أو 5.0 مكتوبة بطريقة باقية، أو لتحرير القيمة المفردة بعد التحويل. إنه تغيير بحرف واحد وهو أمر نادر، ولكن من المفيد معرفة سبب حدوثه بدلاً من افتراض أن المحول خاطئ. هذا ليس خطأ. قامت JSON ببساطة بإلقاء المعلومات بعيدًا قبل أن يراها المحول.
تظهر الحالة العكسية بأرقام كبيرة جدًا أو صغيرة جدًا، حيث JavaScript'؛s String() ينتج تدوين الأس مثل 1e+21. يقبل TOML ذلك باعتباره عائمًا، لذا فهو يتحول بشكل جيد، لكن شكل الرقم قد يبدو مختلفًا عما كتبته. مرة أخرى، القيمة متطابقة؛ تم تغيير العرض فقط.
كيف تعمل المفاتيح العارية والمقتبسة؟
يتيح TOML كتابة المفتاح بدون أحرف إذا كان مكونًا فقط من أحرف وأرقام وشرطات سفلية وشرطات. يجب اقتباس أي شيء آخر، مفتاح به نقطة، مسافة، شرطة مائلة، حرف Unicode. يتحقق المحول من كل مفتاح ويقتبس فقط المفاتيح التي تحتاج إليه، لذلك user-name يبقى عاريا و "user.name" يحصل على علامات اقتباس لإيقاف قراءة النقطة كمسار جدول. ليس عليك التفكير في هذا، ولكن إذا رأيت علامات اقتباس حول مفتاح في الإخراج، فهذا هو السبب: يحتوي المفتاح على حرف من شأنه أن يغير معناه.
مثال عملي
فيما يلي عينة من أحمال الأداة، حتى تتمكن من رؤية كل قاعدة في وقت واحد. JSON:
{
"title": "Toolz config",
"version": 2,
"enabled": true,
"owner": { "name": "Liton", "roles": ["admin", "editor"] },
"database": { "host": "localhost", "port": 5432, "pool": { "min": 2, "max": 10 } },
"servers": [
{ "name": "web", "ip": "10.0.0.1" },
{ "name": "api", "ip": "10.0.0.2" }
]
}
يصبح TOML حيث تأتي الكميات القياسية الجذرية أولاً، وتصبح الكائنات المتداخلة جداول منقطة بالترتيب، وتصبح مجموعة الخوادم اثنين [[servers]] كتل:
title = "Toolz config"
version = 2
enabled = true
[owner]
name = "Liton"
roles = ["admin", "editor"]
[database]
host = "localhost"
port = 5432
[database.pool]
min = 2
max = 10
[[servers]]
name = "web"
ip = "10.0.0.1"
[[servers]]
name = "api"
ip = "10.0.0.2"
لاحظ أن title، version و enabled تتم كتابتها قبل أي رأس، roles يظل مصفوفة مضمنة لأنه عبارة عن مصفوفة من السلاسل، و [database.pool] يجلس تحت [database] كمسار منقط. كل قاعدة في هذا الدليل مرئية في تسعة أسطر من الإخراج.
ما هي الأداة التي يتم التحويل لها؟
TOML هو تنسيق واحد في العائلة، وتعتمد الأداة الصحيحة على المكان الذي تبدأ فيه وتنتهي فيه. وإليك كيف أفكر في ذلك.
| لديك | تريد | يستخدم |
|---|---|---|
| JSON | تكوين TOML | JSON إلى TOML |
| JSON | تكوين YAML | JSON إلى YAML |
| YAML | JSON | YAML إلى JSON |
| JSON | XML | json إلى xml |
| فوضوي JSON | Json للقراءة | منسق JSON |
النمط هو أن تنسيقات التكوين عبارة عن طرق عرض قابلة للتبديل لنفس البيانات، ويتم تسمية المحول الذي تريده على اسم الاتجاه الذي تتجه إليه. تعبر كل من TOML وYAML وJSON عن بيانات المفتاح/القيمة المتداخلة؛ الفرق هو أي أداة تقرأها أداتك المستهدفة.
هل من الآمن تحويل ملف التكوين عبر الإنترنت؟
ملفات التكوين هي بالضبط نوع الأشياء التي يجب أن تكون حذرًا بشأن لصقها في موقع ويب، لأنها غالبًا ما تحتوي على سلاسل اتصال ورموز مميزة وأسرار أخرى. ال محول JSON إلى TOML يعمل بالكامل في متصفحك. يتم تحليل JSON الذي تقوم بلصقه في الذاكرة على جهازك، ويتم إنتاج TOML هناك، ولا يتم إرسال أي شيء إلى الخادم، أو كتابته إلى سجل، أو تخزينه. يمكنك مشاهدة هذا بنفسك: افتح علامة تبويب الشبكة، وقم بتشغيل التحويل، وشاهد عدم خروج أي طلب. كما أنه يستمر في العمل بدون اتصال بمجرد تحميل الصفحة، وهو الدليل العملي على أن العمل محلي. إذا كنت تهتم بمكان وصول بياناتك، ومع ملف التكوين، فيجب عليك ذلك، فهذه هي الخاصية المهمة. إنه نفس المبدأ وراء كل أداة على الموقع، والسبب الذي جعلني أكتب عنها مطولاً في الملاحظة الموجودة خصوصية البيانات في الأدوات عبر الإنترنت.
حيث يتناسب هذا مع سير العمل الحقيقي
نادرا ما يكون تحويل التنسيق هو المهمة بأكملها. إنها خطوة. تقوم بسحب كائن الإعدادات من واجهة برمجة التطبيقات، وتحوله، وتسقطه في مشروع. تكمن قيمة المحول من جانب العميل في أنه يدخل في هذا التدفق دون احتكاك: لا تحميل، ولا حساب، ولا انتظار على الخادم، ولا أتساءل عما إذا كانت أسرارك موجودة الآن في سجلات شخص ما '؛s. وهذا هو نفس السبب الذي يجعلني أحتفظ بالكل تولز.ديف قم بتعيين جانب العميل، وهو موضوع أعود إليه في أدوات إنتاجية المطور الكتابة، لأن الأدوات التي تصل إليها عشرين مرة في اليوم هي تلك التي تضيف فيها رحلة ذهابًا وإيابًا مدتها ثانيتان وسؤال الخصوصية.
حصل TOML على مكانه في هذا التدفق من خلال كونه مملًا بأفضل طريقة. إنه يوزع نفس الشيء في كل مكان، ويقرأ جيدًا، وحافته الحادة الوحيدة، وهي قاعدة الترتيب، هي بالضبط نوع الشيء الذي يجب على المحول حفظه لك. الصق JSON الخاص بك، واختر الطريقة التي تريد بها التعامل مع المصفوفات والأصفار، وانسخ TOML الذي يعمل فقط.
الأسئلة المتداولة
كيف يمكنني تحويل JSON إلى TOML؟
الصق كائن JSON الخاص بك في المحول وانقر فوق تحويل. تقوم الأداة بتسلسل الكائنات إلى جداول TOML، ومصفوفات الكائنات إلى مصفوفات الجداول، وكل قيمة أخرى مضمنة، ثم تمنحك TOML قياسيًا للنسخ. يجب أن يكون JSON ذو المستوى الأعلى كائنًا، لأن مستند TOML يكون دائمًا جدولًا.
ما هي استخدامات تومل؟
TOML هو تنسيق ملف تكوين مصمم ليكون سهل القراءة ولا لبس فيه للتحليل. إنه تنسيق التكوين لـ Rust'؛s Cargo (Cargo.toml)، وتغليف Python (pyproject.toml)، وHugo، والعديد من أدوات Go وRust. يقوم الأشخاص بتحويل JSON إلى TOML لتسليم التكوين الذي تم إنشاؤه آليًا إلى أداة تتوقع TOML.
ماذا يحدث لقيم JSON الفارغة في TOML؟
لا يحتوي TOML على نوع فارغ، لذلك لا يمكن تمثيل JSON null مباشرة. افتراضيًا، يقوم هذا المحول بإسقاط المفاتيح الفارغة وإضافة ملاحظة تدرجها؛ يمكنك التبديل إلى كتابتها كسلاسل فارغة بدلاً من ذلك. يتم دائمًا إسقاط المصفوفات الفارغة الداخلية، لأن مصفوفة TOML لا يمكن أن تحتوي على قيمة فارغة.
ما الفرق بين مجموعة من الجداول والجدول المضمن؟
تستخدم مجموعة من الجداول رؤوسًا مزدوجة الأقواس متكررة، كتلة واحدة لكل سجل، وهي طريقة TOML الاصطلاحية لكتابة قائمة من الكائنات مثل قائمة الخوادم أو التبعيات. يقوم الجدول المضمن بتعبئة كائن في سطر واحد كمجموعة من المفاتيح التي تساوي أزواج القيمة بين قوسين. يتم تعيين هذه الأداة افتراضيًا على صفائف من الجداول ولكنها تتيح لك اختيار مضمنة بدلاً من ذلك.
لماذا أصبح رقم JSON 5.0 الخاص بي 5 في TOML؟
لا يحافظ JSON على الفرق بين 5 و5.0، لذا يقرأ التحليل كلاهما بالرقم 5. نظرًا لأن 5 رقم صحيح، فإن المحول يكتبه كعدد صحيح TOML. إذا كنت بحاجة إلى كتابته كتعويم، فأضف جزءًا كسريًا في المصدر أو قم بتحرير القيمة المفردة بعد التحويل.
هل يحافظ المحول على طلب المفتاح الخاص بي؟
نعم. يتم إصدار المفاتيح بالترتيب الذي تظهر به في JSON، مع إعادة ترتيب واحدة مطلوبة: داخل كل جدول، تتم كتابة المفاتيح العادية قبل أي رؤوس جدول فرعي أو مصفوفة من الجداول. هذه قاعدة بناء جملة TOML، وليست خيار إعادة ترتيب، وبدونها لن يقوم الملف بالتحليل.
هل تم تحميل json الخاص بي على خادم؟
لا. يحدث التحويل بالكامل في متصفحك باستخدام JavaScript عادي. لا يتم أبدًا نقل JSON الخاص بك، بما في ذلك أي أسرار أو بيانات اعتماد في ملف التكوين، أو تسجيله أو تخزينه، ويستمر المحول في العمل بدون اتصال بمجرد تحميل الصفحة.
لماذا يقول أن المستوى الأعلى يجب أن يكون كائنًا؟
يتم تعريف مستند TOML على أنه جدول، مما يعني أنه يجب أن يبدأ من مجموعة من أزواج المفاتيح/القيمة. لا تحتوي مصفوفة JSON العارية أو العددية على جدول يمكن التعيين عليه. قم بتغليفه في كائن أولاً، على سبيل المثال، وضع المصفوفة الخاصة بك تحت مفتاح مسمى، وسيتم تحويله.
