控制错误消息的显示方式等

clap还提供了一些更加严格的参数校验功能。

useclap::{Parser,Subcommand};#[derive(Parser)]#[command(version, author, about, long_about = None)]structCli{#[command(subcommand)]test:Option<Test>,}#[derive(Subcommand)]enumTest{/// Add a numberAdd{#[arg(short, long)]num:u16,},/// Sub a numberSub{#[arg(short, long)]num:u16,}}fnmain(){letcli =Cli::parse();ifletSome(test)=cli.test {matchtest {Test::Add{num}=>println!("test add num: {:?}",num),Test::Sub{num}=>println!("test sub num: {:?}",num),}}}

输出：

➜  learn-clap git:(master)✗ ./target/release/examples/subcommand --helpthis is the about from Cargo.tomlUsage: subcommand [COMMAND]Commands:  addAdd a number  sub   Sub a number  helpPrint this message or the helpof the given subcommand(s)Options:  -h, --helpPrint help-V, --versionPrint version➜  learn-clap git:(master)✗ ./target/release/examples/subcommand add--helpAdd a numberUsage: subcommand add--num<NUM>Options:  -n, --num<NUM>-h, --helpPrint help➜  learn-clap git:(master)✗ ./target/release/examples/subcommand add-n1testaddnum: 1➜  learn-clap git:(master)✗ ./target/release/examples/subcommand sub -n2testsub num: 2

3. 参数校验

3.1 类型校验

可以发现，使用 Derive 模式的时候，我们在参数后面指定参数类型的时候，clap就会对我们输入参数进行类型检查，不匹配的时候会输出丰富的报错信息和指导建议。

我们自定义的校验规则为：

fnparse_port(s:&str)->Result<u16,String>{}

它需要满足：

• 入参是 &str
• 出参是 Result<参数类型, String>

可以测试输出：

➜  learn-clap git:(master)✗ ./target/release/examples/custom --helpthis is the about from Cargo.tomlUsage: custom --port<PORT>Options:  -p, --port<PORT>-h, --helpPrint help-V, --versionPrint version  ➜  learn-clap git:(master)✗ ./target/release/examples/custom -pxxxerror: invalid value 'xxx'for'--port <PORT>':`xxx`isn't a port number`For more information, try '--help'.➜  learn-clap git:(master) ✗ ./target/release/examples/custom -p 0  error: invalid value '0' for '--port <PORT>': port not in range 1-65535For more information, try '--help'.➜  learn-clap git:(master)✗ ./target/release/examples/custom -p9527port: 9527

3.5 关联参数

有时候参数直接还有关联关系，比如说：

• 依赖：必须存在 -a参数，-b参数才有意义，即要使用 -b参数时，必须指定 -a参数。

  在 RustRover 中，你可以在 Builder 模式，通过在 clap::value_parser!()中指定其他的类型，然后输入 .获得其他类型的内置校验规则。控制错误消息的显示方式等。

  

  在 clap中可以使用 #[command(subcommand)]搭配 #[derive(Subcommand)]实现子命令功能。

特此声明，本文包含 AI 辅助生成内容，如有错误遗漏之处，敬请指出。比如上面对 port 的校验，也可以自己实现。

结合起来，value_parser = clap::value_parser!(u16).range(1..)创建了一个规则，要求命令行参数必须是一个大于或等于 1 的 u16类型的数值。

clap之所以在 Rust 社区如此流行，得益于以下几个优点：

1. 易于使用

clap的设计理念是让命令行参数的解析变得简单而直观。

.arg(arg!([NAME]).help("Specify your name")).arg(arg!(-a --age <AGE>).value_parser(value_parser!(u16)))

2.2 可选参数

根据约定，<>表示必须，而 []表示可选：

