مكتبة json — تحليل وتوليد JSON

مكتبة json توفر أدوات شاملة للتعامل مع صيغة JSON (JavaScript Object Notation) — الصيغة الأكثر استخداماً لتبادل البيانات في التطبيقات الحديثة. تشمل تحليل نصوص JSON إلى كائنات، وتوليد نصوص JSON من البيانات، والتحقق من الصحة، والطباعة المنسّقة.

استورد json من "stdlib/json"

# تحليل JSON
متغير نص_json = '{"الاسم": "أحمد"، "العمر": 25، "المدينة": "مكة"}'
متغير بيانات = json.حلل(نص_json)

اطبع_سطر("الاسم: " + بيانات["الاسم"])
اطبع_سطر("العمر: " + بيانات["العمر"])

# توليد JSON
متغير كائن = {"المنتج": "تمر عجوة"، "السعر": 45.5، "متوفر": صحيح}
متغير ناتج = json.نص(كائن)
اطبع_سطر(ناتج)

ملخص الدوال

الدالة	الوصف	المعاملات
json.حلل(نص)	تحليل نص JSON لكائن	نص JSON
json.نص(كائن)	تحويل كائن لنص JSON	أي كائن
json.نص_منسق(كائن)	تحويل مع تنسيق	كائن + مسافات بادئة
json.صحيح(نص)	التحقق من صحة JSON	نص JSON
json.مصغر(نص)	تصغير (إزالة المسافات)	نص JSON
json.دمج(كائن1، كائن2)	دمج كائنين	كائنان
json.مفاتيح(كائن)	مصفوفة المفاتيح	كائن JSON
json.قيم(كائن)	مصفوفة القيم	كائن JSON

---

دوال التحليل والتوليد

json.حلل(نص) — تحليل نص JSON

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

استورد json من "stdlib/json"

# تحليل بيانات مسجد
متغير نص_المسجد = '{
    "الاسم": "المسجد الحرام"،
    "المدينة": "مكة المكرمة"،
    "السعة": 900000،
    "المآذن": 9،
    "الإحداثيات": {
        "خط_العرض": 21.4225،
        "خط_الطول": 39.8262
    }
}'

متغير المسجد = json.حلل(نص_المسجد)
اطبع_سطر("المسجد: " + المسجد["الاسم"])
اطبع_سطر("السعة: " + لنص(المسجد["السعة"]) + " مصلٍّ")
اطبع_سطر("عدد المآذن: " + المسجد["المآذن"])

json.نص(كائن) — تحويل إلى نص JSON

تحوّل أي كائن أو قيمة إلى نص JSON مضغوط (بدون مسافات زائدة). مفيدة لإرسال البيانات عبر الشبكة أو حفظها في ملفات.

استورد json من "stdlib/json"

# إنشاء بيانات طالب للإرسال عبر API
متغير الطالب = {
    "الاسم": "مريم بنت عمران"،
    "الرقم_الجامعي": "1446023"،
    "التخصص": "علوم الحاسب"،
    "المعدل": 3.85،
    "المواد": ["البرمجة"، "قواعد البيانات"، "الشبكات"]
}

متغير نص_json = json.نص(الطالب)
اطبع_سطر(نص_json)

json.نص_منسق(كائن) — تحويل مع تنسيق

تعمل مثل json.نص لكن تُضيف مسافات بادئة وأسطر جديدة لتسهيل القراءة. مفيدة للعرض والتسجيل والتصحيح.

استورد json من "stdlib/json"

متغير المنتجات = [
    {"الاسم": "سجادة صلاة"، "السعر": 35}،
    {"الاسم": "مصحف"، "السعر": 25}،
    {"الاسم": "سبحة"، "السعر": 10}
]

اطبع_سطر(json.نص_منسق(المنتجات))

json.صحيح(نص) — التحقق من الصحة

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

استورد json من "stdlib/json"

متغير نص_سليم = '{"اسم": "أحمد"}'
متغير نص_خطأ = '{"اسم": "أحمد"'    # قوس ناقص

اطبع_سطر(json.صحيح(نص_سليم))   # صحيح
اطبع_سطر(json.صحيح(نص_خطأ))    # خطأ

---

دوال المعالجة

json.دمج(كائن1، كائن2) — دمج كائنين

تدمج كائنين JSON في كائن واحد. إذا وُجدت مفاتيح مكررة، تأخذ قيم الكائن الثاني الأولوية.

استورد json من "stdlib/json"

متغير الأساسي = {"الاسم": "خالد"، "العمر": 30}
متغير الإضافي = {"المهنة": "مبرمج"، "المدينة": "الرياض"}

متغير الكامل = json.دمج(الأساسي، الإضافي)
اطبع_سطر(json.نص_منسق(الكامل))

json.مفاتيح(كائن) / json.قيم(كائن) — استخراج المفاتيح والقيم

json.مفاتيح تُرجع مصفوفة بجميع المفاتيح (أسماء الخصائص) في كائن JSON. json.قيم تُرجع مصفوفة بجميع القيم.

استورد json من "stdlib/json"

متغير الأشهر_الهجرية = {
    "1": "محرم"،
    "2": "صفر"،
    "3": "ربيع الأول"،
    "7": "رجب"،
    "9": "رمضان"،
    "12": "ذو الحجة"
}

متغير الأرقام = json.مفاتيح(الأشهر_الهجرية)
متغير الأسماء = json.قيم(الأشهر_الهجرية)

اطبع_سطر("عدد الأشهر المسجلة: " + حجم_مصفوفة(الأسماء))
لكل اسم في الأسماء
    اطبع_سطر("  • " + اسم)
نهاية

---

مثال شامل

استورد json من "stdlib/json"

# نظام إدارة مكتبة إسلامية
متغير بيانات_المكتبة = '{
    "اسم_المكتبة": "مكتبة دار السلام"،
    "المدينة": "القاهرة"،
    "الكتب": [
        {
            "العنوان": "رياض الصالحين"،
            "المؤلف": "الإمام النووي"،
            "عدد_الصفحات": 600،
            "التصنيف": "حديث"
        }،
        {
            "العنوان": "تفسير ابن كثير"،
            "المؤلف": "ابن كثير"،
            "عدد_الصفحات": 2400،
            "التصنيف": "تفسير"
        }،
        {
            "العنوان": "فقه السنة"،
            "المؤلف": "سيد سابق"،
            "عدد_الصفحات": 800،
            "التصنيف": "فقه"
        }
    ]
}'

متغير المكتبة = json.حلل(بيانات_المكتبة)
اطبع_سطر("📚 " + المكتبة["اسم_المكتبة"] + " — " + المكتبة["المدينة"])
اطبع_سطر("")

لكل كتاب في المكتبة["الكتب"]
    اطبع_سطر("📖 " + كتاب["العنوان"])
    اطبع_سطر("   المؤلف: " + كتاب["المؤلف"])
    اطبع_سطر("   الصفحات: " + لنص(كتاب["عدد_الصفحات"]))
    اطبع_سطر("   التصنيف: " + كتاب["التصنيف"])
    اطبع_سطر("")
نهاية

# إضافة كتاب جديد وتصديره
متغير كتاب_جديد = {
    "العنوان": "الأذكار"،
    "المؤلف": "الإمام النووي"،
    "عدد_الصفحات": 300،
    "التصنيف": "أذكار"
}

اطبع_سطر("--- كتاب جديد ---")
اطبع_سطر(json.نص_منسق(كتاب_جديد))