Skip to content

Latest commit

 

History

History
273 lines (197 loc) · 11.7 KB

readme.ar.md

File metadata and controls

273 lines (197 loc) · 11.7 KB

ProgArg

[English]

نظرة عامة

توفر مكتبة ProgArg حلاً مرنًا وقويًا لتعريف وتحليل الوسائط والأوامر الممررة عبر سطر الأوامر في تطبيقات لغة الأسس البرمجية. تدعم المكتبة الهياكل الهرمية للأوامر والخيارات والوسائط، كما تدعم التوطين بشكل مدمج.

المميزات

  • تعريف الأوامر: تعريف الأوامر باستخدام الكلمات المفتاحية، الوصف، الخيارات، والوسائط.
  • الأوامر الفرعية: دعم الهياكل الهرمية للأوامر.
  • التوطين: دعم مدمج للتدويل باستخدام Alusus/I18n.
  • إظهار التعليمات: إنشاء رسائل تعليمات تلقائيًا.
  • تحليل والمعطيات والخيارات: تحليل المعطيات والخيارات.
  • معالجة الأخطاء: التعامل مع الأخطاء المتعلقة بالمعطيات غير الصحيحة أو الناقصة.

الإضافة إلى المشروع

اشمل "مـحا"؛
مـحا.اشمل_ملف("Alusus/ProgArg"، "بـروجارج.أسس")؛

import "Apm";
Apm.importFile("Alusus/ProgArg");

بعد إضافة المكتبة إلى المشروع ستكون تعريفاتها متوفرة في الوحدة بـروجارج (ProgArg).

الأصناف

تـعريف_الأمر (CmdDef)

يعرّف الأمر والبيانات الوصفية المرتبطة به.

صـنف تـعريف_الأمر {
    عرف الكلمة_التعريفية: نـص؛
    عرف الوصف: نـص؛
    عرف الخيارات: تـطبيق[نـص, نـص]؛
    عرف المعطيات: تـطبيق[نـص, نـص]؛
    عرف عدد_المعطيات_الإلزامية: صـحيح = -1؛
    عرف الأوامر_الفرعية: مـصفوفة[سـندنا[تـعريف_الأمر]]؛
    عرف معالج_التنفيذ: مغلفة(الخيارات: تـطبيق[نـص, نـص], المعطيات: مـصفوفة[نـص])؛
    عرف معالج_البدء: مغلفة(الخيارات: تـطبيق[نـص, نـص], المعطيات: مـصفوفة[نـص])؛
    عرف معالج_الانتهاء: مغلفة(الخيارات: تـطبيق[نـص, نـص], المعطيات: مـصفوفة[نـص])؛

    عملية هذا_الصنف(): سـندنا[تـعريف_الأمر]؛    
}

class CmdDef {
    def kwd: String;
    def description: String;
    def options: Map[String, String];
    def args: Map[String, String];
    def numRequiredArgs: Int = -1;
    def subCmds: Array[SrdRef[CmdDef]];
    def callback: closure(options: Map[String, String], args: Array[String]);
    def startCallback: closure(options: Map[String, String], args: Array[String]);
    def endCallback: closure(options: Map[String, String], args: Array[String]);
    
    handler this_type(): SrdRef[CmdDef];
}

الخصائص:

  • الكلمة_التعريفية (kwd) الكلمة المفتاحية التي تحدد الأمر.

  • الوصف (description) وصف موجز للأمر.

  • الخيارات (options) قائمة بأسماء الخيارات ووصفها.

  • المعطيات (args) قائمة بأسماء المعطيات ووصفها.

  • عدد_المعطيات_الإلزامية (numRequiredArgs) عدد المعطيات المطلوبة. إذا كانت -1، وهي القيمة الافتراضية، تُعتبر جميع المعطيات مطلوبة.

  • الأوامر_الفرعية (subCmds) مصفوفة من الأوامر الفرعية المُعرفة للأمر.

  • معالج_التنفيذ (callback) دالة مغلفة تستدعى عند معالجة الأمر. تُستدعى هذه الدالة فقط في حال عدم احتواء الأمر على أي أوامر فرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر.

  • معالج_البدء (startCallback) دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى قبل البدء بمعالجة الأوامر الفرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر.

  • معالج_الانتهاء (endCallback) دالة مغلفة تستدعى في حال احتواء الأمر على أوامر فرعية. تستدعى بعد الانتهاء من معالجة الأوامر الفرعية. تستلم الدالة قائمة الخيارات والأوامر المتعلقة بهذا الأمر.

المتغيرات العمومية

تعريف_الأمر (cmdDef)

متغير عمومي يحمل تعريف الأمر الرئيسي الذي تبدأ منه عملية التحليل. تُهمل الكلمة التعريفية في هذا الأمر وتستخدم منه تعريفات المعطيات والخيارات والأوامر الفرعية.

الدالات

هيئ (initialize)

دالة هيئ()؛
دالة هيئ(اللغة: مـؤشر_محارف)؛

function initialize();
function initialize(lang: CharsPtr);

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

إطبع_المساعدة (printHelp)

دالة اطبع_المساعدة(تسلسل_أول_معطى: صـحيح، وطن_الأوامر: ثـنائي)؛
دالة اطبع_المساعدة(تعريف_الأمر: سـندنا[تـعريف_الأمر]، إزاحات: صـحيح، وطن_الأوامر: ثـنائي)؛

