常见问题解答

有关完整的问题解答和更深入的细节，请参阅 维基页面

比较

首先，我想说的是，这些比较非常主观，并不旨在批评或严厉。所有的参数解析库（包括 clap）都有其自身的优势和劣势。有时，当所有其他因素都相等时，这仅仅取决于个人喜好。当您不确定时，尝试它们所有，并选择一个您喜欢的！Rust 社区有足够的空间容纳多个实现！

clap 与 structopt 有何比较？

很简单！clap 就是 structopt。在 3.0 版本中，clap 将 structopt 代码导入自己的代码库作为 clap_derive 包。由于 structopt 已经在底层使用了 clap，所以过渡几乎是无缝的，并且与 100% 的功能兼容。

如果您之前使用过 structopt，您需要做的只是将属性从 #[structopt(...)] 改为 #[clap(...)]。

此外，派生语句也改为从 #[derive(Structopt)] 到 #[derive(Clap)]。此外，还在 clap_derive 包中添加了一些额外的功能。有关该包的详细信息，请参阅该包的文档。

如何比较 clap 和 getopts?

getopts 是一个非常基础的、相当简约的参数解析库。这并不是坏事，有时候你不需要很多功能，只是想解析一些简单的参数，并且根据你指定的有效参数生成一些帮助文本。这种方法的缺点是你必须手动实现大多数常见功能（例如检查以显示帮助消息、用法字符串等）。如果你需要一个高度定制的参数解析器，并且不介意自己编写大部分功能，getopts 是一个很好的基础。

getopts 也不分配很多，或者不分配。这给它带来了非常小的性能提升。尽管如此，当你开始实现额外的功能时，这个提升很快就消失了。

我个人发现，许多 getopts 的用途都是手动实现 clap 默认提供的功能。使用 clap 可以简化你的代码库，让你能够专注于应用程序，而不是参数解析。

如何比较 clap 和 docopt.rs?

首先，我想说我非常崇拜 BurntSushi 的作品，他是 Docopt.rs 的创造者。我希望能够创造出这个男人所创造的库的质量！当比较这两个库时，它们非常不同。docopt 要求你编写一个帮助消息，然后它会解析这个消息以确定所有有效参数及其用法。有些人非常喜欢这种方法，而有些人则不喜欢。如果你愿意编写详细的帮助消息，那么将这个消息放入你的程序中，让 docopt 做其余的事情就很好了。缺点是它远不够灵活。

docopt 还擅长自动将参数转换为 Rust 类型。甚至有一个语法扩展，如果你愿意使用 nightly 编译器，它会为你完成所有这些工作（使用稳定编译器需要你手动将参数转换为 Rust 类型）。用 BurntSushi 的话说，docopt 也是一种黑盒。你得到什么，你就得到什么，很难调整实现或为你的用例定制体验。

由于 docopt 需要做大量工作来解析你的帮助消息并确定你试图传达的有效参数，因此它也是性能较重的解析器之一。对于大多数应用程序来说，这并不是问题，这并不是说 docopt 慢，实际上它非常快。这只是在比较时要注意的事情。

在其他条件相同的情况下，使用 clap 有哪些原因？（卖点）

clap 尽可能地快、尽可能轻量，同时仍然提供你期望的现代参数解析器所具有的所有功能。事实上，对于 clap 提供的功能数量和类型，它仍然和 getopts 一样快。如果你只需要解析一些简单的参数，你会发现使用 clap 简单得就像散步一样。 clap 还使得表示极其复杂和高级的要求变得容易，而不需要太多思考。 clap 致力于直观、易于使用，能够满足各种用例和需求。

在其他条件相同的情况下，不使用 clap 有哪些原因？（反卖点）

根据您选择的定义有效参数的风格，clap 可以非常冗长。 clap 还提供了许多微调旋钮和开关，学习所有内容可能会显得令人不知所措。我努力保持简单情况简单，但当我们调整所有这些自定义旋钮时，它可能会变得复杂。clap 在解析方面也有自己的观点。尽管可以用 clap 调整和微调很多东西（而且我还在不断添加），但 clap 仍以特定的方式实现某些功能，这可能不符合某些用户的用例。最后，clap 在引用参数时是“字符串类型的”，这可能导致代码中的拼写错误。这个特定的纸张剪裁正在积极开发中，并应在 v3.x 中消失。

功能

以下是一些 clap 支持的功能，完整的描述和用法可以在 文档 和 examples/ 目录中找到

• 通过定义一个结构体简单地生成 CLI！
• 自动生成帮助、版本和用法信息
  • 如果您想自定义帮助、版本或用法说明，可以完全或部分覆盖
• 自动生成完成脚本（Bash、Zsh、Fish、Elvish 和 PowerShell）
  • 使用 clap_generate
  • 甚至可以通过许多多级子命令工作
  • 与仅接受特定值的选项一起工作
  • 与子命令别名一起工作
