أول لغة برمجة نُظُم مُصرَّفة بصياغة عربية

اكتب تطبيقات أصلية على ويندوز ولينكس باستخدام كلمات مفتاحية وأرقام وعلامات ترقيم عربية

---

حالة الإصدارات

• v0.3.8 — Testing & Quality Assurance ✅ مكتمل (2026-02-25)
• v0.3.9 — Advanced Arrays & String Operations ✅ مكتمل (2026-02-25)
• v0.3.10 — Pointers & References ✅ مكتمل (2026-02-25)
• v0.3.10.5 — Type Casting (تحويل الأنواع) ✅ مكتمل (2026-02-27)
• v0.3.10.6 — Function Pointers (مؤشرات الدوال) ✅ مكتمل (2026-02-28)
• v0.3.11.0 — Dynamic Memory (الذاكرة الديناميكية) ✅ مكتمل (2026-03-01)
• v0.3.12.0 — File I/O (إدخال/إخراج الملفات) ✅ مكتمل (2026-03-02)
• v0.3.12.5 — CLI Args + Custom Startup (سطر الأوامر + نقطة دخول مخصّصة) ✅ مكتمل (2026-03-02)
• v0.4.0.0 — Formatted I/O (الإخراج/الإدخال المنسّق) ✅ مكتمل (2026-03-02)
• v0.4.0.5 — Variadic Functions (دوال متغيرة المعاملات) ✅ مكتمل (2026-03-02)
• v0.4.0.6 — Inline Assembly (المجمع المدمج) ✅ مكتمل (2026-03-02)
• v0.4.1.0 — Standard Library (المكتبة القياسية) ✅ مكتمل (2026-03-02)
• v0.4.2.0 — Floating Point Extensions (توسعات الفاصلة العائمة) ✅ مكتمل (2026-03-02)
• v0.4.3.0 — Error Handling (معالجة الأخطاء) ✅ مكتمل (2026-03-02)
• v0.4.4.0 — Final Polish (الضبط النهائي) ✅ مكتمل (2026-03-02)
• v0.4.4.1 — Include Paths & Version Sync (مسارات التضمين وتوحيد الإصدار) ✅ مكتمل (2026-03-02)

---

المزايا

