Clap لـ Rust: دليل شامل مع أمثلة

ما هو Clap ولماذا هو مطلوب؟

\n\n

Clap (Command Line Argument Parser) هي مكتبة قوية وسريعة وسهلة الاستخدام لتحليل وسائط سطر الأوامر في لغة Rust. تتيح للمطورين تحديد الوسائط والأعلام والخيارات والأوامر الفرعية التي يجب أن يقبلها تطبيقهم بسهولة، وتوليد التعليمات تلقائيًا (--help)، والتحقق من أنواع البيانات، ومعالجة أخطاء الإدخال.

\n\n

لماذا نحتاج Clap؟ بدلاً من تحليل std::env::args() يدويًا وكتابة عشرات الأسطر من الكود للتحقق من الصحة، يقوم Clap بكل العمل نيابة عنك. أنت فقط تصف هيكل واجهة سطر الأوامر الخاصة بك، وتتولى المكتبة عملية التحليل وتوليد رسائل الخطأ وتنسيق التلميحات. يدعم Clap:

\n

\n
• الوسائط الموضعية (الإلزامية والاختيارية).
\n
• الخيارات المسماة (الأعلام) بأسماء قصيرة وطويلة.
\n
• الأوامر الفرعية (مثل git commit).
\n
• الإكمال التلقائي للأصداف (bash, zsh, fish, PowerShell).
\n
• التحقق من صحة القيم، القيم الافتراضية، القيم المتعددة، وغير ذلك الكثير.
\n

\n\n

Clap هو المعيار الفعلي لإنشاء تطبيقات واجهة سطر الأوامر في نظام Rust البيئي. يُستخدم في مشاريع معروفة مثل cargo و ripgrep (rg) و fd وغيرها الكثير.

\n\n

التثبيت

\n\n

Clap هي مكتبة لـ Rust، لذا يتم تثبيتها عبر مدير الحزم cargo. أضف السطر التالي إلى ملف Cargo.toml الخاص بك:

\n\n

[dependencies]\nclap = { version = "4.5", features = ["derive"] }

\n\n

نوصي باستخدام وسوم الاشتقاق (derive macros) (ميزة derive)، لأنها الطريقة الأكثر حداثة وسهولة للعمل مع Clap. إذا كنت تحتاج فقط إلى الوظائف الأساسية بدون derive، يمكنك كتابة:

\n\n

[dependencies]\nclap = "4.5"

\n\n

بعد إضافة التبعية، قم بتنفيذ الأمر cargo build لتحميل المكتبة وتجميعها.

\n\n

بداية سريعة مع مثال كود

\n\n

لنقم بإنشاء تطبيق بسيط يقبل اسم مستخدم وعلم تحية اختياري. أنشئ مشروعًا جديدًا:

\n\n

cargo new hello_clap\ncd hello_clap

\n\n

استبدل محتوى src/main.rs بالكود التالي:

\n\n

use clap::Parser;\n\n/// برنامج بسيط للتحية\n#[derive(Parser)]\n#[command(name = "greeter")]\n#[command(about = "يرحب بالمستخدم", long_about = None)]\nstruct Cli {\n    /// اسم المستخدم\n    name: String,\n\n    /// عدد مرات تكرار التحية\n    #[arg(short = 'c', long = "count", default_value_t = 1)]\n    count: u8,\n}\n\nfn main() {\n    let cli = Cli::parse();\n\n    for _ in 0..cli.count {\n        println!("مرحبًا، {}!", cli.name);\n    }\n}

\n\n

الآن قم بتشغيل البرنامج:

\n\n

cargo run -- عالم\n# الإخراج: مرحبًا، عالم!\n\ncargo run -- عالم -c 3\n# الإخراج:\n# مرحبًا، عالم!\n# مرحبًا، عالم!\n# مرحبًا، عالم!\n\ncargo run -- --help\n# إخراج التعليمات

\n\n

كما ترى، قام Clap تلقائيًا بتوليد التعليمات ومعالجة الوسائط والتحقق من أنواع البيانات (إذا قمت بتمرير قيمة غير رقمية لـ -c، سيظهر خطأ).

\n\n

الطرق والوظائف الأساسية لـ Clap

\n\n

دعنا نستعرض الطرق والسمات الرئيسية التي يوفرها Clap. سنستخدم نهج وسوم الاشتقاق (derive macros) لأنه الأكثر شيوعًا.

\n\n

1. #[derive(Parser)]

\n

ما يفعله: يحول هيكلك إلى محلل لسطر الأوامر. هذا هو الوسم الأساسي الذي يبدأ منه كل شيء. يقوم تلقائيًا بتطبيق trait Parser على هيكلك.

\n

المعلمات: سمات الهيكل (#[command(...)]) والحقول (#[arg(...)]).

\n

مثال:

\n

use clap::Parser;\n\n#[derive(Parser)]\n#[command(name = "myapp")]\nstruct C