• 标志/开关（即布尔字段）
  • 支持短和长版本（即 -f 和 --flag 分别）
  • 支持结合短版本（即 -fBgoZ 与 -f -B -g -o -Z 相同）
  • 支持多次出现（即 -vvv 或 -v -v -v）
• 位置参数（即基于程序名称的索引）
  • 支持多个值（例如，myprog <file>...，如 myprog file1.txt file2.txt 是同一 "file" 参数的两个值）
  • 支持特定的值集合（见下文）
  • 可以设置值参数（例如，最小值数、最大值数或确切值数）
  • 可以为值设置自定义验证，以扩展参数解析能力到真正自定义的领域
• 选项参数（即那些带有值的参数）
  • 支持短和长版本（即 -o value、-ovalue、-o=value 和 --option value 或 --option=value 分别）
  • 支持多个值（例如，-o <val1> -o <val2> 或 -o <val1> <val2>）
  • 支持分隔符值（例如 -o=val1,val2,val3，也可以更改分隔符）
  • 支持特定的值集合（见下文）
  • 支持命名值，使得使用/帮助信息显示为 -o <FILE> <INTERFACE> 等，当您需要特定的多个值时
  • 可以设置值参数（例如，最小值数、最大值数或确切值数）
  • 可以为值设置自定义验证，以扩展参数解析能力到真正自定义的领域
• 子命令（例如 git add <file> 其中 add 是 git 的子命令）
  • 支持自己的子参数，并且与父命令独立
  • 有自己自动生成的帮助、版本和使用说明，与父命令独立
• 支持从 YAML 构建 CLIs - 这使您的 Rust 源代码保持整洁，并且使得支持本地化翻译变得非常简单！
• 需求规则：参数可以定义以下类型的规则
  • 默认要求
  • 只有当某些参数存在时才要求
  • 要求其他参数存在
  • 只有当其他参数的某些值被使用时才要求
• 冲突规则：参数可以可选地定义以下类型的排除规则
  • 当某些参数存在时不允许
  • 当存在时，不允许使用其他参数
• 分组：参数可以是分组的一部分
  • 完全兼容其他关系规则（需求、冲突和覆盖），允许像要求使用组中的任何参数，或条件性地拒绝使用整个组等操作
• 特定值集：位置或可选参数可以定义一组允许的值（例如，想象一个可能 只有 有两个值 fast 或 slow 的 --mode 选项，如 --mode fast 或 --mode slow）
• 默认值
  • 也支持条件默认值（即，只有当使用特定参数或这些参数的特定值时才应用的默认值）
• 从 Cargo.toml 自动获取版本：clap 完全兼容 Rust 的 env!() 宏，用于自动将您应用程序的版本设置为 Cargo.toml 中的版本。有关如何执行此操作的示例，请参阅 09_auto_version 示例（感谢 jhelwig 指出此功能）
• 类型值：您可以使用 clap 提供的几个便利宏从位置或可选参数获取类型值（例如 i32、u8 等），只要您请求的类型实现了 std::str::FromStr。请参阅 12_typed_values 示例。您还可以使用 clap 的 arg_enum! 宏创建一个枚举，其变体自动实现 std::str::FromStr。有关详细信息，请参阅 13a_enum_values_automatic 示例
• 建议：当用户输入错误时，建议纠正。例如，如果您定义了一个 --myoption 参数，而用户错误地输入了 --moyption（注意 y 和 o 位置颠倒），他们会收到一个 Did you mean '--myoption'? 错误并优雅地退出。这也适用于子命令和标志。（感谢 Byron 的实现）（此功能可以选择禁用，请参阅 '可选依赖/功能'）
• 彩色错误（仅限非 Windows 操作系统）：错误信息以彩色文本打印（此功能可以选择禁用，请参阅 '可选依赖/功能'）。
• 全局参数：参数可以一次性定义，并可用于所有子命令。这些值也将向上/向下传播到所有子命令。
• 自定义验证：您可以定义一个函数作为参数值的验证器。想象一下定义一个函数来验证 IP 地址，或者在出错时失败解析。这意味着您的应用程序逻辑可以完全专注于 使用 值。
• POSIX 兼容冲突/覆盖 - 在 POSIX 中，参数可以冲突，但不会导致解析失败，因为哪个参数最后出现，“胜出”，也就是说。这允许像别名（例如，alias ls='ls -l'，但然后在终端中使用 ls -C，结果传递 ls -l -C 作为最终参数。由于 -l 和 -C 不兼容，这在 clap 中实际上运行了 ls -C。如果选择...clap 还支持导致解析失败的硬冲突）。（感谢 Vinatorul！）
• 支持 Unix -- 语法，意味着仅跟随着位置参数

快速示例

