changes on documentation structure

README.ar.md

@@ -1,24 +1,21 @@
 # ProgArg
-[[English]](README.md)
 
 <div dir=rtl>
 
+[[English]](README.md)
+
 ## نظرة عامة
 توفر مكتبة **ProgArg** حلاً مرنًا وقويًا لتعريف وتحليل الوسائط والأوامر الممررة عبر سطر الأوامر في
 تطبيقات لغة الأسس البرمجية. تدعم المكتبة الهياكل الهرمية للأوامر والخيارات والوسائط، كما تدعم
 التوطين بشكل مدمج.
 
----
-
 ## المميزات
-- **تعريف الأوامر**: تعريف الأوامر باستخدام الكلمات المفتاحية، الوصف، الخيارات، والوسائط.
-- **الأوامر الفرعية**: دعم الهياكل الهرمية للأوامر.
-- **التوطين**: دعم مدمج للتدويل باستخدام `Alusus/I18n`.
-- **إظهار التعليمات**: إنشاء رسائل تعليمات تلقائيًا.
-- **تحليل والمعطيات والخيارات**: تحليل  المعطيات والخيارات.
-- **معالجة الأخطاء**: التعامل مع الأخطاء المتعلقة بالمعطيات غير الصحيحة أو الناقصة.
-
----
+* **تعريف الأوامر**: تعريف الأوامر باستخدام الكلمات المفتاحية، الوصف، الخيارات، والوسائط.
+* **الأوامر الفرعية**: دعم الهياكل الهرمية للأوامر.
+* **التوطين**: دعم مدمج للتدويل باستخدام `Alusus/I18n`.
+* **إظهار التعليمات**: إنشاء رسائل تعليمات تلقائيًا.
+* **تحليل والمعطيات والخيارات**: تحليل  المعطيات والخيارات.
+* **معالجة الأخطاء**: التعامل مع الأخطاء المتعلقة بالمعطيات غير الصحيحة أو الناقصة.
 
 ## الإضافة إلى المشروع
 
@@ -38,11 +35,10 @@ Apm.importFile("Alusus/ProgArg");
 
 بعد إضافة المكتبة إلى المشروع ستكون تعريفاتها متوفرة في الوحدة `بـروجارج` (`ProgArg`).
 
----
-
 ## الأصناف
 
