محوّل CSV إلى JSON

ما الذي تفعله هذه الأداة

CSV هو ما تسلّمك إياه جداول البيانات وصادرات قواعد البيانات ولوحات التحليلات؛ وJSON هو ما تريده واجهات البرمجة والكود. تحوّل هذه الأداة بينهما في الاتجاهين، داخل متصفحك. الصق CSV لتحصل على مصفوفة JSON — كائنات مفاتيحها من سطر الترويسة، أو مصفوفات بسيطة عندما لا تحتوي البيانات على ترويسة. بدّل الاتجاه لتعود مصفوفة JSON إلى CSV، مع وضع كل قيمة بين علامتي اقتباس بالقدر اللازم تمامًا.

يجري العمل على جهازك، وهذا مهم هنا: CSV هو الصيغة التي تُصدَّر إليها قوائم العملاء والفواتير وخلاصات التحليلات. لا يُرفع أي من ذلك إلى أي مكان.

لماذا لا يكفي التقسيم على الفواصل

الطريقة البديهية لقراءة CSV — تقسيم كل سطر على الفواصل — تنهار مع الملفات الحقيقية، لأن للصيغة آلية هروب. الحقل الموضوع بين علامتي اقتباس مزدوجتين قد يحتوي على الفاصل، أو على علامة اقتباس حرفية تُكتب كعلامتين متتاليتين، بل وحتى على أسطر جديدة، فيمتد السجل الواحد عبر عدة أسطر من الملف. تطبّق هذه الأداة القواعد الفعلية (RFC 4180) بمحلّل يعمل حرفًا حرفًا، فتصل الحالات الثلاث سليمة.

name,note
Grace,"rear admiral, USN"
Ada,"she said ""hello"""
Alan,"two
lines"

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

الفاصل ليس فاصلة في كثير من الأحيان

رغم الاسم، فإن القيم «المفصولة بفواصل» كثيرًا ما لا تكون كذلك. في الإعدادات المحلية التي تكون فيها الفاصلة هي الفاصل العشري — معظم أوروبا القارية — يصدّر Excel بفاصلة منقوطة، لأن 1,50 هناك رقم. وتنتج أدوات قواعد البيانات وسطر الأوامر غالبًا بيانات مفصولة بـ Tab، بينما تفضّل مسارات السجلات الشرطة الرأسية. لصق أحد هذه الملفات في أداة لا تعرف سوى الفاصلة ينتج عمودًا واحدًا عريضًا جدًا: أكثر إحباطات CSV شيوعًا.

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

الترويسات وشكل المخرجات

عند تفعيل «السطر الأول ترويسة»، يوفّر ذلك السطر أسماء المفاتيح وتكون المخرجات مصفوفة كائنات — الشكل الذي تتوقعه كل واجهة برمجة تقريبًا. وعند تعطيله، يصبح كل سطر مصفوفة قيم، وهو ما تريده لملف يبدأ بالبيانات مباشرة.

• السطر الذي يحتوي على حقول أقل من الترويسة يحصل على سلاسل فارغة في الأعمدة الناقصة، بدل مفاتيح قيمتها undefined.
• تُجعل أسماء الترويسة المكررة فريدة (id، id_2، id_3) بدل أن يطمس بعضها بعضًا، فذلك كان سيُسقط أعمدة في صمت.
• خلية الترويسة الفارغة تصبح column_2 وcolumn_3 وهكذا، حتى لا يكون أي مفتاح سلسلة فارغة.
• تُتخطّى الأسطر الفارغة، كما تفعل أدوات الاستيراد في جداول البيانات: فالملف الملصوق ينتهي كثيرًا بسطر جديد شارد، وسطر من القيم الفارغة هناك يبدو كخلل.

تحويل أنواع لا يمكن أن يفقد بيانات

كل حقل في CSV نص. وتحويل نص يبدو رقميًا إلى أرقام JSON هو عادةً المطلوب — لكنه أيضًا الطريقة التي تُدمَّر بها البيانات في صمت. الرمز البريدي 01234 يصبح 1234. ورقم طلب من 20 خانة يصبح عددًا عشريًا مقرَّبًا. وسعر مكتوب 1.50 يفقد صفره الأخير.

القاعدة المستخدمة هنا تتجنب ذلك كله دون قائمة حالات خاصة: لا تتحول القيمة إلى رقم إلا إذا أعادت العودةُ بها إلى نص إنتاجَ الأصل بالضبط. الرقم 42 ينجح فيُحوَّل. و01234 لا ينجح فيبقى نصًا. وكذلك 1.50 و+5 و1e5 وأي عدد صحيح يتجاوز الحد الذي تفقد عنده الأعداد العشرية دقتها. أما السلسلتان true وfalse فتصبحان قيمتين منطقيتين؛ ويبقى الحقل الفارغ سلسلة فارغة بدل أن يصير null، لأن CSV لا يستطيع التعبير عن الفرق بين «لا قيمة» و«قيمة فارغة»، واختراع أحدهما اختراعٌ للمعلومات.

العودة إلى CSV

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

أما القيم التي لا يستطيع CSV تمثيلها — كائن أو مصفوفة متداخلة — فتُكتب على هيئة JSON داخل خليتها بدل تسطيحها أو إسقاطها، فلا يختفي شيء في التحويل. وتصبح null خلية فارغة.