以下示例展示了 clap 的一些非常基本功能。有关更高级的使用，例如需求、冲突、组、多个值和出现次数，请参阅 文档、此存储库的 examples/ 目录或 视频教程。

注意：所有这些示例在功能上都是相同的，但展示了使用 clap 的不同样式。这些不同的样式完全是个人偏好的问题。

第一个示例展示了使用结构体的最简单方法，这是 clap 的最简单用法。如果您熟悉 structopt 包，那么您很幸运，它是一样的！（实际上，在幕后运行的确实是相同的代码！）

// (Full example with detailed comments in examples/01d_quick_example.rs)
//
// This example demonstrates clap's full 'custom derive' style of creating arguments which is the
// simplest method of use, but sacrifices some flexibility.
use clap::Clap;

/// This doc string acts as a help message when the user runs '--help'
/// as do all doc strings on fields
#[derive(Clap)]
#[clap(version = "1.0", author = "Kevin K.")]
struct Opts {
    /// Sets a custom config file. Could have been an Option<T> with no default too
    #[clap(short = "c", long = "config", default_value = "default.conf")]
    config: String,
    /// Some input. Because this isn't an Option<T> it's required to be used
    input: String,
    /// A level of verbosity, and can be used multiple times
    #[clap(short = "v", long = "verbose", parse(from_occurrences))]
    verbose: i32,
    #[clap(subcommand)]
    subcmd: SubCommand,
}

#[derive(Clap)]
enum SubCommand {
    /// A help message for the Test subcommand
    #[clap(name = "test", version = "1.3", author = "Someone Else")]
    Test(Test),
}

/// A subcommand for controlling testing
#[derive(Clap)]
struct Test {
    /// Print debug info
    #[clap(short = "d")]
    debug: bool
}

fn main() {
    let opts: Opts = Opts::parse();

    // Gets a value for config if supplied by user, or defaults to "default.conf"
    println!("Value for config: {}", opts.config);
    println!("Using input file: {}", opts.input);

    // Vary the output based on how many times the user used the "verbose" flag
    // (i.e. 'myprog -v -v -v' or 'myprog -vvv' vs 'myprog -v'
    match opts.verbose {
        0 => println!("No verbose info"),
        1 => println!("Some verbose info"),
        2 => println!("Tons of verbose info"),
        3 | _ => println!("Don't be crazy"),
    }

    // You can handle information about subcommands by requesting their matches by name
    // (as below), requesting just the name used, or both at the same time
    match opts.subcmd {
        SubCommand::Test(t) => {
            if t.debug {
                println!("Printing debug info...");
            } else {
                println!("Printing normally...");
            }
        }
    }

    // more program logic goes here...
}

此第二种方法展示了使用 'Builder 模式' 的方法，它允许更高级的配置选项（在此小型示例中未显示），或者在需要时动态生成参数。缺点是它更冗长。

// (Full example with detailed comments in examples/01a_quick_example.rs)
//
// This example demonstrates clap's "builder pattern" method of creating arguments
// which the most flexible, but also most verbose.
extern crate clap;
use clap::{Arg, App, SubCommand};

fn main() {
    let matches = App::new("My Super Program")
                          .version("1.0")
                          .author("Kevin K. <[email protected]>")
                          .about("Does awesome things")
                          .arg(Arg::with_name("config")
                               .short('c')
                               .long("config")
                               .value_name("FILE")
                               .help("Sets a custom config file")
                               .takes_value(true))
                          .arg(Arg::with_name("INPUT")
                               .help("Sets the input file to use")
                               .required(true)
                               .index(1))
                          .arg(Arg::with_name("v")
                               .short('v')
                               .multiple(true)
                               .help("Sets the level of verbosity"))
                          .subcommand(SubCommand::with_name("test")
                                      .about("controls testing features")
                                      .version("1.3")
                                      .author("Someone E. <[email protected]>")
                                      .arg(Arg::with_name("debug")
                                          .short('d')
                                          .help("print debug information verbosely")))
                          .get_matches();

    // Same as above examples...
}

下一个示例展示了更简洁的方法，但牺牲了一些高级配置选项（在此小型示例中未显示）。此方法还带来了一个非常小的运行时开销。

// (Full example with detailed comments in examples/01a_quick_example.rs)
//
// This example demonstrates clap's "usage strings" method of creating arguments
// which is less verbose
extern crate clap;
use clap::{Arg, App, SubCommand};