-### `تـعريف_الأمر` (`CmdDef`)
+### تـعريف_الأمر (CmdDef)
+
 يعرّف الأمر والبيانات الوصفية المرتبطة به.
 
 ```
@@ -83,57 +79,176 @@ class CmdDef {
 
 </div>
 
-**الخصائص:**
+#### الكلمة_التعريفية (kwd)
+
+```
+عرف الكلمة_التعريفية: نـص؛
+```
+
+<div dir=ltr>
+
+```
+def kwd: String;
+```
+
+</div>
+
+الكلمة المفتاحية التي تحدد الأمر.
+
+#### الوصف (description)
+
+```
+عرف الوصف: نـص؛
+```
+
+<div dir=ltr>
+
+```
+def description: String;
+```
+
+</div>
+
+وصف موجز للأمر.
+
+#### الخيارات (options)
+
+```
+عرف الخيارات: تـطبيق[نـص, نـص]؛
+```
+
+<div dir=ltr>
+
+```
+def options: Map[String, String];
+```
+
+</div>
+
+قائمة بأسماء الخيارات ووصفها.
+
+#### المعطيات (args)
+
+```
+عرف المعطيات: تـطبيق[نـص, نـص]؛
+```
+
+<div dir=ltr>
+
+```
+def args: Map[String, String];
+```
+
+</div>
+
+قائمة بأسماء المعطيات ووصفها.
+
+#### عدد_المعطيات_الإلزامية (numRequiredArgs)
+
+```
+عرف عدد_المعطيات_الإلزامية: صـحيح = -1؛
+```
+
+<div dir=ltr>
+
+```
+def numRequiredArgs: Int = -1;
+```
+
+</div>
+
+عدد المعطيات المطلوبة. إذا كانت -1، وهي القيمة الافتراضية، تُعتبر جميع المعطيات مطلوبة.
 
-- `الكلمة_التعريفية` (`kwd`)
-  الكلمة المفتاحية التي تحدد الأمر.
+#### الأوامر_الفرعية (subCmds)
 
-- `الوصف` (`description`)
-  وصف موجز للأمر.
+```
+عرف الأوامر_الفرعية: مـصفوفة[سـندنا[تـعريف_الأمر]]؛
+```
+
+<div dir=ltr>
+
+```
+def subCmds: Array[SrdRef[CmdDef]];
+```
+
+</div>
+
+مصفوفة من الأوامر الفرعية المُعرفة للأمر.
+
+#### معالج_التنفيذ (callback)
+
+```
+عرف معالج_التنفيذ: مغلفة(الخيارات: تـطبيق[نـص, نـص], المعطيات: مـصفوفة[نـص])؛
+```
+
+<div dir=ltr>
+
+```
+def callback: closure(options: Map[String, String], args: Array[String]);
+```
+
+</div>
+
+دالة مغلفة تستدعى عند معالجة الأمر. تُستدعى هذه الدالة فقط في حال عدم احتواء الأمر على أي أوامر فرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر.
+
+#### معالج_البدء (startCallback)
+
+```
+عرف معالج_البدء: مغلفة(الخيارات: تـطبيق[نـص, نـص], المعطيات: مـصفوفة[نـص])؛
+```
+
+<div dir=ltr>
+
+```
+def startCallback: closure(options: Map[String, String], args: Array[String]);
+```
+
+</div>
 
-- `الخيارات` (`options`)
-  قائمة بأسماء الخيارات ووصفها.
+دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى قبل البدء بمعالجة الأوامر الفرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر.
 
-- `المعطيات` (`args`)
-  قائمة بأسماء المعطيات ووصفها.
+#### معالج_الانتهاء (endCallback)
 
-- `عدد_المعطيات_الإلزامية` (`numRequiredArgs`)
-  عدد المعطيات المطلوبة. إذا كانت -1، وهي القيمة الافتراضية، تُعتبر جميع المعطيات مطلوبة.
+```
+عرف معالج_الانتهاء: مغلفة(الخيارات: تـطبيق[نـص, نـص], المعطيات: مـصفوفة[نـص])؛
+```
 
-- `الأوامر_الفرعية` (`subCmds`)
-  مصفوفة من الأوامر الفرعية المُعرفة للأمر.
+<div dir=ltr>
 
-- `معالج_التنفيذ` (`callback`)
-  دالة مغلفة تستدعى عند معالجة الأمر. تُستدعى هذه الدالة فقط في حال عدم احتواء الأمر على أي أوامر
-  فرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر.
+```
+def endCallback: closure(options: Map[String, String], args: Array[String]);
+```
 
-- `معالج_البدء` (`startCallback`)
-  دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى قبل البدء بمعالجة الأوامر الفرعية.
-  تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر.
+</div>
 
-- `معالج_الانتهاء` (`endCallback`)
-  دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى بعد الانتهاء من معالجة الأوامر الفرعية.
-  تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر.
+دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى بعد الانتهاء من معالجة الأوامر الفرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر.
 
-**العمليات:**
+#### جد_أمرا_فرعيا (findSubCmd)
 
-- `جد_أمرا_فرعيا` (`findSubCmd`): تبحث عن أمر فرعي بالكلمة المفتاحية المحددة وترجع مرجعا إليه.
-  ترجع مرجعا فارغا إذا لم تجد أمرا فرعيا مطابقا.
+```
+عملية هذا.جد_أمرا_فرعيا(الكلمة_المفتاحية: مـؤشر_محارف): سـندنا[تـعريف_الأمر]؛
+```
 
----
+<div dir=ltr>
+
+```
+handler this.findSubCmd(kwd: CharsPtr): SrdRef[CmdDef]
+```
+
+</div>
+
+تبحث عن أمر فرعي بالكلمة المفتاحية المحددة وترجع مرجعا إليه. ترجع مرجعا فارغا إذا لم تجد أمرا فرعيا مطابقا.
 
 ## المتغيرات العمومية
 
-### `تعريف_الأمر` (`cmdDef`)
+### تعريف_الأمر (cmdDef)
 
 متغير عمومي يحمل تعريف الأمر الرئيسي الذي تبدأ منه عملية التحليل. تُهمل الكلمة التعريفية في هذا الأمر
 وتستخدم منه تعريفات المعطيات والخيارات والأوامر الفرعية.
 
----
-
 ## الدالات
 
-### `هيئ` (`initialize`)
+### هيئ (initialize)
 
 ```
 دالة هيئ()؛
