From 70ed134887421ef8bb773f3d9ba9523e28fcca99 Mon Sep 17 00:00:00 2001 From: Hisham Mahgoub Date: Tue, 26 May 2026 00:12:56 +0300 Subject: [PATCH 1/5] changes on the english documentation structure --- README.md | 147 +++++++++++++++++++++++------------------------------- 1 file changed, 63 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index 8614807..6755fbf 100644 --- a/README.md +++ b/README.md @@ -7,21 +7,21 @@ 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 + + ``` import "Apm"; Apm.importFile("Alusus/ProgArg"); @@ -29,14 +29,13 @@ Apm.importFile("Alusus/ProgArg"); Once the library is added to the project, its definitions will be available under the `ProgArg` module. ---- - ## Classes -### `CmdDef` -Defines a command and its associated metadata. +### CmdDef + +Defines a command and its associated metadata. ``` class CmdDef { def kwd: String; @@ -56,106 +55,87 @@ class CmdDef { #### Properties -- `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. +* `kwd` (`String`): The keyword that identifies the command. +* `description` (`String`): A brief description of the command. +* `options` (`Map[String, String]`): A list of option names and their descriptions. +* `args` (`Map[String, String]`): A list of argument names and their descriptions. +* `numRequiredArgs` (`Int`): The number of required arguments. If set to `-1` (default), all arguments are considered required. +* `subCmds` (`Array[SrdRef[CmdDef]]`): An array of subcommands defined under this command. +* `callback` (`closure`): A closure function invoked when the command is executed, assuming it has no subcommands. +* `startCallback` (`closure`): A closure function invoked before processing subcommands. +* `endCallback` (`closure`): A closure function invoked after processing subcommands. -#### Methods +#### findSubCmd -- `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. - ---- +``` +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, localizeCommands: Bool) +function printHelp(cmdDef: SrdRef[CmdDef], tabs: Int, localizeCommands: Bool) ``` - 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. -- `localizeCommands`: If `true`, keywords, argument names, and option names will be localized in the help output. +* `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. -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. +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. -**Parameters:** +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. -- `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. +* `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. -**Return Value:** - -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. +## Example ---- -## Example ``` import "Apm"; @@ -176,26 +156,25 @@ 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 + + All texts can be localized using the `I18n` module. The `localizeCommands` parameter controls whether keywords, option 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. +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. \ No newline at end of file From 41262e9caf53a605d1f6800691597334c8645827 Mon Sep 17 00:00:00 2001 From: Hisham Mahgoub Date: Sun, 31 May 2026 19:14:12 +0300 Subject: [PATCH 2/5] give each method/field its own #### section instead of bullet lists --- README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 54 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 6755fbf..353b1df 100644 --- a/README.md +++ b/README.md @@ -53,17 +53,60 @@ class CmdDef { } ``` -#### Properties - -* `kwd` (`String`): The keyword that identifies the command. -* `description` (`String`): A brief description of the command. -* `options` (`Map[String, String]`): A list of option names and their descriptions. -* `args` (`Map[String, String]`): A list of argument names and their descriptions. -* `numRequiredArgs` (`Int`): The number of required arguments. If set to `-1` (default), all arguments are considered required. -* `subCmds` (`Array[SrdRef[CmdDef]]`): An array of subcommands defined under this command. -* `callback` (`closure`): A closure function invoked when the command is executed, assuming it has no subcommands. -* `startCallback` (`closure`): A closure function invoked before processing subcommands. -* `endCallback` (`closure`): A closure function invoked after processing subcommands. +#### 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. + +#### subCmds +``` +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 From 701bac526eb02a467e3c9dddb418eb9383c00524 Mon Sep 17 00:00:00 2001 From: Hisham Mahgoub Date: Sun, 31 May 2026 19:14:38 +0300 Subject: [PATCH 3/5] restructure Arabic READMEs to match English format --- README.ar.md | 185 +++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 143 insertions(+), 42 deletions(-) diff --git a/README.ar.md b/README.ar.md index e61005d..a7d9dc3 100644 --- a/README.ar.md +++ b/README.ar.md @@ -8,7 +8,7 @@ تطبيقات لغة الأسس البرمجية. تدعم المكتبة الهياكل الهرمية للأوامر والخيارات والوسائط، كما تدعم التوطين بشكل مدمج. ---- + ## المميزات - **تعريف الأوامر**: تعريف الأوامر باستخدام الكلمات المفتاحية، الوصف، الخيارات، والوسائط. @@ -18,7 +18,7 @@ - **تحليل والمعطيات والخيارات**: تحليل المعطيات والخيارات. - **معالجة الأخطاء**: التعامل مع الأخطاء المتعلقة بالمعطيات غير الصحيحة أو الناقصة. ---- + ## الإضافة إلى المشروع @@ -38,7 +38,7 @@ Apm.importFile("Alusus/ProgArg"); بعد إضافة المكتبة إلى المشروع ستكون تعريفاتها متوفرة في الوحدة `بـروجارج` (`ProgArg`). ---- + ## الأصناف @@ -83,44 +83,147 @@ 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، وهي القيمة الافتراضية، تُعتبر جميع المعطيات مطلوبة. + +#### الأوامر_الفرعية (subCmds) + +``` +عرف الأوامر_الفرعية: مـصفوفة[سـندنا[تـعريف_الأمر]]؛ +``` +
+ +``` +def subCmds: Array[SrdRef[CmdDef]]; +``` +
+ +مصفوفة من الأوامر الفرعية المُعرفة للأمر. -- `الكلمة_التعريفية` (`kwd`) - الكلمة المفتاحية التي تحدد الأمر. +#### معالج_التنفيذ (callback) -- `الوصف` (`description`) - وصف موجز للأمر. +``` +عرف معالج_التنفيذ: مغلفة(الخيارات: تـطبيق[نـص, نـص], المعطيات: مـصفوفة[نـص])؛ +``` +
-- `الخيارات` (`options`) - قائمة بأسماء الخيارات ووصفها. +``` +def callback: closure(options: Map[String, String], args: Array[String]); +``` +
-- `المعطيات` (`args`) - قائمة بأسماء المعطيات ووصفها. +دالة مغلفة تستدعى عند معالجة الأمر. تُستدعى هذه الدالة فقط في حال عدم احتواء الأمر على أي أوامر فرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر. + +#### معالج_البدء (startCallback) + +``` +عرف معالج_البدء: مغلفة(الخيارات: تـطبيق[نـص, نـص], المعطيات: مـصفوفة[نـص])؛ +``` +
+ +``` +def startCallback: closure(options: Map[String, String], args: Array[String]); +``` +
+ +دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى قبل البدء بمعالجة الأوامر الفرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر. + +#### معالج_الانتهاء (endCallback) + +``` +عرف معالج_الانتهاء: مغلفة(الخيارات: تـطبيق[نـص, نـص], المعطيات: مـصفوفة[نـص])؛ +``` +
-- `عدد_المعطيات_الإلزامية` (`numRequiredArgs`) - عدد المعطيات المطلوبة. إذا كانت -1، وهي القيمة الافتراضية، تُعتبر جميع المعطيات مطلوبة. +``` +def endCallback: closure(options: Map[String, String], args: Array[String]); +``` +
-- `الأوامر_الفرعية` (`subCmds`) - مصفوفة من الأوامر الفرعية المُعرفة للأمر. +دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى بعد الانتهاء من معالجة الأوامر الفرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر. -- `معالج_التنفيذ` (`callback`) - دالة مغلفة تستدعى عند معالجة الأمر. تُستدعى هذه الدالة فقط في حال عدم احتواء الأمر على أي أوامر - فرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر. +#### جد_أمرا_فرعيا (findSubCmd) -- `معالج_البدء` (`startCallback`) - دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى قبل البدء بمعالجة الأوامر الفرعية. - تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر. +``` +عملية هذا.جد_أمرا_فرعيا(الكلمة_المفتاحية: مـؤشر_محارف): سـندنا[تـعريف_الأمر]؛ +``` +
-- `معالج_الانتهاء` (`endCallback`) - دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى بعد الانتهاء من معالجة الأوامر الفرعية. - تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر. +``` +handler this.findSubCmd(kwd: CharsPtr): SrdRef[CmdDef] +``` +
-**العمليات:** +تبحث عن أمر فرعي بالكلمة المفتاحية المحددة وترجع مرجعا إليه. ترجع مرجعا فارغا إذا لم تجد أمرا فرعيا مطابقا. -- `جد_أمرا_فرعيا` (`findSubCmd`): تبحث عن أمر فرعي بالكلمة المفتاحية المحددة وترجع مرجعا إليه. - ترجع مرجعا فارغا إذا لم تجد أمرا فرعيا مطابقا. ---- ## المتغيرات العمومية @@ -129,7 +232,7 @@ class CmdDef { متغير عمومي يحمل تعريف الأمر الرئيسي الذي تبدأ منه عملية التحليل. تُهمل الكلمة التعريفية في هذا الأمر وتستخدم منه تعريفات المعطيات والخيارات والأوامر الفرعية. ---- + ## الدالات @@ -193,14 +296,15 @@ function printHelp(cmdDef: SrdRef[CmdDef], tabs: Int, localizeCommands: Bool); تطبع رسالة التعليمات لأمر مع أوامره الفرعية. النسخة الأولى تستنتج الأمر المراد شرحه من مدخلات البرنامج بينما النسخة الثانية تستلم الأمر المراد شرحه. -**المعطيات:** - - `تسلسل_أول_معطى` (`argStartIndex`): تسلسل المعطى الأول ضمن معطيات البرنامج بعد استثناء اسم البرنامج. في العادة يكون هذا المعطى 1 في حالة ترجمة البرنامج مسبقًا، أما في حالة التنفيذ أثناء الترجمة فسيطون هذا المعطى 2 لأن المعطى الأول سيكون لاسم مترجم الأسس بينما الثاني لاسم ملف الشفرة المصدرية التي يُراد تنفيذها. + - `تعريف_الأمر` (`cmdDef`): مرجع لتعريف الأمر المراد شرحه. + - `إزاحات` (`tabs`): عدد المسافات البادئة لإزاحة الإخراج. + - `وطن_الأوامر` (`localizeCommands`): إذا كان هذا المعطى 1 تُوطّن الكلمات المفتاحية وأسماء المعطيات والخيارات عند طباعة الشرح، وإلا فتُطبع بصيغتها الأصلية دون ترجمة. @@ -224,22 +328,19 @@ function parse(cmdDef: SrdRef[CmdDef], argStartIndex: Int): Int; النسخة الثانية تستلم تعريف الأمر المراد بدء التحليل منه، بينما تبدأ النسخة الأولى من الأمر الرئيسي، أي `بـروجارج.تعريف_الأمر` (`ProgArg.cmdDef`). -**المعطيات:** +ترجع الصيغة الثانية تسلسل المعطى الذي وصلت إليه عملية التحليل بعد استخدام كل المعطيات الممكنة. الصيغة +الأولى لا ترجع التسلسل وتفترض بدلا من ذلك أن تُستخدم كل المعطيات الممرة للبرنامج، وفي حال بقاء أي معطى +بعد الانتهاء من التحليل تغلق البرنامج مع طباعة إشعار خطأ حول معطى غير معروف. - `تسلسل_أول_معطى` (`argStartIndex`): تسلسل المعطى الأول ضمن معطيات البرنامج بعد استثناء اسم البرنامج. في العادة يكون هذا المعطى 1 في حالة ترجمة البرنامج مسبقًا، أما في حالة التنفيذ أثناء الترجمة فسيطون هذا المعطى 2 لأن المعطى الأول سيكون لاسم مترجم الأسس بينما الثاني لاسم ملف الشفرة المصدرية التي يُراد تنفيذها. + - `تعريف_الأمر` (`cmdDef`): الأمر الذي سيبدأ منه البحث عن الخيارات والمعطيات والأوامر الفرعية. في حالة النسخة الأولى يُعتمد الأمر الرئيسي المعرف على مستوى المكتبة. -**القيمة المرجعة:** -ترجع الصيغة الثانية تسلسل المعطى الذي وصلت إليه عملية التحليل بعد استخدام كل المعطيات الممكنة. الصيغة -الأولى لا ترجع التسلسل وتفترض بدلا من ذلك أن تُستخدم كل المعطيات الممرة للبرنامج، وفي حال بقاء أي معطى -بعد الانتهاء من التحليل تغلق البرنامج مع طباعة إشعار خطأ حول معطى غير معروف. - ---- ## مثال @@ -285,20 +386,20 @@ ProgArg.parse(2); ---- + ## معالجة الأخطاء - تطبع رسائل الخطأ إلى `stderr` وتخرج برمز غير صفري إذا تم تمرير وسائط غير صحيحة أو إذا كانت هناك وسائط مطلوبة مفقودة. ---- + ## التوطين يمكن توطين جميع النصوص باستخدام وحدة `I18n`. وسيط `localizeCommands` يوجه المكتبة لطباعة النسخ الموطنة من الكلمات المفتاحية وأسماء الخيارات عند إنشاء رسائل التعليمات في الدوال مثل `printHelp` و`printCmdHelp`. ---- + ## الرخصة From a0694d3b147639552078c5f32a9f346545a7f3d1 Mon Sep 17 00:00:00 2001 From: Hisham Mahgoub Date: Tue, 2 Jun 2026 19:46:58 +0300 Subject: [PATCH 4/5] added one space between headings , Divs and content --- README.ar.md | 151 ++++++++++++++++++++++++++------------------------- README.md | 41 +++++++------- 2 files changed, 98 insertions(+), 94 deletions(-) diff --git a/README.ar.md b/README.ar.md index a7d9dc3..a6c3947 100644 --- a/README.ar.md +++ b/README.ar.md @@ -1,50 +1,46 @@ # ProgArg -[[English]](README.md) -
+[[English]](README.md) ## نظرة عامة توفر مكتبة **ProgArg** حلاً مرنًا وقويًا لتعريف وتحليل الوسائط والأوامر الممررة عبر سطر الأوامر في تطبيقات لغة الأسس البرمجية. تدعم المكتبة الهياكل الهرمية للأوامر والخيارات والوسائط، كما تدعم التوطين بشكل مدمج. - - ## المميزات -- **تعريف الأوامر**: تعريف الأوامر باستخدام الكلمات المفتاحية، الوصف، الخيارات، والوسائط. -- **الأوامر الفرعية**: دعم الهياكل الهرمية للأوامر. -- **التوطين**: دعم مدمج للتدويل باستخدام `Alusus/I18n`. -- **إظهار التعليمات**: إنشاء رسائل تعليمات تلقائيًا. -- **تحليل والمعطيات والخيارات**: تحليل المعطيات والخيارات. -- **معالجة الأخطاء**: التعامل مع الأخطاء المتعلقة بالمعطيات غير الصحيحة أو الناقصة. - - +* **تعريف الأوامر**: تعريف الأوامر باستخدام الكلمات المفتاحية، الوصف، الخيارات، والوسائط. +* **الأوامر الفرعية**: دعم الهياكل الهرمية للأوامر. +* **التوطين**: دعم مدمج للتدويل باستخدام `Alusus/I18n`. +* **إظهار التعليمات**: إنشاء رسائل تعليمات تلقائيًا. +* **تحليل والمعطيات والخيارات**: تحليل المعطيات والخيارات. +* **معالجة الأخطاء**: التعامل مع الأخطاء المتعلقة بالمعطيات غير الصحيحة أو الناقصة. ## الإضافة إلى المشروع +
+ ``` اشمل "مـحا"؛ مـحا.اشمل_ملف("Alusus/ProgArg"، "بـروجارج.أسس")؛ ``` -
+
``` import "Apm"; Apm.importFile("Alusus/ProgArg"); ``` -
- بعد إضافة المكتبة إلى المشروع ستكون تعريفاتها متوفرة في الوحدة `بـروجارج` (`ProgArg`). - - ## الأصناف ### `تـعريف_الأمر` (`CmdDef`) + يعرّف الأمر والبيانات الوصفية المرتبطة به. +
+ ``` صـنف تـعريف_الأمر { عرف الكلمة_التعريفية: نـص؛ @@ -62,7 +58,7 @@ Apm.importFile("Alusus/ProgArg"); } ``` -
+
``` class CmdDef { @@ -81,150 +77,165 @@ 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، وهي القيمة الافتراضية، تُعتبر جميع المعطيات مطلوبة. #### الأوامر_الفرعية (subCmds) +
+ ``` عرف الأوامر_الفرعية: مـصفوفة[سـندنا[تـعريف_الأمر]]؛ ``` -
+ +
``` 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]); ``` -
دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى قبل البدء بمعالجة الأوامر الفرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر. #### معالج_الانتهاء (endCallback) +
+ ``` عرف معالج_الانتهاء: مغلفة(الخيارات: تـطبيق[نـص, نـص], المعطيات: مـصفوفة[نـص])؛ ``` -
+ +
``` def endCallback: closure(options: Map[String, String], args: Array[String]); ``` -
دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى بعد الانتهاء من معالجة الأوامر الفرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر. #### جد_أمرا_فرعيا (findSubCmd) +
+ ``` عملية هذا.جد_أمرا_فرعيا(الكلمة_المفتاحية: مـؤشر_محارف): سـندنا[تـعريف_الأمر]؛ ``` -
+ +
``` handler this.findSubCmd(kwd: CharsPtr): SrdRef[CmdDef] ``` -
تبحث عن أمر فرعي بالكلمة المفتاحية المحددة وترجع مرجعا إليه. ترجع مرجعا فارغا إذا لم تجد أمرا فرعيا مطابقا. - - ## المتغيرات العمومية ### `تعريف_الأمر` (`cmdDef`) @@ -232,19 +243,19 @@ handler this.findSubCmd(kwd: CharsPtr): SrdRef[CmdDef] متغير عمومي يحمل تعريف الأمر الرئيسي الذي تبدأ منه عملية التحليل. تُهمل الكلمة التعريفية في هذا الأمر وتستخدم منه تعريفات المعطيات والخيارات والأوامر الفرعية. - - ## الدالات ### `هيئ` (`initialize`) +
+ ``` دالة هيئ()؛ دالة هيئ(اللغة: نـص)؛ دالة هيئ(اللغة: نـص، مسار_التوطين: نـص)؛ ``` -
+
``` function initialize(); @@ -252,8 +263,6 @@ function initialize(lang: String); function initialize(lang: String, localizationsPath: String); ``` -
- تُهيئ المكتبة وتحمل الترجمات المخصصة باللغة المعطاة. النسخة الأولى تستخدم لغة النظام الحالية تلقائيا. النسخة الثانية تسمح بتحديد لغة مخصصة. النسخة الثالثة تسمح بتحديد لغة مخصصة ومسار مخصص لملفات التوطين. النسختان الأولى والثانية تضمنان الترجمات في البرنامج التنفيذي أثناء الترجمة، بينما تحمل النسخة الثالثة @@ -262,68 +271,68 @@ function initialize(lang: String, localizationsPath: String); ### `هات_مسار_الترجمات` (`getLocalizationsPath`) +
+ ``` دالة هات_مسار_الترجمات(): نـص؛ ``` -
+
``` function getLocalizationsPath(): String; ``` -
- ترجع مسار ملفات الترجمة المرفقة مع هذه المكتبة. هذه الدالة تُستخدم داخليا عادة ولكنها تكون مفيدة في حال رغب المستخدم بإرفاق ملفات الترجمة مع برنامجه عند النشر لتحميلها أثناء التنفيذ. ### `إطبع_المساعدة` (`printHelp`) +
+ ``` دالة اطبع_المساعدة(تسلسل_أول_معطى: صـحيح، وطن_الأوامر: ثـنائي)؛ دالة اطبع_المساعدة(تعريف_الأمر: سـندنا[تـعريف_الأمر]، إزاحات: صـحيح، وطن_الأوامر: ثـنائي)؛ ``` -
+
``` function printHelp(argStartIndex: Int, localizeCommands: Bool); function printHelp(cmdDef: SrdRef[CmdDef], tabs: Int, localizeCommands: Bool); ``` -
- تطبع رسالة التعليمات لأمر مع أوامره الفرعية. النسخة الأولى تستنتج الأمر المراد شرحه من مدخلات البرنامج بينما النسخة الثانية تستلم الأمر المراد شرحه. -- `تسلسل_أول_معطى` (`argStartIndex`): تسلسل المعطى الأول ضمن معطيات البرنامج بعد استثناء اسم البرنامج. +* `تسلسل_أول_معطى` (`argStartIndex`): تسلسل المعطى الأول ضمن معطيات البرنامج بعد استثناء اسم البرنامج. في العادة يكون هذا المعطى 1 في حالة ترجمة البرنامج مسبقًا، أما في حالة التنفيذ أثناء الترجمة فسيطون هذا المعطى 2 لأن المعطى الأول سيكون لاسم مترجم الأسس بينما الثاني لاسم ملف الشفرة المصدرية التي يُراد تنفيذها. -- `تعريف_الأمر` (`cmdDef`): مرجع لتعريف الأمر المراد شرحه. +* `تعريف_الأمر` (`cmdDef`): مرجع لتعريف الأمر المراد شرحه. -- `إزاحات` (`tabs`): عدد المسافات البادئة لإزاحة الإخراج. +* `إزاحات` (`tabs`): عدد المسافات البادئة لإزاحة الإخراج. -- `وطن_الأوامر` (`localizeCommands`): إذا كان هذا المعطى 1 تُوطّن الكلمات المفتاحية وأسماء المعطيات +* `وطن_الأوامر` (`localizeCommands`): إذا كان هذا المعطى 1 تُوطّن الكلمات المفتاحية وأسماء المعطيات والخيارات عند طباعة الشرح، وإلا فتُطبع بصيغتها الأصلية دون ترجمة. ### `حلل` (`parse`) +
+ ``` دالة حلل(تسلسل_أول_معطى: صـحيح)؛ دالة حلل(تعريف_الأمر: سـندنا[تـعريف_الأمر]، تسلسل_أول_معطى: صـحيح): صـحيح؛ ``` -
+
``` function parse(argStartIndex: Int); function parse(cmdDef: SrdRef[CmdDef], argStartIndex: Int): Int; ``` -
- تحلل المعطيات الممررة للبرنامج بدءًا من التسلسل المحدد وتستدعي دالات المعالجة لتلك الأوامر. النسخة الثانية تستلم تعريف الأمر المراد بدء التحليل منه، بينما تبدأ النسخة الأولى من الأمر الرئيسي، أي `بـروجارج.تعريف_الأمر` (`ProgArg.cmdDef`). @@ -332,18 +341,18 @@ function parse(cmdDef: SrdRef[CmdDef], argStartIndex: Int): Int; الأولى لا ترجع التسلسل وتفترض بدلا من ذلك أن تُستخدم كل المعطيات الممرة للبرنامج، وفي حال بقاء أي معطى بعد الانتهاء من التحليل تغلق البرنامج مع طباعة إشعار خطأ حول معطى غير معروف. -- `تسلسل_أول_معطى` (`argStartIndex`): تسلسل المعطى الأول ضمن معطيات البرنامج بعد استثناء اسم البرنامج. +* `تسلسل_أول_معطى` (`argStartIndex`): تسلسل المعطى الأول ضمن معطيات البرنامج بعد استثناء اسم البرنامج. في العادة يكون هذا المعطى 1 في حالة ترجمة البرنامج مسبقًا، أما في حالة التنفيذ أثناء الترجمة فسيطون هذا المعطى 2 لأن المعطى الأول سيكون لاسم مترجم الأسس بينما الثاني لاسم ملف الشفرة المصدرية التي يُراد تنفيذها. -- `تعريف_الأمر` (`cmdDef`): الأمر الذي سيبدأ منه البحث عن الخيارات والمعطيات والأوامر الفرعية. في حالة +* `تعريف_الأمر` (`cmdDef`): الأمر الذي سيبدأ منه البحث عن الخيارات والمعطيات والأوامر الفرعية. في حالة النسخة الأولى يُعتمد الأمر الرئيسي المعرف على مستوى المكتبة. - - ## مثال +
+ ``` اشمل "مـحا"؛ مـحا.اشمل_ملف("Alusus/ProgArg"، "بـروجارج.أسس")؛ @@ -363,7 +372,7 @@ function parse(cmdDef: SrdRef[CmdDef], argStartIndex: Int): Int; بـروجارج.حلل(2)؛ ``` -
+
``` import "Apm"; @@ -384,28 +393,20 @@ ProgArg.cmdDef = ProgArg.CmdDef().{ ProgArg.parse(2); ``` -
- - - ## معالجة الأخطاء -- تطبع رسائل الخطأ إلى `stderr` وتخرج برمز غير صفري إذا تم تمرير وسائط غير صحيحة أو إذا كانت هناك وسائط مطلوبة مفقودة. - - +* تطبع رسائل الخطأ إلى `stderr` وتخرج برمز غير صفري إذا تم تمرير وسائط غير صحيحة أو إذا كانت هناك وسائط مطلوبة مفقودة. ## التوطين يمكن توطين جميع النصوص باستخدام وحدة `I18n`. وسيط `localizeCommands` يوجه المكتبة لطباعة النسخ الموطنة من الكلمات المفتاحية وأسماء الخيارات عند إنشاء رسائل التعليمات في الدوال مثل `printHelp` و`printCmdHelp`. - - ## الرخصة حقوق النشر © 2026 سرمد خالد عبد الله هذا المشروع مرخص بموجب رخصة غنو العمومية الصغرى الإصدار 3.0 (LGPL-3.0). راجع ملفات `COPYING` و `COPYING.LESSER` للحصول على التفاصيل. -
+ diff --git a/README.md b/README.md index 353b1df..936b9ea 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # ProgArg + [[العربية]](README.ar.md) ## Overview @@ -9,8 +10,6 @@ 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`. @@ -20,8 +19,6 @@ command structures, options, and arguments, as well as built-in localization. ## Adding to a Project - - ``` import "Apm"; Apm.importFile("Alusus/ProgArg"); @@ -31,11 +28,10 @@ Once the library is added to the project, its definitions will be available unde ## Classes - - ### CmdDef Defines a command and its associated metadata. + ``` class CmdDef { def kwd: String; @@ -54,71 +50,85 @@ class CmdDef { ``` #### 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. #### subCmds + ``` 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 ``` 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 A global variable that holds the main command definition from which parsing starts. The keyword for @@ -126,8 +136,6 @@ this command is ignored, and its argument, option, and subcommand definitions ar ## Functions - - ### initialize ``` @@ -135,6 +143,7 @@ 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. @@ -143,6 +152,7 @@ language automatically. The second version allows specifying a custom language. ``` 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. @@ -167,6 +177,7 @@ explain from program inputs, while the second version accepts an explicit comman 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 and returns the argument index at which parsing stopped. @@ -178,8 +189,6 @@ The first version assumes all arguments will be consumed and exits the program w ## Example - - ``` import "Apm"; Apm.importFile("Alusus/ProgArg"); @@ -201,23 +210,17 @@ 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. ## Localization - - All texts can be localized using the `I18n` module. The `localizeCommands` parameter controls whether keywords, option 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. \ No newline at end of file From 7448b96b10d0a5dd368755eac74f2b5beb4d3299 Mon Sep 17 00:00:00 2001 From: Hisham Mahgoub Date: Tue, 2 Jun 2026 20:18:18 +0300 Subject: [PATCH 5/5] =?UTF-8?q?=D8=AA=D8=B5=D8=AD=D9=8A=D8=AD=20=D8=A8?= =?UTF-8?q?=D8=B9=D8=B6=20=D8=A7=D9=84=D8=AA=D8=B9=D8=B1=D9=8A=D9=81=D8=A7?= =?UTF-8?q?=D8=AA=20=D8=A7=D9=84=D8=AE=D8=A7=D8=B7=D8=A6=D8=A9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.ar.md | 129 +++++++++++++++++++++++++-------------------------- README.md | 5 +- 2 files changed, 66 insertions(+), 68 deletions(-) diff --git a/README.ar.md b/README.ar.md index a6c3947..a6183aa 100644 --- a/README.ar.md +++ b/README.ar.md @@ -1,5 +1,7 @@ # ProgArg +
+ [[English]](README.md) ## نظرة عامة @@ -17,30 +19,28 @@ ## الإضافة إلى المشروع -
- ``` اشمل "مـحا"؛ مـحا.اشمل_ملف("Alusus/ProgArg"، "بـروجارج.أسس")؛ ``` -
+
``` import "Apm"; Apm.importFile("Alusus/ProgArg"); ``` +
+ بعد إضافة المكتبة إلى المشروع ستكون تعريفاتها متوفرة في الوحدة `بـروجارج` (`ProgArg`). ## الأصناف -### `تـعريف_الأمر` (`CmdDef`) +### تـعريف_الأمر (CmdDef) يعرّف الأمر والبيانات الوصفية المرتبطة به. -
- ``` صـنف تـعريف_الأمر { عرف الكلمة_التعريفية: نـص؛ @@ -58,7 +58,7 @@ Apm.importFile("Alusus/ProgArg"); } ``` -
+
``` class CmdDef { @@ -77,177 +77,178 @@ class CmdDef { } ``` -#### الكلمة_التعريفية (kwd) +
-
+#### الكلمة_التعريفية (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، وهي القيمة الافتراضية، تُعتبر جميع المعطيات مطلوبة. #### الأوامر_الفرعية (subCmds) -
- ``` عرف الأوامر_الفرعية: مـصفوفة[سـندنا[تـعريف_الأمر]]؛ ``` -
+
``` 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]); ``` +
+ دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى قبل البدء بمعالجة الأوامر الفرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر. #### معالج_الانتهاء (endCallback) -
- ``` عرف معالج_الانتهاء: مغلفة(الخيارات: تـطبيق[نـص, نـص], المعطيات: مـصفوفة[نـص])؛ ``` -
+
``` def endCallback: closure(options: Map[String, String], args: Array[String]); ``` +
+ دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى بعد الانتهاء من معالجة الأوامر الفرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر. #### جد_أمرا_فرعيا (findSubCmd) -
- ``` عملية هذا.جد_أمرا_فرعيا(الكلمة_المفتاحية: مـؤشر_محارف): سـندنا[تـعريف_الأمر]؛ ``` -
+
``` handler this.findSubCmd(kwd: CharsPtr): SrdRef[CmdDef] ``` +
+ تبحث عن أمر فرعي بالكلمة المفتاحية المحددة وترجع مرجعا إليه. ترجع مرجعا فارغا إذا لم تجد أمرا فرعيا مطابقا. ## المتغيرات العمومية -### `تعريف_الأمر` (`cmdDef`) +### تعريف_الأمر (cmdDef) متغير عمومي يحمل تعريف الأمر الرئيسي الذي تبدأ منه عملية التحليل. تُهمل الكلمة التعريفية في هذا الأمر وتستخدم منه تعريفات المعطيات والخيارات والأوامر الفرعية. ## الدالات -### `هيئ` (`initialize`) - -
+### هيئ (initialize) ``` دالة هيئ()؛ @@ -255,7 +256,7 @@ handler this.findSubCmd(kwd: CharsPtr): SrdRef[CmdDef] دالة هيئ(اللغة: نـص، مسار_التوطين: نـص)؛ ``` -
+
``` function initialize(); @@ -263,45 +264,47 @@ function initialize(lang: String); function initialize(lang: String, localizationsPath: String); ``` +
+ تُهيئ المكتبة وتحمل الترجمات المخصصة باللغة المعطاة. النسخة الأولى تستخدم لغة النظام الحالية تلقائيا. النسخة الثانية تسمح بتحديد لغة مخصصة. النسخة الثالثة تسمح بتحديد لغة مخصصة ومسار مخصص لملفات التوطين. النسختان الأولى والثانية تضمنان الترجمات في البرنامج التنفيذي أثناء الترجمة، بينما تحمل النسخة الثالثة الترجمات عند تنفيذ البرنامج. يجب استدعاء هذه الدالة في بداية البرنامج قبل استخدام الدالات الأخرى. -### `هات_مسار_الترجمات` (`getLocalizationsPath`) - -
+### هات_مسار_الترجمات (getLocalizationsPath) ``` دالة هات_مسار_الترجمات(): نـص؛ ``` -
+
``` 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); ``` +
+ تطبع رسالة التعليمات لأمر مع أوامره الفرعية. النسخة الأولى تستنتج الأمر المراد شرحه من مدخلات البرنامج بينما النسخة الثانية تستلم الأمر المراد شرحه. @@ -314,25 +317,22 @@ function printHelp(cmdDef: SrdRef[CmdDef], tabs: Int, localizeCommands: Bool); * `إزاحات` (`tabs`): عدد المسافات البادئة لإزاحة الإخراج. -* `وطن_الأوامر` (`localizeCommands`): إذا كان هذا المعطى 1 تُوطّن الكلمات المفتاحية وأسماء المعطيات - والخيارات عند طباعة الشرح، وإلا فتُطبع بصيغتها الأصلية دون ترجمة. - -### `حلل` (`parse`) - -
+### حلل (parse) ``` دالة حلل(تسلسل_أول_معطى: صـحيح)؛ دالة حلل(تعريف_الأمر: سـندنا[تـعريف_الأمر]، تسلسل_أول_معطى: صـحيح): صـحيح؛ ``` -
+
``` function parse(argStartIndex: Int); function parse(cmdDef: SrdRef[CmdDef], argStartIndex: Int): Int; ``` +
+ تحلل المعطيات الممررة للبرنامج بدءًا من التسلسل المحدد وتستدعي دالات المعالجة لتلك الأوامر. النسخة الثانية تستلم تعريف الأمر المراد بدء التحليل منه، بينما تبدأ النسخة الأولى من الأمر الرئيسي، أي `بـروجارج.تعريف_الأمر` (`ProgArg.cmdDef`). @@ -351,8 +351,6 @@ function parse(cmdDef: SrdRef[CmdDef], argStartIndex: Int): Int; ## مثال -
- ``` اشمل "مـحا"؛ مـحا.اشمل_ملف("Alusus/ProgArg"، "بـروجارج.أسس")؛ @@ -372,7 +370,7 @@ function parse(cmdDef: SrdRef[CmdDef], argStartIndex: Int): Int; بـروجارج.حلل(2)؛ ``` -
+
``` import "Apm"; @@ -393,6 +391,8 @@ ProgArg.cmdDef = ProgArg.CmdDef().{ ProgArg.parse(2); ``` +
+ ## معالجة الأخطاء * تطبع رسائل الخطأ إلى `stderr` وتخرج برمز غير صفري إذا تم تمرير وسائط غير صحيحة أو إذا كانت هناك وسائط مطلوبة مفقودة. @@ -408,5 +408,4 @@ ProgArg.parse(2); هذا المشروع مرخص بموجب رخصة غنو العمومية الصغرى الإصدار 3.0 (LGPL-3.0). راجع ملفات `COPYING` و `COPYING.LESSER` للحصول على التفاصيل. - - +
diff --git a/README.md b/README.md index 936b9ea..2b12d21 100644 --- a/README.md +++ b/README.md @@ -160,8 +160,8 @@ instead to ship the localization files with the generated build. ### 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. @@ -169,7 +169,6 @@ explain from program inputs, while the second version accepts an explicit comman * `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