مكتبة xml — تحليل وتوليد XML

مكتبة xml توفر أدوات شاملة للتعامل مع مستندات XML. تشمل تحليل XML من نصوص وملفات، بناء مستندات XML برمجياً، دعم مساحات الأسماء (Namespaces)، استعلامات XPath، أقسام CDATA، والطباعة المنسقة.

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

# تحليل مستند XML
متغير المستند = xml.حلل("<كتاب><عنوان>صحيح البخاري</عنوان></كتاب>")
متغير العنوان = المستند.جذر().عنصر("عنوان").نص()
اطبع_سطر(العنوان)    # صحيح البخاري

ملخص الدوال

تحليل XML

الدالة	الوصف
xml.حلل(نص)	تحليل نص XML إلى مستند
xml.حلل_ملف(مسار)	تحليل ملف XML
xml.صحيح(نص)	التحقق من صحة XML

توليد XML

الدالة	الوصف
xml.مستند(جذر)	إنشاء مستند جديد
xml.عنصر(اسم)	إنشاء عنصر
xml.نص(محتوى)	عقدة نصية

عمليات العناصر

الدالة	الوصف
عنصر.اسم()	اسم العنصر
عنصر.نص()	المحتوى النصي
عنصر.سمة(اسم)	قراءة سمة
عنصر.عيّن_سمة(اسم، قيمة)	تعيين سمة
عنصر.أبناء()	العناصر الفرعية
عنصر.عنصر(اسم)	عنصر فرعي باسمه
عنصر.أضف(عنصر)	إضافة عنصر فرعي

التحويل

الدالة	الوصف
مستند.نص()	تحويل لنص XML
مستند.نص_منسق()	تحويل لنص منسق

---

تحليل XML

xml.حلل(نص) — تحليل نص XML

تُحلل نص XML وتُرجع كائن مستند يمثل شجرة DOM الكاملة. يمكنك التنقل في الشجرة باستخدام دوال العناصر لقراءة البيانات واستخراجها.

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

# تحليل بيانات مكتبة إسلامية بصيغة XML
متغير بيانات_xml = "
<مكتبة اسم=\"مكتبة دار السلام\">
    <كتاب نوع=\"حديث\">
        <عنوان>صحيح البخاري</عنوان>
        <مؤلف>الإمام البخاري</مؤلف>
        <أحاديث>7563</أحاديث>
    </كتاب>
    <كتاب نوع=\"تفسير\">
        <عنوان>تفسير ابن كثير</عنوان>
        <مؤلف>ابن كثير</مؤلف>
        <مجلدات>8</مجلدات>
    </كتاب>
</مكتبة>
"

متغير المستند = xml.حلل(بيانات_xml)
متغير الجذر = المستند.جذر()

اطبع_سطر("المكتبة: " + الجذر.سمة("اسم"))

لكل كتاب في الجذر.أبناء()
    اطبع_سطر("📚 " + كتاب.عنصر("عنوان").نص())
    اطبع_سطر("   المؤلف: " + كتاب.عنصر("مؤلف").نص())
    اطبع_سطر("   النوع: " + كتاب.سمة("نوع"))
    اطبع_سطر("")
نهاية

xml.حلل_ملف(مسار) — تحليل ملف XML

تقرأ ملف XML من القرص وتُحلله إلى مستند.

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

متغير المستند = xml.حلل_ملف("بيانات/كتب_الحديث.xml")
متغير الجذر = المستند.جذر()
اطبع_سطر("عدد الكتب: " + لنص(حجم_مصفوفة(الجذر.أبناء())))

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

تتحقق من أن النص يمثل مستند XML صحيح التركيب. تُرجع صحيح أو خطأ.

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

متغير صحيح1 = xml.صحيح("<كتاب><عنوان>نص</عنوان></كتاب>")
اطبع_سطر("XML صحيح: " + لنص(صحيح1))     # صحيح

متغير صحيح2 = xml.صحيح("<كتاب><عنوان>نص</كتاب>")
اطبع_سطر("XML صحيح: " + لنص(صحيح2))     # خطأ (وسم غير مغلق)

---

توليد XML

xml.مستند(جذر) / xml.عنصر(اسم) — بناء مستند

تُنشئ مستند XML جديد برمجياً. استخدم xml.عنصر() لإنشاء عناصر و أضف() لبناء الشجرة.

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

# بناء مستند XML لجدول حلقات تحفيظ القرآن
متغير الجذر = xml.عنصر("حلقات_تحفيظ")
الجذر.عيّن_سمة("مسجد"، "مسجد الرحمة")

# إضافة حلقة
متغير حلقة1 = xml.عنصر("حلقة")
حلقة1.عيّن_سمة("رقم"، "1")

متغير الاسم = xml.عنصر("اسم_الشيخ")
الاسم.عيّن_نص("الشيخ أحمد العلوي")
حلقة1.أضف(الاسم)

