Clap Rust: पूर्ण गाइड, उदाहरण और उपयोग विधि

Clap क्या है और इसकी आवश्यकता क्यों है?

Clap (Command Line Argument Parser) Rust भाषा में कमांड लाइन आर्गुमेंट्स को पार्स करने के लिए एक शक्तिशाली, तेज़ और उपयोगकर्ता-अनुकूल लाइब्रेरी है। यह डेवलपर्स को आसानी से यह परिभाषित करने देता है कि उनके एप्लिकेशन को कौन से आर्गुमेंट्स, फ्लैग्स, ऑप्शन्स और सबकमांड्स स्वीकार करने चाहिए। साथ ही, यह स्वचालित रूप से हेल्प (--help) जनरेट करता है, डेटा टाइप्स की जाँच करता है और इनपुट एरर को हैंडल करता है।

Clap की आवश्यकता क्यों है? std::env::args() को मैन्युअली पार्स करने और वैलिडेशन के लिए दर्जनों लाइनें लिखने के बजाय, Clap आपके लिए सारा काम करता है। आप बस अपने CLI की संरचना बताते हैं, और लाइब्रेरी पार्सिंग, एरर मैसेज जनरेशन और हिंट्स फॉर्मेटिंग का ध्यान रखती है। Clap सपोर्ट करता है:

• पोज़ीशनल आर्गुमेंट्स (अनिवार्य और वैकल्पिक)।
• नामित ऑप्शन्स (फ्लैग्स) छोटे और लंबे नामों के साथ।
• सबकमांड्स (जैसे git commit में)।
• शेल के लिए ऑटो-कम्प्लीशन (bash, zsh, fish, PowerShell)।
• वैल्यू वैलिडेशन, डिफ़ॉल्ट वैल्यू, मल्टीपल वैल्यू और बहुत कुछ।

Clap Rust इकोसिस्टम में CLI एप्लिकेशन बनाने का डी-फैक्टो स्टैंडर्ड है। इसका उपयोग cargo, ripgrep (rg), fd जैसे प्रसिद्ध प्रोजेक्ट्स में किया जाता है।

इंस्टॉलेशन

Clap एक Rust लाइब्रेरी है, इसलिए इसे cargo पैकेज मैनेजर के माध्यम से इंस्टॉल किया जाता है। अपने Cargo.toml फ़ाइल में निम्नलिखित लाइन जोड़ें:

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

हम derive-मैक्रोज़ (फीचर derive) का उपयोग करने की सलाह देते हैं, क्योंकि यह Clap के साथ काम करने का सबसे आधुनिक और सुविधाजनक तरीका है। यदि आपको केवल बेसिक फंक्शनैलिटी चाहिए, तो आप लिख सकते हैं:

[dependencies]
clap = "4.5"

डिपेंडेंसी जोड़ने के बाद, लाइब्रेरी को डाउनलोड और कंपाइल करने के लिए cargo build कमांड चलाएँ।

कोड उदाहरण के साथ त्वरित शुरुआत

चलिए एक सरल एप्लिकेशन बनाते हैं जो उपयोगकर्ता का नाम और एक वैकल्पिक ग्रीटिंग फ्लैग लेता है। एक नया प्रोजेक्ट बनाएँ:

cargo new hello_clap
cd hello_clap

src/main.rs की सामग्री को निम्नलिखित कोड से बदलें:

use clap::Parser;

/// एक सरल अभिवादन प्रोग्राम
#[derive(Parser)]
#[command(name = "greeter")]
#[command(about = "उपयोगकर्ता का अभिवादन करता है", long_about = None)]
struct Cli {
    /// उपयोगकर्ता का नाम
    name: String,

    /// अभिवादन दोहराने की संख्या
    #[arg(short = 'c', long = "count", default_value_t = 1)]
    count: u8,
}

fn main() {
    let cli = Cli::parse();

    for _ in 0..cli.count {
        println!("नमस्ते, {}!", cli.name);
    }
}

अब प्रोग्राम चलाएँ:

cargo run -- दुनिया
# आउटपुट: नमस्ते, दुनिया!

cargo run -- दुनिया -c 3
# आउटपुट:
# नमस्ते, दुनिया!
# नमस्ते, दुनिया!
# नमस्ते, दुनिया!

cargo run -- --help
# हेल्प आउटपुट

जैसा कि आप देख सकते हैं, Clap ने स्वचालित रूप से हेल्प जनरेट की, आर्गुमेंट्स को प्रोसेस किया और टाइप चेकिंग की (यदि -c में नंबर नहीं देंगे तो एरर आएगी)।

Clap के मुख्य तरीके और फंक्शन

आइए Clap द्वारा प्रदान किए जाने वाले प्रमुख तरीकों और एट्रीब्यूट्स को समझते हैं। हम derive-मैक्रोज़ का उपयोग करेंगे, क्योंकि यह सबसे लोकप्रिय तरीका है।

1. #[derive(Parser)]

क्या करता है: आपकी स्ट्रक्चर को कमांड लाइन पार्सर में बदल देता है। यह मुख्य मैक्रो है जहाँ से सब कुछ शुरू होता है। यह आपकी स्ट्रक्चर के लिए स्वचालित रूप से Parser ट्रेट को इम्प्लीमेंट करता है।