.arg(arg!(<NAME>)// 必须.arg(arg!([ADDRESS]))// 可选

你也可以使用 .required(bool)函数明确指出是否必须：

.arg(arg!(<NAME>).required(true))

.required()的优先级高于 <>和 []，但是建议你在构建的时候还是遵循约定。

我们复用上面介绍「多选一参数」的代码：

useclap::{Parser,ValueEnum};#[derive(Parser)]#[command(version, author, about, long_about = None)]structCli{/// Choose the program mode run in#[arg(value_enum)]mode:Mode,}#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum)]enumMode{/// run in fast modeFast,/// run in slow modeSlow,}fnmain(){letcli =Cli::parse();matchcli.mode {Mode::Fast=>println!("fast!!!!!"),Mode::Slow=>println!("slow......"),}}

使用错误的值进行尝试：

➜  learn-clap git:(master)✗ ./target/release/examples/enum xxxx               error: invalid value 'xxxx'for'<MODE>'[possible values: fast, slow]For moreinformation, try '--help'.

3.3 范围校验

如果你想要实现数字类型范围限制的话，比如端口号参数的范围应该是 [1, 65535]，那可以使用 value_parser! = clap::value_parser!(u16).range(1..)来实现这个功能：

useclap::Parser;#[derive(Parser)]#[command(version, author, about, long_about = None)]structCli{#[arg(short, long, value_parser = clap::value_parser!(u16).range(1..))]port:u16,}fnmain(){letcli =Cli::parse();println!("port: {:?}",cli.port);}

输出：

➜  learn-clap git:(master)✗ ./target/release/examples/range --helpthis is the about from Cargo.tomlUsage: range --port<PORT>Options:  -p, --port<PORT>-h, --helpPrint help-V, --versionPrint version  ➜  learn-clap git:(master)✗ ./target/release/examples/range -p0error: invalid value '0'for'--port <PORT>':0is not in1..=65535For moreinformation, try '--help'.➜  learn-clap git:(master)✗ ./target/release/examples/range -p11111111error: invalid value '11111111'for'--port <PORT>':11111111is not in1..=65535For moreinformation, try '--help'.➜  learn-clap git:(master)✗ ./target/release/examples/range -p1111port: 1111

在这个例子中，value_parser = clap::value_parser!(u16).range(1..)的含义可以分为两部分解释：

1. clap::value_parser!(u16)

这部分使用 value_parser!宏为命令行参数指定了 u16类型的解析器。换句话说，任何小于 1 的值都将被认为是无效的，clap会因此报错并要求用户输入一个符合范围要求的值。

5. 活跃的社区支持

clap有一个非常活跃的社区，在 GitHub 上不断有新的贡献者加入。

useclap::{arg,command,value_parser,ValueEnum};fnmain(){letmatches =command!()// .arg(arg!(<MODE>).value_parser(["fast, slow"])).arg(arg!(<MODE>).value_parser(value_parser!(Mode)).required(true)).get_matches();matchmatches.get_one::<Mode>("MODE").expect("'Mode' is required and parsing will fail if its missing"){Mode::Fast=>println!("fast"),Mode::Slow=>println!("slow"),}}#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq, ValueEnum)]enumMode{/// Run in fast modeFast,/// Run in slow modeSlow,}

2.4 累计参数

使用 clap::ArgAction::Count设置参数为累计参数，然后使用 get_count(id)获取参数的值：

useclap::{arg,command};fnmain(){letmatches =command!().arg(arg!(-v --verbose...).action(clap::ArgAction::Count)).get_matches();println!("v count: {:?}",matches.get_count("verbose"));}

这里要注意，arg!()中参数的定义，也要符合累计参数的格式 -{short} --{long}...。

4. 性能优异

尽管 clap功能强大，但它仍然非常注重性能。HTTPS、isize

在 clap中可以通过 clap::ArgAction::Count来实现这种累积参数。

2. 参数类型

在 Builder 模式中，配置参数有两种方式：

• arg!([-short] [–long] id)
• Args::new(“id”).short(‘s’).long(“long”)

2.1 Arguments & Options

Arguments:  [NAME]Specify your nameOptions:  -a, --age<AGE>

• Argument:不包含 -{short}和 --{long}。

  输出：

  ➜  learn-clap git:(master)✗ ./target/release/examples/relation      a: Noneb: None➜  learn-clap git:(master)✗ ./target/release/examples/relation -b1error: the following required arguments were not provided:  --a<A>Usage: relation --a<A>--b<B>For moreinformation, try '--help'.➜  learn-clap git:(master)✗ ./target/release/examples/relation -a1a: Some("1")b: None➜  learn-clap git:(master)✗ ./target/release/examples/relation -a1-b2a: Some("1")b: Some("2")

  可以使用 #[group(required = true, mutiple = false)] 来实现互斥关系：

  useclap::{Args,Parser};#[derive(Parser)]#[command(version, author, about, long_about = None)]structCli{#[command(flatten)]args:Only,}#[derive(Args, Debug)]#[group(required = true, multiple = false)]structOnly{#[arg(long)]a:Option<String>,#[arg(long)]b:Option<String>,#[arg(long)]c:Option<String>,#[arg(long)]d:Option<String>,}fnmain(){letcli =Cli::parse();println!("only: {:?}",cli.args)}

  #[command(flattern)] 直接将结构体里面的参数平铺。usize、

  下面的示例目录结构如下：

  ├── Cargo.lock├── Cargo.toml├── build.rs└── src    ├── cli.rs    └── main.rs

  首先我们需要引入 clap和 clap_completecrate，其中 clap_complete只需在 build 环境下即可，所以我们的 Cargo.tmol如下：

  [package]name = "myapp"version = "0.1.0"edition = "2021"build = "build.rs"[dependencies]clap = { version = "4.5.1" }dirs = "5.0.1"[build-dependencies]clap = { version = "4.5.1"}clap_complete = "4.5.1"

  我们先在 src/cli.rs中实现一个简单的命令行程序 myapp：

  useclap::{Arg,ArgAction,Command};pubfnbuild_cli()->Command{Command::new("myapp").about("Tests completions").arg(Arg::new("file").help("some input file")).subcommand(Command::new("test").about("tests things").arg(Arg::new("case").long("case").action(ArgAction::Set).help("the case to test")))}

  我们主要是演示这个自动补全功能，为了省事，src/main.rs中就不实现具体逻辑了：

  modcli;fnmain(){let_m =cli::build_cli().get_matches();}

  接着，我们在项目根目录下实现 build.rs，它将为我们指定的命令生成自动补全脚本：

  touchbuild.rs

  useclap_complete::{generate_to,shells::Bash};usestd::env;usestd::io::Error;include!("src/cli.rs");fnmain()->Result<(),Error>{letoutdir =matchenv::var_os("OUT_DIR"){None=>returnOk(()),Some(outdir)=>outdir,};letmutcmd =build_cli();letpath =generate_to(Bash,&mutcmd,// We need to specify what generator to use"myapp",// We need to specify the bin name manuallyoutdir,// We need to specify where to write to)?;println!("cargo:warning=completion file is generated: {path:?}");Ok(())}

  你需要把其中的 myapp替换为你的命令。

  特别说明：后续的例子均在 examples目录下实现，故编译和执行命令都包含 example。具体的错误信息，帮助用户快速定位问题。若你有这方面的需求，可以使用 rpasswordcrate 辅助完成。

  error: invalid value 'xxxx'for'--num <NUM>':invalid digit found instringFor moreinformation, try '--help'.

  默认支持：

  • 原生类型：bool, String, OsString, PathBuf、

    这里等价于 Builder 模式下的：

    #[command(version, author, about)]

    3. 添加命令行参数：

    .arg(arg!([NAME]).help("Specify your name")).arg(Arg::new("age").short('a').long("age").value_parser(value_parser!(u8)))

    这部分代码添加了两个命令行参数：

    • .arg(arg!([NAME]).required(true).help("Specify your name"))使用 arg!宏添加了一个名为 NAME的必需参数，并提供了一些帮助信息。

      一款优秀的 CLI 工具应该具备以下的功能和特性，以提升用户体验和效率：

      一个优秀的命令行工具（CLI, Command Line Interface）应该具备以下功能和特性，以提升用户体验和效率：

      1. 直观易用：
         • 简洁的命令语法：命令和参数的设计应直观易懂，方便用户记忆和使用。

           arg!(<PORT>).value_parser(value_parser!(u16).range(1..))

           3.4 自定义校验

           value_parser()中也可以传自定义的校验函数，该函数的签名需要满足的条件跟我们在介绍 Derive 时一样。

           useclap::Parser;#[derive(Parser)]#[command(version, author, about, long_about = None)]structCli{#[arg(short, long, action = clap::ArgAction::Count)]verbose:u8,}fnmain(){letcli =Cli::parse();println!("verbose: {}",cli.verbose);}

           输出：

           ➜  learn-clap git:(master)✗ ./target/release/examples/accurate --helpthis is the about from Cargo.tomlUsage: accurate [OPTIONS]Options:  -v, --verbose...    -h, --helpPrint help-V, --versionPrint version➜  learn-clap git:(master)✗ ./target/release/examples/accurate -vverbose: 1➜  learn-clap git:(master)✗ ./target/release/examples/accurate -vvvvverbose: 4

           2.5 变长参数

           有时候我们希望接收变长参数，比如说：

           del file1 file2 file3

           这个时候可以使用 Vec<>来实现。

         • clap::ArgAction::SetFalse: 设置参数的话，则为 false，否则 true（默认）。

      这些特性不仅能够提高用户的工作效率，还能增强用户体验，使命令行工具更加强大和易用。

    • 对比 cobra：从设计理念和目标、
    • 复杂的命令结构：支持子命令的嵌套，允许构建复杂的命令行应用结构。DICT、这意味着 clap不断地得到改进和更新，同时也有大量的社区资源可供参考。curl是一个非常强大和灵活的工具，广泛应用于自动化脚本、

      useclap::{Parser,ValueEnum};#[derive(Parser)]#[command(version, author, about, long_about = None)]structCli{/// Choose the program mode run in#[arg(value_enum)]mode:Mode,}#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum)]enumMode{/// run in fast modeFast,/// run in slow modeSlow,}fnmain(){letcli =Cli::parse();matchcli.mode {Mode::Fast=>println!("fast!!!!!"),Mode::Slow=>println!("slow......"),}}

      输出：

      Usage: enum <MODE>Arguments:  <MODE>Choose the program mode run inPossible values:          - fast: run infast mode          - slow: run inslow modeOptions:  -h, --helpPrint help(see a summary with '-h')-V, --versionPrint version

      2.4 累计参数

      累积参数允许用户通过重复指定同一个标志（例如 -d）来累加值或效果，通常用于控制命令行应用的详细级别（verbosity level）或其他需要根据次数变化的行为。

    • 内置帮助命令：通过如--help或-h参数轻松访问帮助信息。

    测试：

    ➜  learn-clap-builder git:(master)✗ ./target/release/examples/flag      debug: falseverbose: true➜  learn-clap-builder git:(master)✗ ./target/release/examples/flag -ddebug: trueverbose: true➜  learn-clap-builder git:(master)✗ ./target/release/examples/flag -vdebug: falseverbose: false

    2.7 子命令

    可以使用 subcommand(sub_cmd)和 subcommand([sub_cmd1, sub_cmd2])来添加子命令，解析的时候使用 matches.subcommand()匹配子命令，再按照之前的规则解析子命令中对应的参数即可。From<&OsStr>、

  cobra:

  • 性能对于大多数命令行应用来说已经足够，但可能不如 clap优化。
  • Options:包含 -{short}或 --{long}。

    curl是一种命令行工具和库，用于传输数据。所以，-vvv（等价于 -v -v -v） 会比单个 -v提供更多的详细信息。这个参数使用了 value_parser宏来指明它的值应被解析为 u8类型的数字。

• 版本管理：
  • 版本控制：提供命令查看工具版本，支持多版本共存或升级。
• 高效的执行和输出：
  • 快速响应：命令执行应迅速，减少用户等待时间。

    useclap::{arg,Command,value_parser};fnmain(){letmatches =Command::new("myapp").subcommands([Command::new("add").arg(arg!(<NUM>).value_parser(value_parser!(i16))),Command::new("sub").arg(arg!(<NUM>).value_parser(value_parser!(i16))),]).get_matches();matchmatches.subcommand(){Some(("add",add_cmd))=>println!("'myapp add' was used, num is: {:?}",add_cmd.get_one::<i16>("NUM"),),Some(("sub",sub_cmd))=>println!("'myapp sub' was used, num is: {:?}",sub_cmd.get_one::<i16>("NUM"),),_ =>unreachable!()}}

    3. 参数校验

    3.1 类型校验

    使用 value_parser!()在括号中指定类型，clap就会自动帮我们对参数进行类型校验，当然你在获取参数值 get_one::<类型>()的时候，类型要对上，否则会 panic。

  • 支持自定义验证器和复杂的参数关系（如互斥、

    进入终端，我们可以用下面命令查看 curl的说明文档：

    ➜  ~ curl--helpUsage: curl[options...]<url>-d, --data<data>HTTP POST data -f, --failFail fast with no output on HTTP errors -h, --help<category>Get helpforcommands -i, --includeInclude protocol response headers inthe output -o, --output<file>Write to fileinstead of stdout -O, --remote-name          Write output to a filenamed as the remote file-s, --silentSilent mode -T, --upload-file <file>Transfer localFILE to destination -u, --user<user:password>Server user and password -A, --user-agent <name>Send User-Agent <name>to server -v, --verboseMake the operation moretalkative -V, --versionShow version number and quitThis is not the full help, this menu is stripped into categories.Use "--help category"to get an overview of all categories.For all options use the manual or "--help all".

    使用示例：

    • 下载文件：

      curl-Ohttp://example.com/file.txt

    • 发送 POST 请求：

      curl-d"param1=value1&param2=value2"http://example.com/resource

    • 使用 HTTPS 并忽略证书验证：

      curl-khttps://example.com

    • 使用基本认证：

      curl-uusername:password http://example.com

    curl的这些特性使其成为开发者、

  • 更少的运行时开销，尤其是在处理大量复杂命令行参数时。FromStr的类型

  3.2 枚举校验

  2.3 中枚举参数的说明中，已经体现了枚举校验的功能了，这里不赘述。POP3、

  使用 -- help测试输出如下：

  This the intro of the cli applicationUsage: app2 [OPTIONS][NAME]Arguments:  [NAME]Specify your nameOptions:  -a, --age<AGE>-h, --helpPrint help-V, --versionPrint version

  你可以将其与「Derive - 应用配置」进行比较，应该很容易找到它们之间的对应关系。

  下面我们将从**「应用配置」、

可以使用 requires 实现依赖关系：

useclap::Parser;#[derive(Parser)]#[command(version, author, about, long_about = None)]structCli{#[arg(short, long)]a:Option<String>,#[arg(short, long,requires = "a")]b:Option<String>,}fnmain(){letcli =Cli::parse();println!("a: {:?}",cli.a);println!("b: {:?}",cli.b);}

上述代码中，我们在参数 b中加入了 requires = "a"，表示要使用 b参数必须要有 a参数。

2. 配置应用：

.version("1.0.0").author("hedon").about("This the intro of the cli application")

接下来，使用链式调用方法配置应用的版本号为 "1.0.0"，作者为 "hedon"，并添加了一个简短的描述。

2. .range(1…)

这部分进一步限制了参数值的有效范围。顾名思义，Derive就是利用宏强大的功能来构建命令行，而 Builder则采用构建者模式链式构建命令行工具。