نظام الأوامر في Kawkab

نظام الأوامر في إطار عمل Kawkab يوفر واجهة سطر أوامر قوية ومرنة لإدارة وتنفيذ المهام المختلفة في تطبيقك. يمكنك استخدام الأوامر المدمجة أو إنشاء أوامر مخصصة خاصة بك.

استعراض الأوامر المتاحة

للحصول على قائمة بجميع الأوامر المتاحة، قم بتنفيذ:

npm run kawkab

هذا الأمر سيعرض قائمة بجميع الأوامر المتاحة مع وصف مختصر لكل أمر.

إنشاء أمر جديد

الصيغة الأساسية

npm run kawkab command:make <name> [module]

تفاصيل المعلمات:

• <name>: اسم الأمر الذي ترغب في إنشائه.
• [module]: اسم الموديول الذي سيحتوي على الأمر (اختياري، الافتراضي هو main).

مثال:

npm run kawkab command:make hello

هذا الأمر سينشئ ملف أمر جديد في المسار المناسب مع الهيكل الأساسي التالي:

import { Command } from "kawkab";
 
export default function(program: Command): void {
  program
    // صيغة الأمر: '<variable_name>' إلزامي، '[variable_name]' اختياري
    .command("hello <name> [module]")
    // وصف الأمر الذي سيظهر في مساعدة CLI
    .description("وصف الأمر الخاص بك")
    // الإجراء الذي سيتم تنفيذه عند تشغيل الأمر
    .action(async (name: string, module: string = "main") => {
      // قم بكتابة منطق الأمر هنا
      console.log(`Hello ${name}`);
    });
}

هيكل الأمر

المكونات الأساسية

1. command(): تحديد اسم وصيغة الأمر

   • المتغيرات الإلزامية تُكتب بين <>
   • المتغيرات الاختيارية تُكتب بين []

2. description(): وصف مختصر للأمر يظهر في قائمة المساعدة

3. action(): دالة تحتوي على منطق تنفيذ الأمر

   • تستقبل المتغيرات المحددة في صيغة الأمر
   • يمكن أن تكون غير متزامنة (async)

إضافة خيارات

يمكنك إضافة خيارات لأمرك باستخدام option():

program
  .command("hello <name>")
  .option("-c, --capitalize", "تحويل الاسم إلى أحرف كبيرة")
  .action(async (name: string, options) => {
    const output = options.capitalize ? name.toUpperCase() : name;
    console.log(`Hello ${output}`);
  });

أفضل الممارسات

1. أسماء واضحة: استخدم أسماء وصفية وواضحة لأوامرك.
2. توثيق جيد: اكتب وصفاً واضحاً ومفصلاً لكل أمر وخياراته.
3. التحقق من المدخلات: تحقق دائماً من صحة المدخلات قبل تنفيذ الأمر.
4. رسائل واضحة: اعرض رسائل واضحة للمستخدم عن نتيجة تنفيذ الأمر.
5. معالجة الأخطاء: قم بتنفيذ معالجة مناسبة للأخطاء المحتملة.

الخاتمة

نظام الأوامر في Kawkab يوفر طريقة سهلة ومرنة لإضافة وظائف جديدة إلى تطبيقك عبر واجهة سطر الأوامر. مع دعم المتغيرات الإلزامية والاختيارية والخيارات المخصصة، يمكنك إنشاء أوامر قوية ومفيدة لتطبيقك.