पैरामीटर: स्ट्रक्चर एट्रीब्यूट्स (#[command(...)]) और फील्ड एट्रीब्यूट्स (#[arg(...)])।

उदाहरण:

use clap::Parser;

#[derive(Parser)]
#[command(name = "myapp")]
struct Cli {
    #[arg(short, long)]
    verbose: bool,
}

2. Cli::parse()

क्या करता है: यह मुख्य मेथड है जो कमांड लाइन से आर्गुमेंट्स को पार्स करता है। यह std::env::args() से आर्गुमेंट्स लेता है और आपकी स्ट्रक्चर का एक इंस्टेंस लौटाता है। यदि पार्सिंग विफल होती है (जैसे गलत टाइप या गायब आर्गुमेंट), तो यह एक एरर मैसेज प्रिंट करके प्रोग्राम को बाहर निकाल देता है।

सिंटैक्स:

let cli = Cli::parse();

उदाहरण:

fn main() {
    let cli = Cli::parse();
    println!("वर्बोज़ मोड: {}", cli.verbose);
}

3. #[arg(short, long)]

क्या करता है: किसी फील्ड को कमांड लाइन ऑप्शन (फ्लैग) के रूप में परिभाषित करता है। short एक छोटा नाम (जैसे -v) बनाता है, और long एक लंबा नाम (जैसे --verbose) बनाता है। आप कस्टम नाम भी दे सकते हैं, जैसे short = 'c' या long = "count"।

सिंटैक्स:

#[arg(short, long)]
#[arg(short = 'c', long = "count")]

उदाहरण:

struct Cli {
    #[arg(short, long)]
    verbose: bool,

    #[arg(short = 'o', long = "output")]
    output_file: Option,
}

4. default_value_t

क्या करता है: किसी ऑप्शन के लिए डिफ़ॉल्ट मान सेट करता है जब उपयोगकर्ता इसे प्रदान नहीं करता। यह टाइप-सेफ है और कंपाइल टाइम पर वैल्यू की जाँच करता है।

सिंटैक्स:

#[arg(default_value_t = 1)]
#[arg(default_value_t = String::from("default.txt"))]

उदाहरण:

struct Cli {
    #[arg(short, long, default_value_t = 3)]
    count: u8,
}

5. #[command(name = "...")]

क्या करता है: आपके CLI एप्लिकेशन का नाम सेट करता है। यह नाम हेल्प मैसेज और एरर रिपोर्टिंग में उपयोग होता है।

सिंटैक्स:

#[command(name = "myapp")]
#[command(about = "एप्लिकेशन का विवरण", long_about = None)]

उदाहरण:

#[derive(Parser)]
#[command(name = "file-utils")]
#[command(about = "फ़ाइल उपयोगिताएँ")]
struct Cli {
    // फील्ड्स
}

6. subcommand

क्या करता है: सबकमांड्स को परिभाषित करता है (जैसे git commit, git push)। आप एक एनम बनाते हैं जहाँ प्रत्येक वेरिएंट एक सबकमांड है, और प्रत्येक वेरिएंट की अपनी स्ट्रक्चर होती है।

सिंटैक्स:

#[derive(Parser)]
enum Commands {
    Add { name: String },
    Remove { id: u32 },
}

उदाहरण:

use clap::{Parser, Subcommand};

#[derive(Parser)]
struct Cli {
    #[command(subcommand)]
    command: Commands,
}

#[derive(Subcommand)]
enum Commands {
    /// एक नया आइटम जोड़ें
    Add {
        name: String,
    },
    /// एक आइटम हटाएँ
    Remove {
        #[arg(short, long)]
        id: u32,
    },
}

fn main() {
    let cli = Cli::parse();
    match &cli.command {
        Commands::Add { name } => println!("जोड़ा गया: {}", name),
        Commands::Remove { id } => println!("हटाया गया: {}", id),
    }
}

7. value_parser

क्या करता है: आर्गुमेंट वैल्यू के लिए कस्टम वैलिडेशन और पार्सिंग लागू करता है। आप रेंज, रेगेक्स पैटर्न, या कस्टम फंक्शन का उपयोग कर सकते हैं।

सिंटैक्स:

#[arg(value_parser = clap::value_parser!(u8).range(1..10))]
#[arg(value_parser = |s: &str| -> Result<MyType, String> { ... })]

उदाहरण:

struct Cli {
    #[arg(short, long, value_parser = clap::value_parser!(u8).range(1..=100))]
    level: u8,
}

8. num_args

क्या करता है: निर्धारित करता है कि एक ऑप्शन कितनी वैल्यू ले सकता है। उदाहरण के लिए, num_args = 1.. का मतलब है कम से कम एक वैल्यू, और num_args = 3 का मतल� ठीक तीन वैल्यू।

सिंटैक्स:

#[arg(short, long, num_args = 1..)]
#[arg(short, long, num_args = 3)]

उदाहरण:

struct Cli {
    #[arg(short, long, num_args = 2)]
    coordinates: Vec<f64>,
}

निष्कर्ष

Clap Rust में CLI एप्लिकेशन बनाने के लिए एक अनिवार्य लाइब्रेरी है। इसकी derive-आधारित सिंटैक्स, शक्तिशाली वैलिडेशन, और स्वचालित हेल्प जनरेशन इसे शुरुआती और अनुभवी डेवलपर्स दोनों के लिए आदर्श बनाती है। चाहे आप एक सरल टूल बना रहे हों या एक जटिल CLI, Clap आपका समय और प्रयास बचाता है।