الميزة	الوصف
تصريف أصلي	تُصرِّف الشيفرة إلى ملف تجميع (.s) لمعمارية x86-64 ثم تُنتج ملفات تنفيذية أصلية (ويندوز: PE/COFF، لينكس: ELF)
تعدد الأهداف	دعم هدفين: x86_64-windows (COFF) و x86_64-linux (ELF) مع خيار --target
صياغة عربية كاملة	كلمات مفتاحية عربية، وأرقام (٠-٩)، وعلامات ترقيم (. ؛)
شيفرة معيارية	#تضمين، تصريف متعدد الملفات، وملفات ترويسة .baahd
المعالج القبلي	#تعريف، #إذا_عرف، #الغاء_تعريف
الدوال	تعريف الدوال واستدعاؤها مع معاملات وقيم إرجاع
المصفوفات	مصفوفات ثابتة الحجم أحادية/متعددة الأبعاد (محلية/عامة/ساكنة) مع تهيئة {...} (جزئية + تعبئة بالأصفار)
أنواع مركبة	تعداد + هيكل + اتحاد مع الوصول للأعضاء عبر : (يدعم التعشيش)
مؤهّلات الأنواع	ثابت (const) للثوابت، ساكن (static) لمدة التخزين الساكنة
تدفّق التحكّم	إذا/وإلا، طالما، لكل
تحكّم متقدّم	اختر، حالة، افتراضي، توقف، استمر
المعاملات	معاملات حسابية ومقارنة ومنطقية مع تقييم قصير
النصوص والمحارف	ثوابت السلاسل ("...") وثوابت المحارف ('...') + نوع حرف UTF-8 + دوال طول_نص/قارن_نص/نسخ_نص/دمج_نص/حرر_نص
أحجام أعداد صحيحة	ص٨/ص١٦/ص٣٢/ص٦٤ و ط٨/ط١٦/ط٣٢/ط٦٤ مع ترقيات/تحويلات على نمط C
الأعداد العشرية	نوع عشري (f64) يدعم + - * / والمقارنات والطباعة مع توافق ABI على ويندوز/لينكس
عمليات منخفضة المستوى	دعم & و`
المؤشرات (v0.3.10)	تعريف مؤشرات عامة + & (عنوان) + * (فك الإشارة) + عدم كمؤشر فارغ + إسناد عبر المؤشر *م = قيمة + حساب مؤشري (pointer +/- int وpointer - pointer)
التحويل الصريح (v0.3.10.5)	صيغة كـ<النوع>(التعبير) للتحويلات العددية (int/float/char) وتحويلات المؤشرات (pointer <-> pointer, pointer <-> int)
مؤشرات الدوال (v0.3.10.6)	نوع دالة(...) -> ... للمتغيرات/المعاملات + إسناد مرجع دالة (عملية = جمع.) + نداء غير مباشر عبر معرّف (عملية(١،٢).) + عدم كمؤشر دالة فارغ
الذاكرة الديناميكية (v0.3.11.0)	حجز_ذاكرة/تحرير_ذاكرة/إعادة_حجز/نسخ_ذاكرة/تعيين_ذاكرة مع خفض مباشر إلى libc واحترام shadowing
ملفات (v0.3.12.0)	فتح_ملف/اغلق_ملف/اقرأ_ملف/اكتب_ملف/اقرأ_حرف/اكتب_حرف/اقرأ_سطر/اكتب_سطر/نهاية_ملف/موقع_ملف/اذهب_لموقع باستخدام عدم* كمقبض FILE*
إخراج/إدخال منسّق (v0.4.0.0+)	اطبع_منسق/نسق/اقرأ_منسق/اقرأ_سطر()/اقرأ_رقم() مع مواصفات عربية مثل %ص/%ط/%ن/%ع/%أ
الدوال متغيرة المعاملات (v0.4.0.5)	دعم ... في تواقيع الدوال ومؤشرات الدوال + الدوال المضمنة بدء_معاملات/معامل_تالي/نهاية_معاملات
المكتبة القياسية (v0.4.1.0)	وحدات إضافية: الرياضيات جذر_تربيعي/أس/مطلق/عشوائي + النظام متغير_بيئة/نفذ_أمر + الوقت وقت_حالي/وقت_كنص
توسعات الفاصلة العائمة (v0.4.2.0)	دوال مثلثية جيب/جيب_تمام/ظل + النوع عشري٣٢ (alias حالياً إلى عشري) + تنسيق علمي %أ
معالجة الأخطاء (v0.4.3.0)	تأكد/توقف_فوري + جسر errno عبر كود_خطأ_النظام/ضبط_كود_خطأ_النظام/نص_كود_خطأ + رموز خطأ قياسية
الضبط النهائي (v0.4.4.0)	توثيق محدث بالكامل + سلسلة دروس عربية + أمثلة جاهزة + دليل قياس الأداء
تسلسلات الهروب	دعم \س (سطر جديد)، \ت (Tab)، \٠، و\\ في النصوص/المحارف
إدخال المستخدم	العبارة اقرأ لقراءة أعداد صحيحة
النظام الوسيط (IR)	IR داخلي مع SSA form وتحليل التدفّق والتحسينات متعددة المراحل
سلامة الأنواع	تدقيق ثابت للأنواع مع تحليل دلالي
تحديث ذاتي	مُحدِّث مدمج (baa update) — ويندوز فقط حالياً

مسار التصريف الكامل

المصدر (.baa)
    ↓
المحلل اللفظي (Lexer) + المعالج القبلي
    ↓
المحلل القواعدي (Parser) ← شجرة الإعراب (AST)
    ↓
التحليل الدلالي (Semantic Analysis) ← جدول الرموز
    ↓
توليد IR (Intermediate Representation)
    ↓
المُحسِّن (Optimizer) ← SSA form + تحسينات متعددة المراحل
    ↓
الخلفية (Backend): اختيار التعليمات (ISel) ← تخصيص السجلات (RegAlloc) ← توليد التجميع
    ↓
ملف التجميع (.s)
    ↓
GCC/Clang المضيف (الربط والتجميع)
    ↓
ملف تنفيذي أصلي (PE/COFF على ويندوز، ELF على لينكس)

---

التوافقية

العنصر	مدعوم	ملاحظات
نظام التشغيل	ويندوز (x86-64) + لينكس (x86-64)	على لينكس يتم إنتاج ELF والربط باستخدام GCC المضيف حالياً
سلسلة الأدوات	ويندوز: CMake 3.10+ + MinGW-w64 GCC / لينكس: CMake 3.10+ + GCC/Clang	على ويندوز نستخدم MinGW، وعلى لينكس نستخدم GCC/Clang المضيف
ترميز ملفات المصدر	UTF-8	يتطلب النص العربي ملفات بترميز UTF-8
الطرفية	ويندوز تيرمنال / باورشِل	فعِّل UTF-8 إذا ظهر الإخراج بصورة غير سليمة

البدء السريع

1) بناء المُصرِّف

ويندوز (MinGW):

git clone https://github.com/OmarAglan/Baa.git
cd Baa
cmake -B build -G "MinGW Makefiles"
cmake --build build

لينكس (GCC/Clang):

git clone https://github.com/OmarAglan/Baa.git
cd Baa
cmake -B build-linux -DCMAKE_BUILD_TYPE=Release
cmake --build build-linux -j
./build-linux/baa --version

2) اكتب برنامجك الأول

أنشئ ملف hello.baa (مهم: احفظ الملف بترميز UTF-8):

صحيح الرئيسية() {
    اطبع "مرحباً بالعالم!".
    إرجع ٠.
}

3) صرِّف وشغِّل

# التصريف
.\build\baa.exe .\hello.baa

# التشغيل
.\out.exe

# التصريف
./build-linux/baa ./hello.baa

# التشغيل
./out

4) اختيار الهدف (تعدد الأهداف)

افتراضياً يختار المُصرِّف هدف النظام المضيف. يمكنك تحديده صراحةً:

baa --target=x86_64-windows البرنامج.baa
baa --target=x86_64-linux   البرنامج.baa

ملاحظة (0.3.2.8.4+):

• عند اختلاف الهدف عن نظام المضيف، يدعم المُصرّف حالياً -S فقط (توليد ملف تجميع). التجميع/الربط العابر للأهداف مؤجل.

القيود الحالية (0.4.4.1)

• نوع عشري (f64) مدعوم للحساب/المقارنة/الطباعة، وعشري٣٢ متاح كـ alias مصدرية حالياً؛ التمثيل الداخلي لا يزال f64 في هذا الإصدار.
• حساب المؤشرات في هذا الإصدار يغطي المسار الأساسي (pointer +/- int)؛ الميزات المتقدمة مؤجلة.
• صيغة التحويل الصريح كـ<...>(...) مدعومة في v0.3.10.5 للأنواع العددية وتحويلات المؤشرات الأساسية.
• مؤشرات الدوال (دالة(...) -> ...) لا تدعم حالياً تعشيش تواقيع مؤشرات الدوال داخل تواقيع مؤشرات دوال أخرى، ولا تدعم النداء عبر تعبير كـ callee (حالياً النداء غير المباشر مدعوم عبر معرّف فقط).

موارد v0.4.4 (Final Polish)

• دروس خطوة بخطوة: docs/TUTORIALS_AR.md
• فهرس أمثلة جاهزة: examples/README.md
• دليل الأداء والقياس: docs/PERFORMANCE.md

دوال النص القياسية (0.3.9)

#تضمين "baalib.baahd"   // مدعوم أيضاً: "stdlib/baalib.baahd"

صحيح الرئيسية() {
    نص س = دمج_نص("مرح", "با").
    اطبع طول_نص(س).
    حرر_نص(س).
    إرجع ٠.
}

ملاحظة: يبحث #تضمين بالترتيب في:

1. من مجلد الملف الحالي، 2) المسار كما كُتب، 3) {BAA_HOME}/<path> (للمسارات النسبية)، 4) مسارات -I بالترتيب. وللاسم المجرّد مثل baalib.baahd: stdlib/ قرب الملف، ثم stdlib/ محلياً، ثم BAA_STDLIB، ثم {BAA_HOME}/stdlib. بعد اختيار الملف، يُطبَّع المسار الناجح قبل إدخاله إلى مكدس التضمين، لذلك تُعامل الصيغ المكافئة مثل a.baahd و./a.baahd كملف واحد، وتُرفض دورات التضمين برسالة عربية تعرض سلسلة التضمين. قواعد الظهور الحالية بين الملفات:
2. الدوال على المستوى العام مرئية خارج الملف افتراضياً.
3. النموذج الأولي في .baahd تصريح فقط ولا يُنشئ جسماً إضافياً.
4. المتغيرات/المصفوفات العامة الموسومة ساكن محلية للملف.
5. لا توجد بعد صيغة extern مستقلة للمتغيرات العامة، لذا الواجهة المشتركة المستقرة بين الملفات هي واجهات الدوال.

مثال سريع: المؤشرات (0.3.10)

صحيح الرئيسية() {
    صحيح س = ١٠.
    صحيح* م = &س.

    إذا (*م != ١٠) { إرجع ١. }

    *م = ٢٠.
    إذا (س != ٢٠) { إرجع ٢. }

    صحيح* فارغ = عدم.
    إذا (فارغ != عدم) { إرجع ٣. }

    إرجع ٠.
}

مثال: مؤشرات الدوال (0.3.10.6)

صحيح اجمع(صحيح أ، صحيح ب) {
    إرجع أ + ب.
}

صحيح طبق(دالة(صحيح، صحيح) -> صحيح ف، صحيح أ، صحيح ب) {
    إرجع ف(أ، ب).
}

صحيح الرئيسية() {
    // إسناد مرجع الدالة إلى مؤشر
    دالة(صحيح، صحيح) -> صحيح ف = اجمع.
    
    // النداء غير المباشر عبر المؤشر
    صحيح ن = ف(٢، ٣).
    اطبع ن.  // المخرج: ٥
    
    // تمرير مؤشر الدالة كمعامل
    صحيح م = طبق(اجمع، ١٠، ٢٠).
    اطبع م.  // المخرج: ٣٠
    
    // مقارنة مع عدم
    إذا (ف != عدم) {
        اطبع "المؤشر غير فارغ".
    }
    
    إرجع ٠.
}

خيارات المُصرِّف المفيدة

الخيار	الوصف
-O0	بدون تحسين (افتراضي)
-O1	تحسين أساسي
-O2	تحسين عالي (مستوى الإنتاج)
-S	توليد ملف تجميع فقط (.s)
-c	توليد ملف كائن فقط (.o)
-o <file>	تحديد اسم ملف المخرج
--target=x86_64-windows|x86_64-linux	تحديد الهدف
--startup=custom	استخدام نقطة دخول مخصّصة (__baa_start) مع الحفاظ على تهيئة CRT/libc
--verify	التحقق من صحة IR/SSA بعد التحسين
--verify-ir	التحقق من صحة IR فقط
--verify-ssa	التحقق من صحة SSA فقط
-fPIC / -fPIE	خيارات PIC/PIE (لينكس/ELF)
-fstack-protector / -fstack-protector-all	حماية المكدس (لينكس/ELF)
-mcmodel=small	نموذج الذاكرة الصغير
--help	عرض مساعدة الاستخدام
--version	عرض إصدار المُصرِّف

---

مثال: جمع عناصر مصفوفة

// حساب مجموع مصفوفة
صحيح الرئيسية() {
    // التصريح بمصفوفة من ٥ أعداد صحيحة
    صحيح قائمة[٥].
    صحيح مجموع = ٠.

    // ملء المصفوفة بالقيم: ٠، ١٠، ٢٠، ٣٠، ٤٠
    لكل (صحيح س = ٠؛ س < ٥؛ س = س + ١) {
        قائمة[س] = س * ١٠.
    }

    // جمع جميع القيم
    لكل (صحيح س = ٠؛ س < ٥؛ س = س + ١) {
        مجموع = مجموع + قائمة[س].
    }

    اطبع "المجموع هو: ".
    اطبع مجموع.
    
    إرجع ٠.
}

المخرجات: المجموع هو: ١٠٠ (٠ + ١٠ + ٢٠ + ٣٠ + ٤٠)

---

مثال: هيكل + تعداد + اتحاد

تعداد نوع_قيمة { رقم، نص_ق }

اتحاد قيمة {
    صحيح رقم.
    نص نص_قيمة.
}

هيكل قيمة_موسومة {
    تعداد نوع_قيمة نوع.
    اتحاد قيمة بيانات.
}

صحيح الرئيسية() {
    هيكل قيمة_موسومة م.
    م:نوع = نوع_قيمة:رقم.
    م:بيانات:رقم = ٤٢.
    اطبع م:بيانات:رقم.

    م:نوع = نوع_قيمة:نص_ق.
    م:بيانات:نص_قيمة = "مرحبا".
    اطبع م:بيانات:نص_قيمة.

    إرجع ٠.
}

---

التوثيق

المستند	الوصف
دليل المستخدم	البدء والاستخدام الأساسي
الكتاب العربي	تعلّم/مرجع عربي شامل (مسودة)
مواصفة اللغة	مرجع كامل للصياغة والمزايا
البنية الداخلية للمُصرِّف	المعمارية وتفاصيل التنفيذ
مرجع واجهة البرمجة	توثيق الواجهة الداخلية للمُصرِّف
خارطة الطريق	خطط التطوير المستقبلية
سجل التغييرات	تاريخ الإصدارات

---

البناء من الشيفرة المصدرية

المتطلبات

• CMake 3.10+
• MinGW-w64 مع GCC
• باورشِل (ويندوز)
• Git (لاستنساخ المستودع)

خطوات البناء

# استنساخ المستودع
git clone https://github.com/OmarAglan/Baa.git
cd Baa

# التوليد ثم البناء (من جذر المشروع)
cmake -B build -G "MinGW Makefiles"
cmake --build build

# أصبح المُصرّف الآن في: build/baa.exe

تشغيل الاختبارات

# المسار الموصى به (تشغيل سريع)
python .\scripts\qa_run.py --mode quick

# المسار الموصى به (تحقق كامل)
python .\scripts\qa_run.py --mode full

# مسار الضغط
python .\scripts\qa_run.py --mode stress

# (اختياري) المشغّل القديم لاختبارات الانحدار
python .\tests\regress.py

# تشغيل اختبار تكاملي واحد (مثال)
.\build\baa.exe -O2 --verify .\tests\integration\backend\backend_test.baa -o .\build\backend_test.exe
.\build\backend_test.exe

تنظيم إطار الاختبارات

tests/
├── integration/
│   ├── backend/   # اختبارات تكامل وتجميع/تشغيل
│   └── ir/        # اختبارات تكامل خاصة بـ IR من منظور المستخدم
├── neg/           # اختبارات تشخيص فشل متوقع
├── stress/        # اختبارات الضغط
├── fixtures/      # ملفات مساعدة للاختبارات (headers/includes/multi-file)
├── corpus_docs/   # عينات من التوثيق
├── corpus_v2x_docs/
├── test.py        # مشغل التكامل
└── regress.py     # مشغل الانحدار

---

التحقّق (مقترح)

للتحقق من أمثلة التوثيق مقابل التنفيذ:

cmake -S . -B build
cmake --build build
.\build\baa.exe --help
.\build\baa.exe --version

ولفحص سريع طرف-إلى-طرف:

gcc .\make_test.c -o .\build\make_test.exe
.\build\make_test.exe
.\build\baa.exe .\build\test.baa -o .\build\test_suite.exe
.\build\test_suite.exe