Crate Clap
Source: https://docs.rs/clap/latest/clap/
Setup Steps 🔗
An example of project where this was used is zola_chrono but I want to stop including the logging level as part of it and defer to using environment variables as already supported by env_logger.
- Add dependency
cargo add clap -F derive,cargo,wrap_help - Copy cli.rs and add and remove as needed
- Copy from main.rs as needed
- Testing
#[cfg(test)] mod tests { #[test] fn verify_cli() { // Source: https://docs.rs/clap/latest/clap/_derive/_tutorial/index.html#testing // My understanding it reports most development errors without additional effort use clap::CommandFactory; super::Cli::command().debug_assert() } }
Example of cargo subcommand 🔗
https://github.com/rust-practice/cargo-leet/
Example of using clap derive 🔗
Full details can be found in the clap docs. This is just an short example showing features I use more frequently.
#!/usr/bin/env -S cargo +nightly -Zscript
---cargo
package.edition = "2021" # Desirable to stop warning but not needed
[dependencies]
version-control-clean-check = { version = "0.1.4", features = ["clap"] }
anyhow = "1.0.94"
clap = { version = "4.5.23", features = ["derive", "wrap_help"] }
---
use clap::{Parser, ValueEnum};
use std::path::PathBuf;
use version_control_clean_check::{check_version_control, CheckOptions};
/// Short about text goes here
///
/// This part is only included in the long about text that shows when using --help
#[derive(Parser, Clone, Eq, PartialEq, Ord, PartialOrd, Debug, Default)]
#[command(author, version, about)]
struct Cli {
/// Specify the root directory or uses current directory if not provided
#[arg(value_name = "FOLDER", default_value = ".")]
root: PathBuf,
#[clap(flatten)]
check_version_control: CheckOptions,
/// A boolean flag that is set to true if the argument is provided
///
/// This line only shows in the long help mode and
/// if you do not include `long` or `short` (both used below) on the argument
/// then it becomes positional
#[arg(long, short)]
optional_flag: bool,
/// Included to give an example for an enum
#[arg(value_enum, long, default_value_t)]
mode: Animal,
}
#[derive(ValueEnum, Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Default)]
enum Animal {
Bird,
#[default]
Cat,
Dog,
}
fn main() -> anyhow::Result<()> {
let cli = Cli::parse();
dbg!(&cli);
let path = cli.root.canonicalize()?;
dbg!(&path);
check_version_control(path, &cli.check_version_control)?;
println!("Program Ended");
Ok(())
}
Example output:
% ./single_file_script.rs -h
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.04s
Running `/home/one/.cargo/target/b1/bdd0db958a601c/debug/single_file_script -h`
Short about text goes here
Usage: single_file_script [OPTIONS] [FOLDER]
Arguments:
[FOLDER] Specify the root directory or uses current directory if not provided [default: .]
Options:
--allow-dirty Does not return an error for dirty files nor generate the list of said files
--allow-no-vcs This option basically disables checking. If true no checks are done. (Not even if the `path`
exists)
--allow-staged Does not return an error for staged files nor generate the list of said files
-o, --optional-flag A boolean flag that is set to true if the argument is provided
--mode <MODE> Included to give an example for an enum [default: cat] [possible values: bird, cat, dog]
-h, --help Print help (see more with '--help')
-V, --version Print version