مكتبة filesystem — نظام الملفات

مكتبة filesystem توفر دوالاً شاملة للتعامل مع الملفات والمجلدات: القراءة والكتابة والإلحاق، وإنشاء المجلدات وحذفها، ومعالجة المسارات، والاستعلام عن خصائص الملفات. تدعم ترميز UTF-8 بالكامل مما يتيح التعامل مع أسماء ملفات عربية.

استورد ملفات من "stdlib/filesystem"

# كتابة ملف
ملفات.اكتب_ملف("السلام.txt"، "بسم الله الرحمن الرحيم\nالسلام عليكم")

# قراءة ملف
متغير محتوى = ملفات.اقرأ_ملف("السلام.txt")
اطبع_سطر(محتوى)

# فحص الوجود
إذا (ملفات.موجود("السلام.txt"))
    اطبع_سطر("الملف موجود!")
نهاية

ملخص الدوال

قراءة وكتابة الملفات

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

عمليات المجلدات

الدالة	الوصف
ملفات.أنشئ_مجلد(مسار)	إنشاء مجلد (ومجلدات أب)
ملفات.قائمة_المجلد(مسار)	محتويات مجلد
ملفات.احذف(مسار)	حذف ملف أو مجلد

الاستعلام

الدالة	الوصف
ملفات.موجود(مسار)	هل الملف/المجلد موجود
ملفات.هو_ملف(مسار)	هل هو ملف
ملفات.هو_مجلد(مسار)	هل هو مجلد
ملفات.حجم(مسار)	حجم الملف بالبايت

معالجة المسارات

الدالة	الوصف
ملفات.اسم_الملف(مسار)	اسم الملف فقط
ملفات.المجلد_الأب(مسار)	المجلد الذي يحتويه
ملفات.الامتداد(مسار)	امتداد الملف
ملفات.ربط_مسار(أجزاء...)	دمج أجزاء المسار

---

قراءة وكتابة الملفات

ملفات.اقرأ_ملف(مسار) — قراءة ملف كنص

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

استورد ملفات من "stdlib/filesystem"

# قراءة ملف إعدادات
متغير الإعدادات = ملفات.اقرأ_ملف("إعدادات_التطبيق.txt")
اطبع_سطر(الإعدادات)

# قراءة ملف شعر
متغير القصيدة = ملفات.اقرأ_ملف("قصائد/المعلقات.txt")
اطبع_سطر("طول القصيدة: " + طول(القصيدة) + " حرف")

ملفات.اقرأ_أسطر(مسار) — قراءة ملف كمصفوفة

تقرأ الملف وتُقسّمه إلى مصفوفة من الأسطر. كل عنصر في المصفوفة يمثل سطراً واحداً. مفيدة لمعالجة الملفات سطراً سطراً كملفات CSV أو السجلات.

استورد ملفات من "stdlib/filesystem"

# قراءة قائمة الطلاب سطراً سطراً
متغير الأسطر = ملفات.اقرأ_أسطر("طلاب_الحلقة.txt")

اطبع_سطر("عدد الطلاب: " + حجم_مصفوفة(الأسطر))
متغير رقم = 1
لكل سطر في الأسطر
    اطبع_سطر(رقم + ". " + سطر)
    رقم = رقم + 1
نهاية

ملفات.اكتب_ملف(مسار، محتوى) — كتابة نص إلى ملف

تكتب النص المحدد إلى ملف. إذا كان الملف موجوداً يتم استبدال محتواه بالكامل. إذا لم يكن موجوداً يُنشأ ملف جديد. تدعم النصوص العربية بترميز UTF-8.

استورد ملفات من "stdlib/filesystem"

# حفظ تقرير الحضور
متغير التقرير = "تقرير حضور حلقة التحفيظ\n"
التقرير = التقرير + "التاريخ: 15 رمضان 1446\n"
التقرير = التقرير + "الحاضرون: 25 طالب\n"
التقرير = التقرير + "الغائبون: 3 طلاب\n"

ملفات.اكتب_ملف("تقارير/حضور_رمضان.txt"، التقرير)
اطبع_سطر("تم حفظ التقرير")

ملفات.أضف_إلى_ملف(مسار، محتوى) — إلحاق نص

تُضيف نصاً إلى نهاية ملف موجود دون مسح محتواه السابق. مثالية لملفات السجلات (logs) التي تتراكم فيها البيانات.

استورد ملفات من "stdlib/filesystem"

# تسجيل الأحداث في ملف سجل
دالة سجّل(رسالة)
    متغير سطر = "[1446/09/15] " + رسالة + "\n"
    ملفات.أضف_إلى_ملف("سجل_النظام.log"، سطر)
نهاية

سجّل("بدء تشغيل النظام")
سجّل("تسجيل دخول المستخدم: أحمد")
سجّل("عملية حفظ ناجحة")

---

عمليات المجلدات

ملفات.أنشئ_مجلد(مسار) — إنشاء مجلد

تُنشئ مجلداً جديداً في المسار المحدد. تُنشئ تلقائياً المجلدات الأب إذا لم تكن موجودة (مثل mkdir -p). لا تُرمى رسالة خطأ إذا كان المجلد موجوداً بالفعل.