@@ -157,7 +272,7 @@ function initialize(lang: String, localizationsPath: String);
 الترجمات عند تنفيذ البرنامج.
 يجب استدعاء هذه الدالة في بداية البرنامج قبل استخدام الدالات الأخرى.
 
-### `هات_مسار_الترجمات` (`getLocalizationsPath`)
+### هات_مسار_الترجمات (getLocalizationsPath)
 
 ```
 دالة هات_مسار_الترجمات(): نـص؛
@@ -174,37 +289,35 @@ function getLocalizationsPath(): String;
 ترجع مسار ملفات الترجمة المرفقة مع هذه المكتبة. هذه الدالة تُستخدم داخليا عادة ولكنها تكون مفيدة في حال
 رغب المستخدم بإرفاق ملفات الترجمة مع برنامجه عند النشر لتحميلها أثناء التنفيذ.
 
-### `إطبع_المساعدة` (`printHelp`)
+### إطبع_المساعدة (printHelp)
 
 ```
-دالة اطبع_المساعدة(تسلسل_أول_معطى: صـحيح، وطن_الأوامر: ثـنائي)؛
-دالة اطبع_المساعدة(تعريف_الأمر: سـندنا[تـعريف_الأمر]، إزاحات: صـحيح، وطن_الأوامر: ثـنائي)؛
+دالة اطبع_المساعدة(تسلسل_أول_معطى: صـحيح)؛
+دالة اطبع_المساعدة(تعريف_الأمر: سـندنا[تـعريف_الأمر]، إزاحات: صـحيح)؛
 ```
 
 <div dir=ltr>
 
 ```
-function printHelp(argStartIndex: Int, localizeCommands: Bool);
-function printHelp(cmdDef: SrdRef[CmdDef], tabs: Int, localizeCommands: Bool);
+function printHelp(argStartIndex: Int);
+function printHelp(cmdDef: SrdRef[CmdDef], tabs: Int);
 ```
 
 </div>
 
 تطبع رسالة التعليمات لأمر مع أوامره الفرعية. النسخة الأولى تستنتج الأمر المراد شرحه من مدخلات البرنامج
 بينما النسخة الثانية تستلم الأمر المراد شرحه.
 
-**المعطيات:**
-
-- `تسلسل_أول_معطى` (`argStartIndex`): تسلسل المعطى الأول ضمن معطيات البرنامج بعد استثناء اسم البرنامج.
+* `تسلسل_أول_معطى` (`argStartIndex`): تسلسل المعطى الأول ضمن معطيات البرنامج بعد استثناء اسم البرنامج.
   في العادة يكون هذا المعطى 1 في حالة ترجمة البرنامج مسبقًا، أما في حالة التنفيذ أثناء الترجمة فسيطون
   هذا المعطى 2 لأن المعطى الأول سيكون لاسم مترجم الأسس بينما الثاني لاسم ملف الشفرة المصدرية التي يُراد
   تنفيذها.
-- `تعريف_الأمر` (`cmdDef`): مرجع لتعريف الأمر المراد شرحه.
-- `إزاحات` (`tabs`): عدد المسافات البادئة لإزاحة الإخراج.
-- `وطن_الأوامر` (`localizeCommands`): إذا كان هذا المعطى 1 تُوطّن الكلمات المفتاحية وأسماء المعطيات
-  والخيارات عند طباعة الشرح، وإلا فتُطبع بصيغتها الأصلية دون ترجمة.
 
-### `حلل` (`parse`)
+* `تعريف_الأمر` (`cmdDef`): مرجع لتعريف الأمر المراد شرحه.
+
+* `إزاحات` (`tabs`): عدد المسافات البادئة لإزاحة الإخراج.
+
+### حلل (parse)
 
 ```
 دالة حلل(تسلسل_أول_معطى: صـحيح)؛