متغير العدد = xml.عنصر("عدد_الطلاب")
العدد.عيّن_نص("15")
حلقة1.أضف(العدد)

متغير الوقت = xml.عنصر("وقت")
الوقت.عيّن_نص("بعد صلاة الفجر")
حلقة1.أضف(الوقت)

الجذر.أضف(حلقة1)

# التحويل لنص XML منسق
متغير المستند = xml.مستند(الجذر)
متغير النتيجة = المستند.نص_منسق()
اطبع_سطر(النتيجة)

الناتج:

<?xml version="1.0" encoding="UTF-8"?>
<حلقات_تحفيظ مسجد="مسجد الرحمة">
  <حلقة رقم="1">
    <اسم_الشيخ>الشيخ أحمد العلوي</اسم_الشيخ>
    <عدد_الطلاب>15</عدد_الطلاب>
    <وقت>بعد صلاة الفجر</وقت>
  </حلقة>
</حلقات_تحفيظ>

---

عمليات العناصر

عنصر.سمة(اسم) / عنصر.عيّن_سمة(اسم، قيمة) — السمات

قراءة وتعيين سمات العنصر. السمات أزواج اسم-قيمة في وسم الفتح.

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

متغير بيانات = "<طالب رقم=\"1001\" مستوى=\"متقدم\">أحمد بن خالد</طالب>"
متغير المستند = xml.حلل(بيانات)
متغير الطالب = المستند.جذر()

اطبع_سطر("الرقم: " + الطالب.سمة("رقم"))
اطبع_سطر("المستوى: " + الطالب.سمة("مستوى"))
اطبع_سطر("الاسم: " + الطالب.نص())

عنصر.أبناء() — العناصر الفرعية

تُرجع مصفوفة بجميع العناصر الفرعية المباشرة للعنصر.

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

متغير بيانات = "
<أصناف_زكاة>
    <صنف>نقود</صنف>
    <صنف>ذهب</صنف>
    <صنف>فضة</صنف>
    <صنف>عروض تجارة</صنف>
    <صنف>ماشية</صنف>
</أصناف_زكاة>
"

متغير المستند = xml.حلل(بيانات)
متغير الأصناف = المستند.جذر().أبناء()

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

عنصر.عنصر(اسم) — عنصر فرعي باسمه

تبحث عن أول عنصر فرعي مباشر بالاسم المحدد.

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

متغير بيانات = "
<مسجد>
    <الاسم>المسجد الحرام</الاسم>
    <المدينة>مكة المكرمة</المدينة>
    <السعة>900000</السعة>
</مسجد>
"

متغير المستند = xml.حلل(بيانات)
متغير المسجد = المستند.جذر()

اطبع_سطر("المسجد: " + المسجد.عنصر("الاسم").نص())
اطبع_سطر("السعة: " + المسجد.عنصر("السعة").نص())

---

مثال شامل

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

# نظام أرشفة مخطوطات إسلامية بصيغة XML
اطبع_سطر("=== أرشيف المخطوطات الإسلامية ===")
اطبع_سطر("")

# بناء سجل المخطوطات
متغير الأرشيف = xml.عنصر("أرشيف")
الأرشيف.عيّن_سمة("مؤسسة"، "مكتبة الملك فهد الوطنية")

# مخطوطة 1
متغير م1 = xml.عنصر("مخطوطة")
م1.عيّن_سمة("رقم"، "MKT-001")

متغير عنوان1 = xml.عنصر("العنوان")
عنوان1.عيّن_نص("الجامع الصحيح — نسخة أصلية")
م1.أضف(عنوان1)

متغير مؤلف1 = xml.عنصر("المؤلف")
مؤلف1.عيّن_نص("الإمام البخاري")
م1.أضف(مؤلف1)

متغير تاريخ1 = xml.عنصر("تاريخ_النسخ")
تاريخ1.عيّن_نص("256 هـ")
م1.أضف(تاريخ1)

الأرشيف.أضف(م1)

# تحويل وعرض
متغير المستند = xml.مستند(الأرشيف)
متغير الناتج = المستند.نص_منسق()
اطبع_سطر(الناتج)
اطبع_سطر("")

# إعادة التحليل والقراءة
متغير المُحلَّل = xml.حلل(الناتج)
متغير الجذر = المُحلَّل.جذر()
اطبع_سطر("المؤسسة: " + الجذر.سمة("مؤسسة"))

لكل مخطوطة في الجذر.أبناء()
    اطبع_سطر("📜 " + مخطوطة.عنصر("العنوان").نص())
    اطبع_سطر("   المؤلف: " + مخطوطة.عنصر("المؤلف").نص())
    اطبع_سطر("   التاريخ: " + مخطوطة.عنصر("تاريخ_النسخ").نص())
نهاية