function printHelp(argStartIndex: Int, localizeCommands: Bool);
function printHelp(cmdDef: SrdRef[CmdDef], tabs: Int, localizeCommands: Bool);

تطبع رسالة التعليمات لأمر مع أوامره الفرعية. النسخة الأولى تستنتج الأمر المراد شرحه من مدخلات البرنامج بينما النسخة الثانية تستلم الأمر المراد شرحه.

المعطيات:

  • تسلسل_أول_معطى (argStartIndex): تسلسل المعطى الأول ضمن معطيات البرنامج بعد استثناء اسم البرنامج. في العادة يكون هذا المعطى 1 في حالة ترجمة البرنامج مسبقًا، أما في حالة التنفيذ أثناء الترجمة فسيطون هذا المعطى 2 لأن المعطى الأول سيكون لاسم مترجم الأسس بينما الثاني لاسم ملف الشفرة المصدرية التي يُراد تنفيذها.
  • تعريف_الأمر (cmdDef): مرجع لتعريف الأمر المراد شرحه.
  • إزاحات (tabs): عدد المسافات البادئة لإزاحة الإخراج.
  • وطن_الأوامر (localizeCommands): إذا كان هذا المعطى 1 تُوطّن الكلمات المفتاحية وأسماء المعطيات والخيارات عند طباعة الشرح، وإلا فتُطبع بصيغتها الأصلية دون ترجمة.

حلل (parse)

دالة حلل(تسلسل_أول_معطى: صـحيح)؛
دالة حلل(تعريف_الأمر: سـندنا[تـعريف_الأمر]، تسلسل_أول_معطى: صـحيح): صـحيح؛

function parse(argStartIndex: Int);
function parse(cmdDef: SrdRef[CmdDef], argStartIndex: Int): Int;

تحلل المعطيات الممررة للبرنامج بدءًا من التسلسل المحدد وتستدعي دالات المعالجة لتلك الأوامر. النسخة الثانية تستلم تعريف الأمر المراد بدء التحليل منه، بينما تبدأ النسخة الأولى من الأمر الرئيسي، أي بـروجارج.تعريف_الأمر (ProgArg.cmdDef).

المعطيات:

  • تسلسل_أول_معطى (argStartIndex): تسلسل المعطى الأول ضمن معطيات البرنامج بعد استثناء اسم البرنامج. في العادة يكون هذا المعطى 1 في حالة ترجمة البرنامج مسبقًا، أما في حالة التنفيذ أثناء الترجمة فسيطون هذا المعطى 2 لأن المعطى الأول سيكون لاسم مترجم الأسس بينما الثاني لاسم ملف الشفرة المصدرية التي يُراد تنفيذها.
  • تعريف_الأمر (cmdDef): الأمر الذي سيبدأ منه البحث عن الخيارات والمعطيات والأوامر الفرعية. في حالة النسخة الأولى يُعتمد الأمر الرئيسي المعرف على مستوى المكتبة.

القيمة المرجعة:

ترجع الصيغة الثانية تسلسل المعطى الذي وصلت إليه عملية التحليل بعد استخدام كل المعطيات الممكنة. الصيغة الأولى لا ترجع التسلسل وتفترض بدلا من ذلك أن تُستخدم كل المعطيات الممرة للبرنامج، وفي حال بقاء أي معطى بعد الانتهاء من التحليل تغلق البرنامج مع طباعة إشعار خطأ حول معطى غير معروف.

مثال

اشمل "مـحا"؛
مـحا.اشمل_ملف("Alusus/ProgArg"، "بـروجارج.أسس")؛

بـروجارج.هيئ()؛
بـروجارج.تعريف_الأمر = بـروجارج.تـعريف_الأمر().{
    المعطيات = تـطبيق[نـص, نـص]()
        .حدد(نـص("معطى1"), نـص("شرح المعطى 1."))
        .حدد(نـص("معطى2"), نـص("nشرح المعطى 2."))؛
    الخيارات = تـطبيق[نـص, نـص]()
        .حدد(نـص("خيار1"), نـص("شرح الخيار 1."))
        .حدد(نـص("خيار2"), نـص("شرح الخيار 2."))؛
    معالج_التنفيذ = مغلفة (الخيارات: تـطبيق[نـص, نـص], المعطيات: مـصفوفة[نـص]) {
        // معالجة المعطيات والخيارات هنا.
    }؛
}
بـروجارج.حلل(2)؛

import "Apm";
Apm.importFile("Alusus/ProgArg");

ProgArg.initialize();
ProgArg.cmdDef = ProgArg.CmdDef().{
    args = Map[String, String]()
        .set(String("arg1"), String("This is description for argument 1."))
        .set(String("arg2"), String("nThis is description for argument 2."));
    options = Map[String, String]()
        .set(String("opt1"), String("This is description for option 1."))
        .set(String("opt2"), String("This is description for option 2."));
    callback = closure (options: Map[String, String], args: Array[String]) {
        // Process command options and arguments here.
    };
}
ProgArg.parse(2);

معالجة الأخطاء

  • تطبع رسائل الخطأ إلى stderr وتخرج برمز غير صفري إذا تم تمرير وسائط غير صحيحة أو إذا كانت هناك وسائط مطلوبة مفقودة.

التوطين

يمكن توطين جميع النصوص باستخدام وحدة I18n. وسيط localizeCommands يوجه المكتبة لطباعة النسخ الموطنة من الكلمات المفتاحية وأسماء الخيارات عند إنشاء رسائل التعليمات في الدوال مثل printHelp وprintCmdHelp.