快速示例

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

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

将 clap 添加到您的 Cargo.toml

[dependencies]
clap = { version = "3.0.0-beta.2", package = "nameless-clap" }

使用派生宏

第一个示例展示了使用结构体定义 clap 的最简单方式。如果您熟悉 structopt 库，那么您很幸运，它们是相同的！（实际上，它是运行在底层上的完全相同的代码！）

Clap 引入了自动检测类型是否实现了 FromStr，From<&OsStr>，TryFrom<&OsStr> 和其他标准解析特性，因此在许多情况下，不再需要使用 parse(try_from_str)，parse(from_os_str)，parse(try_from_os_str) 和类似的属性。

// (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::{AppSettings, 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. <[email protected]>")]
#[clap(setting = AppSettings::ColoredHelp)]
struct Opts {
    /// Sets a custom config file. Could have been an Option<T> with no default too
    #[clap(short, long, 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, long, parse(from_occurrences))]
    verbose: i32,
    #[clap(subcommand)]
    subcmd: SubCommand,
}

#[derive(Clap)]
enum SubCommand {
    #[clap(version = "1.3", author = "Someone E. <[email protected]>")]
    Test(Test),
}

/// A subcommand for controlling testing
#[derive(Clap)]
struct Test {
    /// Print debug info
    #[clap(short)]
    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"),
        _ => 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 Pattern' 的一种方法，这允许更高级的配置选项（在此小型示例中没有展示），或者当需要时动态生成参数。缺点是它更冗长。

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

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

    // You can check the value provided by positional arguments, or option arguments
    if let Some(i) = matches.value_of("INPUT") {
        println!("Value for input: {}", i);
    }

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

    // You can see how many times a particular flag or argument occurred
    // Note, only flags can have multiple occurrences
    match matches.occurrences_of("v") {
        0 => println!("Verbose mode is off"),
        1 => println!("Verbose mode is kind of on"),
        2 => println!("Verbose mode is on"),
        _ => println!("Don't be crazy"),
    }

    // You can check for the existence of subcommands, and if found use their
    // matches just as you would the top level app
    if let Some(ref matches) = matches.subcommand_matches("test") {
        // "$ myapp test" was run
        if matches.is_present("debug") {
            // "$ myapp test -d" was run
            println!("Printing debug info...");
        } else {
            println!("Printing normally...");
        }
    }

    // Continued program logic goes here...
}

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

// (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
use clap::App;

fn main() {
    let matches = App::new("myapp")
        .version("1.0")
        .author("Kevin K. <[email protected]>")
        .about("Does awesome things")
        .arg("-c, --config=[FILE] 'Sets a custom config file'")
        .arg("<INPUT>              'Sets the input file to use'")
        .arg("-v...                'Sets the level of verbosity'")
        .subcommand(App::new("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

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

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

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

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

只需将 yaml 功能标志添加到您的 Cargo.toml。

[dependencies]
clap = { version = "3.0.0-beta.2", package = "nameless-clap", 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.yaml");
    let matches = App::from(yaml).get_matches();

    // Same as previous examples...
}

使用宏

最后，还有一个宏版本，这是一种混合方法，它提供了构建模式的速度（第一个例子），但没有所有冗余。

use clap::clap_app;

fn main() {
    let matches = clap_app!(myapp =>
        (version: "1.0")
        (author: "Kevin K. <[email protected]>")
        (about: "Does awesome things")
        (@arg CONFIG: -c --config +takes_value "Sets a custom config file")
        (@arg INPUT: +required "Sets the input file to use")
        (@arg verbose: -v --verbose "Print test information verbosely")
        (@subcommand test =>
            (about: "controls testing features")
            (version: "1.3")
            (author: "Someone E. <[email protected]>")
            (@arg debug: -d ... "Sets the level of debugging information")
        )
    ).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> - [args to example] 进行一次性运行

构建自己的二进制文件

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

• 创建一个新的 cargo 项目 $ cargo new fake --bin && cd fake
• 按照快速示例部分描述编写您的程序。
• 构建您的程序 $ cargo build --release
• 使用帮助或版本运行 $ ./target/release/fake --help 或 $ ./target/release/fake --version

使用方法

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

[dependencies]
clap = { version = "3.0.0-beta.2", package = "nameless-clap" }

定义您的程序的有效参数列表（请参阅文档或此仓库的示例目录）

然后运行 cargo build 或 cargo update && cargo build 以构建您的项目。

可选依赖/特性

默认启用的特性

• derive: 启用自定义 derive（即 #[derive(Clap)]）。没有这个选项，您必须使用上面列出的其他创建 clap CLI 的方法。
• cargo: 打开从 CARGO_* 环境变量读取值的宏。
• suggestions: 当用户输入错误时，打开 Did you mean '--myoption'? 功能。 (构建依赖 strsim)
• color: 打开彩色错误信息。您仍然需要通过设置 AppSettings::ColoredHelp 来打开彩色帮助。 (构建依赖 termcolor)
• unicode_help: 打开在帮助信息中支持 Unicode 字符的支持。 (构建依赖 textwrap)

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

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

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

[dependencies]
clap = { version = "~3.0.0-beta.2", package = "nameless-clap" }