Introduction to Clap

Clap is a powerful command-line argument parser for Rust, allowing developers to easily define, parse, and validate command-line parameters. It provides a rich set of features and is highly configurable. Let’s dive into some of its most useful APIs with code snippets.

Getting Started

To get started with Clap, add it to your Cargo.toml:

  [dependencies]
  clap = "3.0"

Basic Example

Here’s a basic example to parse and print command-line arguments:

  use clap::{Arg, Command};

  fn main() {
    let matches = Command::new("myapp")
      .version("1.0")
      .author("Author Name ")
      .about("Does awesome things")
      .arg(Arg::new("input")
        .about("Sets the input file to use")
        .required(true)
        .index(1))
      .arg(Arg::new("debug")
        .short('d')
        .long("debug")
        .about("Turn debugging information on"))
      .get_matches();

    let input = matches.value_of("input").unwrap();
    let debug = matches.is_present("debug");

    println!("Input file: {}", input);
    println!("Debug mode: {}", debug);
  }

Advanced Features

Subcommands

Clap supports subcommands, which are useful for complex applications:

  use clap::{Arg, Command};

  fn main() {
    let matches = Command::new("myapp")
      .subcommand(Command::new("test")
        .about("does testing things")
        .arg(Arg::new("verbose")
          .short('v')
          .about("Provides verbose output")))
      .get_matches();

    match matches.subcommand() {
      Some(("test", sub_matches)) => {
        if sub_matches.is_present("verbose") {
          println!("Running test in verbose mode");
        } else {
          println!("Running test");
        }
      }
      _ => println!("No subcommand was used"),
    }
  }

Custom Validations

You can add custom validations to your arguments:

  use clap::{Arg, Command};

  fn main() {
    let matches = Command::new("myapp")
      .arg(Arg::new("port")
        .about("Sets the port number")
        .required(true)
        .validator(|s| {
          s.parse::()
            .map(|_| ())
            .map_err(|_| String::from("Port must be a number"))
        }))
      .get_matches();

    let port: u16 = matches.value_of_t("port").unwrap();
    println!("Port: {}", port);
  }

Environment Variable Support

You can configure Clap to read from environment variables:

  use clap::{Arg, Command};

  fn main() {
    let matches = Command::new("myapp")
      .arg(Arg::new("config")
        .about("Sets a custom config file")
        .env("MYAPP_CONFIG")
        .long("config")
        .takes_value(true))
      .get_matches();

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

Application Example

Combining all the discussed APIs, here is an example of a more complete application:

  use clap::{Arg, Command};

  fn main() {
    let matches = Command::new("myapp")
      .version("1.0")
      .about("An advanced CLI app")
      .author("Author Name ")
      .arg(Arg::new("input")
        .about("Sets the input file to use")
        .required(true)
        .index(1))
      .arg(Arg::new("debug")
        .short('d')
        .long("debug")
        .about("Turn debugging information on"))
      .arg(Arg::new("port")
        .about("Sets the port number")
        .required(true)
        .validator(|s| {
          s.parse::()
            .map(|_| ())
            .map_err(|_| String::from("Port must be a number"))
        }))
      .subcommand(Command::new("test")
        .about("does testing things")
        .arg(Arg::new("verbose")
          .short('v')
          .about("Provides verbose output")))
      .get_matches();

    let input = matches.value_of("input").unwrap();
    let debug = matches.is_present("debug");
    let port: u16 = matches.value_of_t("port").unwrap();

    println!("Input file: {}", input);
    println!("Debug mode: {}", debug);
    println!("Port: {}", port);

    match matches.subcommand() {
      Some(("test", sub_matches)) => {
        if sub_matches.is_present("verbose") {
          println!("Running test in verbose mode");
        } else {
          println!("Running test");
        }
      }
      _ => println!("No subcommand was used"),
    }
  }

With these Clap features, you can build powerful CLI applications in Rust that are both user-friendly and highly configurable.

Hash: 8cceaf5c89e63591aea2e0a16fd98363477c370764ffa98fa7f00a60928576e1