Argh

Argh 是一个基于Derive的、针对代码大小优化的参数解析器

基于Derive的参数解析，针对代码大小优化并符合Fuchsia命令行工具规范

此库的公共API主要包括 FromArgs derive 和 from_env 函数，可以使用这些函数从当前程序的命令行参数中生成一个顶级的 FromArgs 类型。

基本示例

use argh::FromArgs;

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

    /// how high to go
    #[argh(option)]
    height: usize,

    /// an optional nickname for the pilot
    #[argh(option)]
    pilot_nickname: Option<String>,
}

fn main() {
    let up: GoUp = argh::from_env();
}

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

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

Reach new heights.

Options:
  -j, --jump        whether or not to jump
  --height          how high to go
  --pilot-nickname  an optional nickname for the pilot
  --help            display usage information

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

• ./some_bin --高度 5
• ./some_bin -j --高度 5
• ./some_bin --跳跃 --高度 5 --飞行员昵称Wes

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

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

use argh::FromArgs;

fn default_height() -> usize {
    5
}

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

    /// an optional height
    #[argh(option, default = "default_height()")]
    height: usize,

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

fn main() {
    let up: GoUp = argh::from_env();
}

只要实现了 FromArgValue 特性（所有 FromStr 类型都自动实现），就可以反序列化自定义选项类型。如果需要更自定义的解析，可以使用 from_str_fn 属性提供自定义的 fn(&str) -> Result<T, String>。

use argh::FromArgs;

#[derive(FromArgs)]
/// Goofy thing.
struct FiveStruct {
    /// always five
    #[argh(option, from_str_fn(always_five))]
    five: usize,
}

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

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

use argh::FromArgs;

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

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

还支持子命令。要使用子命令，需要为每个子命令声明一个单独的 FromArgs 类型以及一个覆盖每个命令的枚举。

use argh::FromArgs;

#[derive(FromArgs, PartialEq, Debug)]
/// Top-level command.
struct TopLevel {
    #[argh(subcommand)]
    nested: MySubCommandEnum,
}

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

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

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

注意：这不是一个官方支持的产品。

如何调试 argh 的展开 derive 宏

可以使用 cargo-expand 包来调试 argh::FromArgs derive 宏。

在 examples/simple_example.rs 中展开 derive 宏

有关我们希望展开的示例结构体的示例，请参阅 argh/examples/simple_example.rs。

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

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