استورد ملفات من "stdlib/filesystem"

# إنشاء هيكل مجلدات لمشروع
ملفات.أنشئ_مجلد("مشروع_المكتبة/بيانات")
ملفات.أنشئ_مجلد("مشروع_المكتبة/تقارير")
ملفات.أنشئ_مجلد("مشروع_المكتبة/صور")

اطبع_سطر("تم إنشاء هيكل المشروع")

ملفات.قائمة_المجلد(مسار) — محتويات المجلد

تُرجع مصفوفة بأسماء الملفات والمجلدات داخل المسار المحدد. مفيدة لاستعراض محتويات مجلد أو البحث عن ملفات محددة.

استورد ملفات من "stdlib/filesystem"

# عرض ملفات مجلد المشاريع
متغير المحتويات = ملفات.قائمة_المجلد("مشاريع")

اطبع_سطر("محتويات المجلد:")
لكل عنصر في المحتويات
    إذا (ملفات.هو_مجلد("مشاريع/" + عنصر))
        اطبع_سطر("  📁 " + عنصر)
    وإلا
        اطبع_سطر("  📄 " + عنصر)
    نهاية
نهاية

---

الاستعلام

ملفات.موجود(مسار) — التحقق من الوجود

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

استورد ملفات من "stdlib/filesystem"

# التحقق قبل القراءة
متغير المسار = "بيانات/المستخدمين.json"

إذا (ملفات.موجود(المسار))
    متغير البيانات = ملفات.اقرأ_ملف(المسار)
    اطبع_سطر("تم تحميل البيانات")
وإلا
    اطبع_سطر("ملف البيانات غير موجود، سيتم إنشاؤه")
    ملفات.اكتب_ملف(المسار، "[]")
نهاية

ملفات.حجم(مسار) — حجم الملف

تُرجع حجم الملف بالبايتات كعدد صحيح. مفيدة للتحقق من أن الملف ليس فارغاً أو لا يتجاوز حداً معيناً.

استورد ملفات من "stdlib/filesystem"

متغير الحجم = ملفات.حجم("كتاب.pdf")
إذا (الحجم > 1048576)
    اطبع_سطر("حجم الملف: " + (الحجم / 1048576) + " ميغابايت")
وإلا
    اطبع_سطر("حجم الملف: " + (الحجم / 1024) + " كيلوبايت")
نهاية

---

معالجة المسارات

ملفات.اسم_الملف(مسار) / ملفات.المجلد_الأب(مسار) / ملفات.الامتداد(مسار)

مجموعة دوال لتفكيك المسارات واستخراج أجزائها.

استورد ملفات من "stdlib/filesystem"

متغير المسار = "مشاريع/لغة_ص/المصادر/رئيسي.ص"

اطبع_سطر(ملفات.اسم_الملف(المسار))     # "رئيسي.ص"
اطبع_سطر(ملفات.المجلد_الأب(المسار))    # "مشاريع/لغة_ص/المصادر"
اطبع_سطر(ملفات.الامتداد(المسار))       # ".ص"

ملفات.ربط_مسار(أجزاء...) — دمج أجزاء المسار

تدمج أجزاء المسار بفاصل النظام المناسب. أكثر أماناً من الدمج اليدوي لأنها تعالج الفواصل المكررة والنظام المختلف (Windows/Linux).

استورد ملفات من "stdlib/filesystem"

متغير المسار = ملفات.ربط_مسار("بيانات"، "مستخدمين"، "أحمد.json")
اطبع_سطر(المسار)    # "بيانات/مستخدمين/أحمد.json"

---

مثال شامل

استورد ملفات من "stdlib/filesystem"

# نظام أرشفة الفتاوى
اطبع_سطر("=== نظام أرشفة الفتاوى ===")

# إنشاء هيكل الأرشيف
متغير المجلد_الرئيسي = "أرشيف_الفتاوى"
ملفات.أنشئ_مجلد(المجلد_الرئيسي + "/عبادات")
ملفات.أنشئ_مجلد(المجلد_الرئيسي + "/معاملات")
ملفات.أنشئ_مجلد(المجلد_الرئيسي + "/أسرة")

# حفظ فتوى
متغير فتوى = "السؤال: ما حكم صلاة التراويح جماعة؟\n"
فتوى = فتوى + "الجواب: صلاة التراويح سنة مؤكدة، ويجوز أداؤها جماعة أو فرادى.\n"
فتوى = فتوى + "المصدر: فتاوى اللجنة الدائمة\n"

متغير مسار_الفتوى = ملفات.ربط_مسار(المجلد_الرئيسي، "عبادات"، "التراويح.txt")
ملفات.اكتب_ملف(مسار_الفتوى، فتوى)
اطبع_سطر("تم حفظ الفتوى في: " + مسار_الفتوى)

# عرض محتويات الأرشيف
متغير التصنيفات = ملفات.قائمة_المجلد(المجلد_الرئيسي)
اطبع_سطر("التصنيفات المتاحة:")
لكل تصنيف في التصنيفات
    اطبع_سطر("  📂 " + تصنيف)
نهاية