@@ -224,22 +337,17 @@ function parse(cmdDef: SrdRef[CmdDef], argStartIndex: Int): Int;
 النسخة الثانية تستلم تعريف الأمر المراد بدء التحليل منه، بينما تبدأ النسخة الأولى من الأمر
 الرئيسي، أي `بـروجارج.تعريف_الأمر` (`ProgArg.cmdDef`).
 
-**المعطيات:**
+ترجع الصيغة الثانية تسلسل المعطى الذي وصلت إليه عملية التحليل بعد استخدام كل المعطيات الممكنة. الصيغة
+الأولى لا ترجع التسلسل وتفترض بدلا من ذلك أن تُستخدم كل المعطيات الممرة للبرنامج، وفي حال بقاء أي معطى
+بعد الانتهاء من التحليل تغلق البرنامج مع طباعة إشعار خطأ حول معطى غير معروف.
 
-- `تسلسل_أول_معطى` (`argStartIndex`): تسلسل المعطى الأول ضمن معطيات البرنامج بعد استثناء اسم البرنامج.
+* `تسلسل_أول_معطى` (`argStartIndex`): تسلسل المعطى الأول ضمن معطيات البرنامج بعد استثناء اسم البرنامج.
   في العادة يكون هذا المعطى 1 في حالة ترجمة البرنامج مسبقًا، أما في حالة التنفيذ أثناء الترجمة فسيطون
   هذا المعطى 2 لأن المعطى الأول سيكون لاسم مترجم الأسس بينما الثاني لاسم ملف الشفرة المصدرية التي يُراد
   تنفيذها.
-- `تعريف_الأمر` (`cmdDef`): الأمر الذي سيبدأ منه البحث عن الخيارات والمعطيات والأوامر الفرعية. في حالة
-  النسخة الأولى يُعتمد الأمر الرئيسي المعرف على مستوى المكتبة.
-
-**القيمة المرجعة:**
-
-ترجع الصيغة الثانية تسلسل المعطى الذي وصلت إليه عملية التحليل بعد استخدام كل المعطيات الممكنة. الصيغة
-الأولى لا ترجع التسلسل وتفترض بدلا من ذلك أن تُستخدم كل المعطيات الممرة للبرنامج، وفي حال بقاء أي معطى
-بعد الانتهاء من التحليل تغلق البرنامج مع طباعة إشعار خطأ حول معطى غير معروف.
 
----
+* `تعريف_الأمر` (`cmdDef`): الأمر الذي سيبدأ منه البحث عن الخيارات والمعطيات والأوامر الفرعية. في حالة
+  النسخة الأولى يُعتمد الأمر الرئيسي المعرف على مستوى المكتبة.
 
 ## مثال
 
@@ -285,26 +393,19 @@ ProgArg.parse(2);
 
 </div>
 
----
-
 ## معالجة الأخطاء
 
-- تطبع رسائل الخطأ إلى `stderr` وتخرج برمز غير صفري إذا تم تمرير وسائط غير صحيحة أو إذا كانت هناك وسائط مطلوبة مفقودة.
-
----
+* تطبع رسائل الخطأ إلى `stderr` وتخرج برمز غير صفري إذا تم تمرير وسائط غير صحيحة أو إذا كانت هناك وسائط مطلوبة مفقودة.
 
 ## التوطين
 
 يمكن توطين جميع النصوص باستخدام وحدة `I18n`. وسيط `localizeCommands` يوجه المكتبة لطباعة النسخ الموطنة من الكلمات
 المفتاحية وأسماء الخيارات عند إنشاء رسائل التعليمات في الدوال مثل `printHelp` و`printCmdHelp`.
 
----
-
 ## الرخصة
 
 حقوق النشر © 2026 سرمد خالد عبد الله
 
 هذا المشروع مرخص بموجب رخصة غنو العمومية الصغرى الإصدار 3.0 (LGPL-3.0). راجع ملفات `COPYING` و `COPYING.LESSER` للحصول على التفاصيل.
 
 </div>
-