Introduction to Clap in Rust

Clap is a powerful command-line argument parsing library in Rust that makes it easy to build robust command-line interfaces. With Clap, you can define complex command-line options, subcommands, and automated help and version generation.

Getting Started with Clap

First, add Clap to your dependencies in Cargo.toml:

[dependencies] clap = "3.0"

Then, you can start using it in your project:

use clap::{Arg, App};
fn main() {
    let matches = App::new("MyApp")
        .version("1.0")
        .author("Your Name ")
        .about("Describes what the application does")
        .arg(Arg::new("INPUT")
            .about("The input file to use")
            .required(true)
            .index(1))
        .arg(Arg::new("debug")
            .short('d')
            .long("debug")
            .about("Activate debug mode"))
        .get_matches();
    
    // You can get the value of the input file as follows:
    if let Some(input) = matches.value_of("INPUT") {
        println!("Using input file: {}", input);
    }
    if matches.is_present("debug") {
        println!("Debug mode is on");
    }
}

Advanced Uses of Clap

Clap supports many advanced features like subcommands, default values, and custom validators. Here are some more examples:

Subcommands

use clap::{App, SubCommand};
fn main() {
    let matches = App::new("MyApp")
        .subcommand(SubCommand::with_name("test")
            .about("does testing things")
            .version("1.3")
            .author("Someone Else ")
            .arg_from_usage("-d, --debug 'Print debug information'"))
        .get_matches();

    if let Some(matches) = matches.subcommand_matches("test") {
        if matches.is_present("debug") {
            println!("Debugging is enabled");
        }
    }
}

Default Values

use clap::{Arg, App};
fn main() {
    let matches = App::new("MyApp")
        .arg(Arg::new("config")
            .short('c')
            .long("config")
            .about("Sets a custom config file")
            .default_value("default.conf"))
        .get_matches();

    println!("Value for config: {}", matches.value_of("config").unwrap());
}

Custom Validators

use clap::{Arg, App};
fn main() {
    let matches = App::new("MyApp")
        .arg(Arg::new("number")
            .short('n')
            .about("A number between 1 and 10")
            .validator(|v| {
                v.parse::()
                    .map_err(|_| String::from("Must be a number"))
                    .and_then(|n| {
                        if n >= 1 && n <= 10 {
                            Ok(())
                        } else {
                            Err(String::from("Must be between 1 and 10"))
                        }
                    })
            })
            .required(true))
        .get_matches();

    println!("Value for number: {}", matches.value_of("number").unwrap());
}

Full Application Example

Here is a complete example that combines various features of Clap for a more comprehensive application:

use clap::{Arg, App, SubCommand};
fn main() {
    let matches = App::new("CliApp")
        .version("1.0")
        .author("Your Name ")
        .about("An example of using Clap with subcommands, arguments, and flags")
        .arg(Arg::new("config")
            .short('c')
            .long("config")
            .about("Sets a custom config file")
            .default_value("default.conf"))
        .subcommand(SubCommand::with_name("test")
            .about("does testing things")
            .version("1.3")
            .author("Someone Else ")
            .arg(Arg::new("debug").short('d').long("debug").about("Print debug information")))
        .subcommand(SubCommand::with_name("process")
            .about("process inputs")
            .arg(Arg::new("INPUT").required(true).index(1).about("Input file to process")))
        .get_matches();

    if let Some(c) = matches.value_of("config") {
        println!("Value for config: {}", c);
    }

    match matches.subcommand() {
        ("test", Some(test_matches)) => {
            if test_matches.is_present("debug") {
                println!("Running in debug mode");
            } else {
                println!("Running in normal mode");
            }
        }
        ("process", Some(process_matches)) => {
            if let Some(input) = process_matches.value_of("INPUT") {
                println!("Processing input file: {}", input);
            }
        }
        _ => println!("No valid subcommand provided"),
    }
}

With these examples, you should have a solid foundation for using Clap in your Rust applications. Happy coding!