clap-patterns

# clap-patterns

Provides modern type-safe Rust CLI patterns using Clap 4.x with derive macros, Parser trait, Subcommand enums, custom validation, value parsers, and environment variable integration for building maintainable command-line applications.

## Core Patterns

### 1. Basic Parser with Derive Macros

Use derive macros for automatic CLI parsing with type safety:

```rust
use clap::Parser;

#[derive(Parser)]
#[command(name = "myapp")]
#[command(author, version, about, long_about = None)]
struct Cli {
    /// Input file path
    #[arg(short, long, value_name = "FILE")]
    input: std::path::PathBuf,

    /// Optional output file
    #[arg(short, long)]
    output: Option<std::path::PathBuf>,

    /// Verbose mode
    #[arg(short, long)]
    verbose: bool,

    /// Number of items to process
    #[arg(short, long, default_value_t = 10)]
    count: usize,
}

fn main() {
    let cli = Cli::parse();
    if cli.verbose {
        println!("Processing: {:?}", cli.input);
    }
}
```

### 2. Subcommand Enums

Organize complex CLIs with nested subcommands:

```rust
use clap::{Parser, Subcommand};

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

#[derive(Subcommand)]
enum Commands {
    /// Add files to staging
    Add {
        /// Files to add
        #[arg(value_name = "FILE")]
        files: Vec<String>,
    },
    /// Commit changes
    Commit {
        /// Commit message
        #[arg(short, long)]
        message: String,
    },
}
```

### 3. Value Parsers and Validation

Implement custom parsing and validation:

```rust
use clap::Parser;
use std::ops::RangeInclusive;

const PORT_RANGE: RangeInclusive<usize> = 1..=65535;

fn port_in_range(s: &str) -> Result<u16, String> {
    let port: usize = s
        .parse()
        .map_err(|_| format!("`{s}` isn't a valid port number"))?;
    if PORT_RANGE.contains(&port) {
        Ok(port as u16)
    } else {
        Err(format!("port not in range {}-{}", PORT_RA