Lib.rs

基本示例

use argp::FromArgs;

/// Reach new heights.
#[derive(FromArgs)]
struct GoUp {
    /// Whether or not to jump.
    #[argp(switch, short = 'j')]
    jump: bool,

    /// How high to go.
    #[argp(option, arg_name = "meters")]
    height: usize,

    /// An optional nickname for the pilot.
    #[argp(option, arg_name = "name")]
    pilot_nickname: Option<String>,
}

fn main() {
    let up: GoUp = argp::parse_args_or_exit(argp::DEFAULT);
}

./some_bin --help 将输出以下内容

Usage: cmdname [-j] --height <meters> [--pilot-nickname <name>]

Reach new heights.

Options:
  -j, --jump                   Whether or not to jump.
      --height <meters>        How high to go.
      --pilot-nickname <name>  An optional nickname for the pilot.
  -h, --help                   Show this help message and exit.

生成的程序可以用以下任何一种方式使用

• ./some_bin --height 5

• ./some_bin -j --height 5

• ./some_bin --jump --height 5 --pilot-nicknameWes

开关，如 jump，是可选的，如果提供，则设置为 true。

选项，如 height 和 pilot_nickname，可以是必需的、可选的或重复的，具体取决于它们是否包含在 Option 或 Vec 中。可以使用 #[argp(default = "<your_code_here>")] 属性提供默认值，在这种情况下，选项被视为可选的。

use argp::FromArgs;

fn default_height() -> usize {
    5
}

/// Reach new heights.
#[derive(FromArgs)]
struct GoUp {
    /// An optional nickname for the pilot.
    #[argp(option)]
    pilot_nickname: Option<String>,

    /// An optional height.
    #[argp(option, default = "default_height()")]
    height: usize,

    /// An optional direction which is "up" by default.
    #[argp(option, default = "String::from(\"only up\")")]
    direction: String,
}

fn main() {
    let up: GoUp = argp::parse_args_or_exit(argp::DEFAULT);
}

只要实现 FromArgValue 特性（已经为在 std 中实现 FromStr 特性的大多数类型实现），就可以反序列化自定义选项类型。如果需要更多的自定义解析，可以使用 from_str_fn 属性提供一个自定义 fn(&str) → Result<T, E>，或者使用 from_os_str_fn 属性提供一个自定义 fn(&OsStr) → Result<T, E>，其中 E 实现 ToString

use argp::FromArgs;
use std::ffi::OsStr;
use std::path::PathBuf;

/// Goofy thing.
#[derive(FromArgs)]
struct FineStruct {
    /// Always five.
    #[argp(option, from_str_fn(always_five))]
    five: usize,

    /// File path.
    #[argp(option, from_os_str_fn(convert_path))]
    path: PathBuf,
}

fn always_five(_value: &str) -> Result<usize, String> {
    Ok(5)
}

fn convert_path(value: &OsStr) -> Result<PathBuf, String> {
    Ok(PathBuf::from("/tmp").join(value))
}

可以使用 #[argp(positional)] 来声明位置参数。这些参数将按照结构体中声明的顺序进行解析。

use argp::FromArgs;

/// A command with positional arguments.
#[derive(FromArgs, PartialEq, Debug)]
struct WithPositional {
    #[argp(positional)]
    first: String,
}

最后一个位置参数可以包含默认值，或者用 Option 或 Vec 包装，以表示可选或重复的位置参数。

也支持子命令。要使用子命令，为每个子命令声明一个单独的 FromArgs 类型，以及一个遍历每个命令的枚举。

use argp::FromArgs;

/// Top-level command.
#[derive(FromArgs, PartialEq, Debug)]
struct TopLevel {
    /// Be verbose.
    #[argp(switch, short = 'v', global)]
    verbose: bool,

    #[argp(subcommand)]
    nested: MySubCommandEnum,
}

#[derive(FromArgs, PartialEq, Debug)]
#[argp(subcommand)]
enum MySubCommandEnum {
    One(SubCommandOne),
    Two(SubCommandTwo),
}

/// First subcommand.
#[derive(FromArgs, PartialEq, Debug)]
#[argp(subcommand, name = "one")]
struct SubCommandOne {
    /// How many x.
    #[argp(option)]
    x: usize,
}

/// Second subcommand.
#[derive(FromArgs, PartialEq, Debug)]
#[argp(subcommand, name = "two")]
struct SubCommandTwo {
    /// Whether to fooey.
    #[argp(switch)]
    fooey: bool,
}

有关更多信息，请参阅 argp 文档。

如何调试 argp 的展开 derive 宏

可以使用 cargo-expand crate 调试 argp::FromArgs derive 宏。

在 examples/simple_example.rs 中展开 derive 宏

请参阅 argp/examples/simple_example.rs，以了解我们希望展开的示例结构体。

首先，通过运行 cargo install cargo-expand 来安装 cargo-expand。注意，这需要 Rust 的夜间构建。

安装完成后，在 argp 包中运行 cargo expand，您可以看到展开的代码。

许可证

本项目采用 BSD-3-Clause 许可证。有关许可证的全文，请参阅 LICENSE 文件。

1. 在带有 strip = true 和 panic = "abort" 的发布构建中进行了测量。确切的大小取决于多个因素，包括选项和子命令的数量。