diff --git a/README.ar.md b/README.ar.md index e61005d..a6183aa 100644 --- a/README.ar.md +++ b/README.ar.md @@ -1,24 +1,21 @@ # ProgArg -[[English]](README.md)
+[[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 {
-**الخصائص:** +#### الكلمة_التعريفية (kwd) + +``` +عرف الكلمة_التعريفية: نـص؛ +``` + +
+ +``` +def kwd: String; +``` + +
+ +الكلمة المفتاحية التي تحدد الأمر. + +#### الوصف (description) + +``` +عرف الوصف: نـص؛ +``` + +
+ +``` +def description: String; +``` + +
+ +وصف موجز للأمر. + +#### الخيارات (options) + +``` +عرف الخيارات: تـطبيق[نـص, نـص]؛ +``` + +
+ +``` +def options: Map[String, String]; +``` + +
+ +قائمة بأسماء الخيارات ووصفها. + +#### المعطيات (args) + +``` +عرف المعطيات: تـطبيق[نـص, نـص]؛ +``` + +
+ +``` +def args: Map[String, String]; +``` + +
+ +قائمة بأسماء المعطيات ووصفها. + +#### عدد_المعطيات_الإلزامية (numRequiredArgs) + +``` +عرف عدد_المعطيات_الإلزامية: صـحيح = -1؛ +``` + +
+ +``` +def numRequiredArgs: Int = -1; +``` + +
+ +عدد المعطيات المطلوبة. إذا كانت -1، وهي القيمة الافتراضية، تُعتبر جميع المعطيات مطلوبة. -- `الكلمة_التعريفية` (`kwd`) - الكلمة المفتاحية التي تحدد الأمر. +#### الأوامر_الفرعية (subCmds) -- `الوصف` (`description`) - وصف موجز للأمر. +``` +عرف الأوامر_الفرعية: مـصفوفة[سـندنا[تـعريف_الأمر]]؛ +``` + +
+ +``` +def subCmds: Array[SrdRef[CmdDef]]; +``` + +
+ +مصفوفة من الأوامر الفرعية المُعرفة للأمر. + +#### معالج_التنفيذ (callback) + +``` +عرف معالج_التنفيذ: مغلفة(الخيارات: تـطبيق[نـص, نـص], المعطيات: مـصفوفة[نـص])؛ +``` + +
+ +``` +def callback: closure(options: Map[String, String], args: Array[String]); +``` + +
+ +دالة مغلفة تستدعى عند معالجة الأمر. تُستدعى هذه الدالة فقط في حال عدم احتواء الأمر على أي أوامر فرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر. + +#### معالج_البدء (startCallback) + +``` +عرف معالج_البدء: مغلفة(الخيارات: تـطبيق[نـص, نـص], المعطيات: مـصفوفة[نـص])؛ +``` + +
+ +``` +def startCallback: closure(options: Map[String, String], args: Array[String]); +``` + +
-- `الخيارات` (`options`) - قائمة بأسماء الخيارات ووصفها. +دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى قبل البدء بمعالجة الأوامر الفرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر. -- `المعطيات` (`args`) - قائمة بأسماء المعطيات ووصفها. +#### معالج_الانتهاء (endCallback) -- `عدد_المعطيات_الإلزامية` (`numRequiredArgs`) - عدد المعطيات المطلوبة. إذا كانت -1، وهي القيمة الافتراضية، تُعتبر جميع المعطيات مطلوبة. +``` +عرف معالج_الانتهاء: مغلفة(الخيارات: تـطبيق[نـص, نـص], المعطيات: مـصفوفة[نـص])؛ +``` -- `الأوامر_الفرعية` (`subCmds`) - مصفوفة من الأوامر الفرعية المُعرفة للأمر. +
-- `معالج_التنفيذ` (`callback`) - دالة مغلفة تستدعى عند معالجة الأمر. تُستدعى هذه الدالة فقط في حال عدم احتواء الأمر على أي أوامر - فرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر. +``` +def endCallback: closure(options: Map[String, String], args: Array[String]); +``` -- `معالج_البدء` (`startCallback`) - دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى قبل البدء بمعالجة الأوامر الفرعية. - تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر. +
-- `معالج_الانتهاء` (`endCallback`) - دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى بعد الانتهاء من معالجة الأوامر الفرعية. - تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر. +دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى بعد الانتهاء من معالجة الأوامر الفرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر. -**العمليات:** +#### جد_أمرا_فرعيا (findSubCmd) -- `جد_أمرا_فرعيا` (`findSubCmd`): تبحث عن أمر فرعي بالكلمة المفتاحية المحددة وترجع مرجعا إليه. - ترجع مرجعا فارغا إذا لم تجد أمرا فرعيا مطابقا. +``` +عملية هذا.جد_أمرا_فرعيا(الكلمة_المفتاحية: مـؤشر_محارف): سـندنا[تـعريف_الأمر]؛ +``` ---- +
+ +``` +handler this.findSubCmd(kwd: CharsPtr): SrdRef[CmdDef] +``` + +
+ +تبحث عن أمر فرعي بالكلمة المفتاحية المحددة وترجع مرجعا إليه. ترجع مرجعا فارغا إذا لم تجد أمرا فرعيا مطابقا. ## المتغيرات العمومية -### `تعريف_الأمر` (`cmdDef`) +### تعريف_الأمر (cmdDef) متغير عمومي يحمل تعريف الأمر الرئيسي الذي تبدأ منه عملية التحليل. تُهمل الكلمة التعريفية في هذا الأمر وتستخدم منه تعريفات المعطيات والخيارات والأوامر الفرعية. ---- - ## الدالات -### `هيئ` (`initialize`) +### هيئ (initialize) ``` دالة هيئ()؛ @@ -157,7 +272,7 @@ function initialize(lang: String, localizationsPath: String); الترجمات عند تنفيذ البرنامج. يجب استدعاء هذه الدالة في بداية البرنامج قبل استخدام الدالات الأخرى. -### `هات_مسار_الترجمات` (`getLocalizationsPath`) +### هات_مسار_الترجمات (getLocalizationsPath) ``` دالة هات_مسار_الترجمات(): نـص؛ @@ -174,18 +289,18 @@ function getLocalizationsPath(): String; ترجع مسار ملفات الترجمة المرفقة مع هذه المكتبة. هذه الدالة تُستخدم داخليا عادة ولكنها تكون مفيدة في حال رغب المستخدم بإرفاق ملفات الترجمة مع برنامجه عند النشر لتحميلها أثناء التنفيذ. -### `إطبع_المساعدة` (`printHelp`) +### إطبع_المساعدة (printHelp) ``` -دالة اطبع_المساعدة(تسلسل_أول_معطى: صـحيح، وطن_الأوامر: ثـنائي)؛ -دالة اطبع_المساعدة(تعريف_الأمر: سـندنا[تـعريف_الأمر]، إزاحات: صـحيح، وطن_الأوامر: ثـنائي)؛ +دالة اطبع_المساعدة(تسلسل_أول_معطى: صـحيح)؛ +دالة اطبع_المساعدة(تعريف_الأمر: سـندنا[تـعريف_الأمر]، إزاحات: صـحيح)؛ ```
``` -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); ```
@@ -193,18 +308,16 @@ function printHelp(cmdDef: SrdRef[CmdDef], tabs: Int, localizeCommands: Bool); تطبع رسالة التعليمات لأمر مع أوامره الفرعية. النسخة الأولى تستنتج الأمر المراد شرحه من مدخلات البرنامج بينما النسخة الثانية تستلم الأمر المراد شرحه. -**المعطيات:** - -- `تسلسل_أول_معطى` (`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,21 +393,15 @@ ProgArg.parse(2); ---- - ## معالجة الأخطاء -- تطبع رسائل الخطأ إلى `stderr` وتخرج برمز غير صفري إذا تم تمرير وسائط غير صحيحة أو إذا كانت هناك وسائط مطلوبة مفقودة. - ---- +* تطبع رسائل الخطأ إلى `stderr` وتخرج برمز غير صفري إذا تم تمرير وسائط غير صحيحة أو إذا كانت هناك وسائط مطلوبة مفقودة. ## التوطين يمكن توطين جميع النصوص باستخدام وحدة `I18n`. وسيط `localizeCommands` يوجه المكتبة لطباعة النسخ الموطنة من الكلمات المفتاحية وأسماء الخيارات عند إنشاء رسائل التعليمات في الدوال مثل `printHelp` و`printCmdHelp`. ---- - ## الرخصة حقوق النشر © 2026 سرمد خالد عبد الله @@ -307,4 +409,3 @@ ProgArg.parse(2); هذا المشروع مرخص بموجب رخصة غنو العمومية الصغرى الإصدار 3.0 (LGPL-3.0). راجع ملفات `COPYING` و `COPYING.LESSER` للحصول على التفاصيل. - diff --git a/README.md b/README.md index 8614807..2b12d21 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # ProgArg + [[العربية]](README.ar.md) ## Overview @@ -7,18 +8,14 @@ The **ProgArg** library provides a flexible and powerful solution for defining a command-line arguments and commands in Alusus-based applications. It supports hierarchical command structures, options, and arguments, as well as built-in localization. ---- - ## Features -- **Command Definition**: Define commands with keywords, descriptions, options, and arguments. -- **Subcommands**: Support for hierarchical command structures. -- **Localization**: Built-in internationalization support using `Alusus/I18n`. -- **Help Display**: Automatically generates help messages. -- **Argument and Option Parsing**: Parses arguments and options. -- **Error Handling**: Handles errors related to incorrect or missing arguments. - ---- +* **Command Definition**: Define commands with keywords, descriptions, options, and arguments. +* **Subcommands**: Support for hierarchical command structures. +* **Localization**: Built-in internationalization support using `Alusus/I18n`. +* **Help Display**: Automatically generates help messages. +* **Argument and Option Parsing**: Parses arguments and options. +* **Error Handling**: Handles errors related to incorrect or missing arguments. ## Adding to a Project @@ -29,11 +26,9 @@ Apm.importFile("Alusus/ProgArg"); Once the library is added to the project, its definitions will be available under the `ProgArg` module. ---- - ## Classes -### `CmdDef` +### CmdDef Defines a command and its associated metadata. @@ -54,106 +49,142 @@ class CmdDef { } ``` -#### Properties +#### kwd + +``` +def kwd: String; +``` + +The keyword that identifies the command. + +#### description + +``` +def description: String; +``` + +A brief description of the command. + +#### options + +``` +def options: Map[String, String]; +``` + +A list of option names and their descriptions. + +#### args + +``` +def args: Map[String, String]; +``` + +A list of argument names and their descriptions. + +#### numRequiredArgs + +``` +def numRequiredArgs: Int = -1; +``` + +The number of required arguments. If set to `-1` (default), all arguments are considered required. -- `kwd`: The keyword that identifies the command. -- `description`: A brief description of the command. -- `options`: A list of option names and their descriptions. -- `args`: A list of argument names and their descriptions. -- `numRequiredArgs`: The number of required arguments. If set to `-1` (default), all arguments - are considered required. -- `subCmds`: An array of subcommands defined under this command. -- `callback`: A closure function invoked when the command is executed, assuming it has no subcommands. -- `startCallback`: A closure function invoked before processing subcommands. -- `endCallback`: A closure function invoked after processing subcommands. +#### subCmds -#### Methods +``` +def subCmds: Array[SrdRef[CmdDef]]; +``` + +An array of subcommands defined under this command. + +#### callback + +``` +def callback: closure(options: Map[String, String], args: Array[String]); +``` + +A closure function invoked when the command is executed, assuming it has no subcommands. + +#### startCallback + +``` +def startCallback: closure(options: Map[String, String], args: Array[String]); +``` +A closure function invoked before processing subcommands. + +#### endCallback + +``` +def endCallback: closure(options: Map[String, String], args: Array[String]); +``` +A closure function invoked after processing subcommands. -- `findSubCmd(kwd: CharsPtr)`: Searches for a subcommand with the given keyword and returns a reference to it. - Returns an empty reference if no matching subcommand is found. +#### findSubCmd ---- +``` +handler this.findSubCmd(kwd: CharsPtr): SrdRef[CmdDef] +``` + +Searches for a subcommand with the given keyword and returns a reference to it. Returns an empty reference if no matching subcommand is found. ## Global Variables -### `cmdDef` +### cmdDef A global variable that holds the main command definition from which parsing starts. The keyword for this command is ignored, and its argument, option, and subcommand definitions are used instead. ---- - ## Functions -### `initialize` +### initialize ``` -function initialize(); -function initialize(lang: String); -function initialize(lang: String, localizationsPath: String); +function initialize() +function initialize(lang: String) +function initialize(lang: String, localizationsPath: String) ``` -Initializes the library and loads localized translations. The first version uses the system's current -language automatically. The second version allows specifying a custom language. The third version allows -specifying both a custom language and a custom path to the localization files. The first and the second -versions of this function embeds the localizations into the executable during compilation, whereas the -third one loads them at run time. -This function must be called at the beginning of the program before using other functions. +Initializes the library and loads localized translations. The first version uses the system's current +language automatically. The second version allows specifying a custom language. The third version allows specifying both a custom language and a custom path to the localization files. The first and the second versions of this function embeds the localizations into the executable during compilation, whereas the third one loads them at run time. This function must be called at the beginning of the program before using other functions. -### `getLocalizationsPath` +### getLocalizationsPath ``` -function getLocalizationsPath(): String; +function getLocalizationsPath(): String ``` Returns the path to the localization files included with this library. This is typically used internally but it can be used for cases where the user doesn't want to embed the translations into the execcutable and wants instead to ship the localization files with the generated build. -### `printHelp` +### printHelp ``` -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) ``` - Prints the help message for a command and its subcommands. The first version infers the command to explain from program inputs, while the second version accepts an explicit command definition. -**Parameters:** +* `argStartIndex`: The index of the first argument in the program's input (excluding the program name). Typically `1` for precompiled programs, but `2` for interpreted execution since in the case of interpretation the first argument in `Process.args` will be `alusus`. +* `cmdDef`: A reference to the command definition to explain. +* `tabs`: The number of leading spaces for indentation. -- `argStartIndex`: The index of the first argument in the program's input (excluding the program name). - Typically `1` for precompiled programs, but `2` for interpreted execution since in the case of - interpretation the first argument in `Process.args` will be `alusus`. -- `cmdDef`: A reference to the command definition to explain. -- `tabs`: The number of leading spaces for indentation. -- `localizeCommands`: If `true`, keywords, argument names, and option names will be localized in the help output. - -### `parse` +### parse ``` -function parse(argStartIndex: Int); -function parse(cmdDef: SrdRef[CmdDef], argStartIndex: Int): Int; +function parse(argStartIndex: Int) +function parse(cmdDef: SrdRef[CmdDef], argStartIndex: Int): Int ``` -Parses command-line arguments starting from the specified index and invokes the appropriate processing functions. The -first version uses the main command definition (`ProgArg.cmdDef`), while the second version accepts an explicit command -definition. - -**Parameters:** +Parses command-line arguments starting from the specified index and invokes the appropriate processing functions. -- `argStartIndex`: The index of the first argument in the program's input (excluding the program name). Typically `1` - for precompiled programs, but `2` for interpreted execution since in the case of interpretation the first argument in - `Process.args` will be `alusus`. -- `cmdDef`: The command definition to start parsing from. The first version defaults to the main command definition. +The first version uses the main command definition (`ProgArg.cmdDef`), while the second version accepts an explicit command definition and returns the argument index at which parsing stopped. -**Return Value:** +The first version assumes all arguments will be consumed and exits the program with an error if any unknown arguments remain, i.e if the return value isn't at the end of the `Process.args` array. -The second version returns the argument index at which parsing stopped. The first version assumes all arguments will be -consumed and exists the program with an error if any unknown arguments remain, i.e if the return value isn't at the end -of the `Process.args` array. - ---- +* `argStartIndex`: The index of the first argument in the program's input (excluding the program name). Typically `1` for precompiled programs, but `2` for interpreted execution since in the case of interpretation the first argument in `Process.args` will be `alusus`. +* `cmdDef`: The command definition to start parsing from. The first version defaults to the main command definition. ## Example @@ -176,14 +207,10 @@ ProgArg.cmdDef = ProgArg.CmdDef().{ ProgArg.parse(2); ``` ---- - ## Error Handling -- Error messages are printed to `stderr`, and a non-zero exit code is returned if incorrect arguments are passed or - required arguments are missing. - ---- +Error messages are printed to `stderr`, and a non-zero exit code is returned if incorrect arguments are passed or +required arguments are missing. ## Localization @@ -191,11 +218,8 @@ All texts can be localized using the `I18n` module. The `localizeCommands` param names, and argument names are localized when generating help messages with functions like `printHelp` and `printCmdHelp`. ---- - ## License Copyright (C) 2026 Sarmad Abdullah -This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0). See the `COPYING` and `COPYING.LESSER` files for details. - +This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0). See the `COPYING` and `COPYING.LESSER` files for details. \ No newline at end of file