fn main() {
    let matches = App::new("myapp")
                          .version("1.0")
                          .author("Kevin K. <[email protected]>")
                          .about("Does awesome things")
                          .args_from_usage(
                              "-c, --config=[FILE] 'Sets a custom config file'
                              <INPUT>              'Sets the input file to use'
                              -v...                'Sets the level of verbosity'")
                          .subcommand(SubCommand::with_name("test")
                                      .about("controls testing features")
                                      .version("1.3")
                                      .author("Someone E. <[email protected]>")
                                      .arg("-d, --debug 'Print debug information'"))
                          .get_matches();

    // Same as previous example...
}

此第三种方法展示了如何使用 YAML 文件来构建您的 CLI，并保持您的 Rust 源代码整洁，或者通过为每个本地化创建不同的 YAML 文件来支持多种本地化翻译。

首先，创建一个 cli.yml 文件来存储您的 CLI 选项，但它可以命名为我们喜欢的任何名称

name: myapp
version: "1.0"
author: Kevin K. <[email protected]>
about: Does awesome things
args:
    - config:
        short: c
        long: config
        value_name: FILE
        help: Sets a custom config file
        takes_value: true
    - INPUT:
        help: Sets the input file to use
        required: true
        index: 1
    - verbose:
        short: v
        multiple: true
        help: Sets the level of verbosity
subcommands:
    - test:
        about: controls testing features
        version: "1.3"
        author: Someone E. <[email protected]>
        args:
            - debug:
                short: d
                help: print debug information

由于此功能需要额外的依赖项，这些依赖项并非每个人都需要，因此默认情况下不会编译，我们需要在 Cargo.toml 中启用功能标志

只需将您的 clap = "3.0.0-beta.1" 修改为 clap = {version = "3.0.0-beta.1", features = ["yaml"]}。

最后，我们创建我们的 main.rs 文件，就像前面两个示例一样

// (Full example with detailed comments in examples/17_yaml.rs)
//
// This example demonstrates clap's building from YAML style of creating arguments which is far
// more clean, but takes a very small performance hit compared to the other two methods.
use clap::{App, load_yaml};

fn main() {
    // The YAML file is found relative to the current file, similar to how modules are found
    let yaml = load_yaml!("cli.yml");
    let matches = App::from(yaml).get_matches();

    // Same as previous examples...
}

如果您编译上述任何程序，并使用标志 --help 或 -h（或 help 子命令，因为我们已定义 test 为子命令）运行它们，以下内容将被输出（第一个示例中的帮助信息几乎解释了 Rust 代码）。

$ myprog --help
My Super Program 1.0
Kevin K. <[email protected]>
Does awesome things

ARGS:
    INPUT    The input file to use

USAGE:
    MyApp [FLAGS] [OPTIONS] <INPUT> [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -v               Sets the level of verbosity
    -V, --version    Prints version information

OPTIONS:
    -c, --config <FILE>    Sets a custom config file

SUBCOMMANDS:
    help    Prints this message or the help of the given subcommand(s)
    test    Controls testing features

注意：您还可以运行 myapp test --help 或 myapp help test 来查看 test 子命令的帮助信息。

试试吧！

预构建测试

要尝试预构建示例，请按照以下步骤操作

• 克隆仓库 $ git clone https://github.com/clap-rs/clap && cd clap/
• 编译示例 $ cargo build --example <EXAMPLE>
• 运行帮助信息 $ ./target/debug/examples/<EXAMPLE> --help
• 尝试不同的参数！
• 您也可以通过 $ cargo run --example <EXAMPLE> - [示例参数] 进行一次性运行

BYOB (自己构建二进制文件)

要测试 clap 的默认自动生成帮助/版本，请按照以下步骤操作

• 创建一个新的 cargo 项目 $ cargo new fake --bin && cd fake
• 将 clap 添加到您的 Cargo.toml

[dependencies]
clap = "3.0.0-beta.1"

• 将以下内容添加到您的 src/main.rs

use clap::{App, Clap};

#[derive(Clap)]
#[clap(version = "v1.0-beta")]
/// My First clap CLI!
struct Opts;

fn main() {
    Opts::parse();
}

• 构建您的程序 $ cargo build --release
• 使用帮助或版本号运行，输入 $ ./target/release/fake --help 或 $ ./target/release/fake --version

用法

要完整使用，请在您的 Cargo.toml 中将 clap 添加为依赖项，以便从 crates.io 使用

[dependencies]
clap = "~3.0.0-beta.1"

(注意：如果您关心支持比当前稳定 Rust 低于 2 个稳定版本的最小版本，建议在您的 Cargo.toml 中使用 ~major.minor.patch 风格的版本，这将仅自动更新补丁版本。更多信息请参阅 兼容性策略)

然后，将 extern crate clap; 添加到您的 crate 根目录。

[dependencies.clap]
version = "3.0.0-beta.1"
default-features = false

[dependencies.clap]
version = "3.0.0-beta.1"
default-features = false

# Cherry-pick the features you'd like to use
features = [ "suggestions", "color" ]

[dependencies]
clap = "~3.0.0-beta.1"

# In one Cargo.toml
[dependencies]
clap = "~3.0.0-beta.1"

# In another Cargo.toml
[dependencies]
clap = "3.0.0-beta.1"