Rust库clap：命令行工具clap 命令行解析 clap是一个易于使用、高效且功能齐全的库，用于在编写控制台/终端应

clap 命令行解析

方法内容来源于官网的翻译，若有误，可在评论区帮助改正

clap是一个易于使用、高效且功能齐全的库，用于在编写控制台/终端应用程序时解析命令行参数和子命令。

clap用于解析并验证用户在运行命令行程序时提供的命令行参数字符串。你所需要做的只是提供有效参数的列表，clap会自动处理其余的繁杂工作。这样工程师可以把时间和精力放在实现程序功能上，而不是参数的解析和验证上。

当clap解析了用户提供的参数字符串，它就会返回匹配项以及任何适用的值。如果用户输入了错误或错字，clap会通知他们错误并退出（或返回Result类型，并允许您在退出前执行任何清理操作）。这样，工程师可以在代码中对参数的有效性做出合理的假设。

导入依赖

cargo add clap --features derive

发生以下几个操作：

添加 clap 依赖：
- cargo add clap 会将 clap 库添加到当前 Rust 项目的 Cargo.toml 文件中。如果没有手动编辑过 Cargo.toml，这个命令会自动处理添加依赖的过程。具体来说，clap 会被添加到 [dependencies] 部分，并且使用最新的稳定版本，除非你指定了版本号。
启用 derive 特性：
- --features derive 指定启用 clap 库的 derive 特性。derive 特性允许使用 clap 提供的宏，例如 #[derive(Parser)]，来自动派生命令行解析器，而不需要手动写太多代码。

具体执行内容：

在 Cargo.toml 中，clap 依赖项会被添加到 [dependencies] 部分，并且 derive 特性会被启用。例如，Cargo.toml 会变成这样：
```
[dependencies]
clap = { version = "4.0", features = ["derive"] }
```
此外，cargo add 会自动更新 Cargo.lock 文件，以确保该依赖被正确解析。

derive 特性的作用：

启用 derive 特性后，你可以使用 clap 的派生宏，如下所示：

use clap::Parser;

/// 一个简易程序
// 派生宏
/**
 * Parser：来自 clap 库，自动为结构体实现命令行参数解析功能
 * Debug：实现 Debug trait，允许使用 {:?} 格式化打印结构体
 */
#[derive(Parser, Debug)]
/**
 * 命令行程序的元信息
 * version：自动从 Cargo.toml 获取版本信息
 * about：使用文档注释作为程序描述
 * long_about = None：不提供详细描述
 */
#[command(version, about, long_about = None)]
struct Args {
    #[arg(short, long)] // 支持 -n 和 --name 两种参数形式
    name: String,

    #[arg(short, long, default_value_t = 1)] // 支持 -c 和 --count，默认值为 1
    count: u8,
}

fn main() {
    let args = Args::parse();

    for _ in 0..args.count {
        println!("Hello {}!", args.name);
    }
}

总结：cargo add clap --features derive 会将 clap 库添加到 Cargo.toml，并启用 derive 特性，使你可以使用 clap 的宏来简化命令行解析器的创建过程。

`Arg`结构体方法列表

基本方法

`new()`

pub fn new(id: impl Into<Id>) -> Arg // 创建一个具有唯一名称的新的Arg结构体类型

该名称用于检查参数是否在运行时使用、获取值、设置与其他参数的关系等。

// 示例
Arg::new("config")

如果参数取值（即Arg::action（ArgAction::Set））和位置参数（即没有前面的-或--），当用户打印程序的 usage/help 信息时，也会显示名称。

`id()`

pub fn id(self, id: impl Into<Id>) -> Arg

设置用于在clap API中引用此参数的标识符。

`short()`

// 传递一个字符参数
pub fn short(self, s: impl IntoResettable<char>) -> Arg

用于设置简短参数的版本

默认情况下，-V和-h分别自动生成版本和帮助参数使用。需要禁用自动生成的标志（disable_help_flag、disable_version_flag）并定义自己的标志。

`long()`

// 参数传递一个字符串类型
pub fn long(self, l: impl IntoResettable<Str>) -> Arg

设置前面带有--的参数的长版本。

默认情况下，自动生成的版本和帮助参数分别使用版本和帮助。可以使用单词version或help来表示自己的参数的长形式，在这种情况下，clap不会将它们分配给自动生成的版本或帮助参数。

`alias()`、`short_alias()`

// 添加一个假名，用作隐藏的长标志。
pub fn alias(self, name: impl IntoResettable<Str>) -> Arg

// 添加一个假名，用作隐藏的短标志。
pub fn short_alias(self, name: impl IntoResettable<char>) -> Arg

这比创建多个隐藏参数更有效、更容易，因为只需要检查此命令的存在，而不是所有变体。

`aliases()`、`short_aliases()`

// 添加多个别名，其函数为隐藏的长标志。
pub fn aliases(self, names: impl IntoIterator<Item = impl Into<Str>>) -> Arg

// 添加多个别名，其函数为隐藏的短标志。
pub fn short_aliases(self, names: impl IntoIterator<Item = char>) -> Arg

这比创建多个隐藏子命令更有效、更容易，因为只需要检查此命令的存在，而不是所有变体。

`visible_alias()`、`visible_short_alias()`

// 添加一个假名，用作可见的长标志
pub fn visible_alias(self, name: impl IntoResettable<Str>) -> Arg

pub fn visible_short_alias(self, name: impl IntoResettable<char>) -> Arg

`visible_aliases()`、`visible_short_aliases()`

// 添加多个别名，其函数为可见的长标志。
pub fn visible_aliases(
    self,
    names: impl IntoIterator<Item = impl Into<Str>>,
) -> Arg

pub fn visible_short_aliases(self, names: impl IntoIterator<Item = char>) -> Arg

`index()`

pub fn index(self, idx: impl IntoResettable<usize>) -> Arg

指定从1开始的位置参数的索引。

注意：

索引根据其他位置参数引用位置。它不定义整个参数列表中的位置。

可以选择省略index方法，索引将按评估顺序分配。使用index方法允许无序设置索引

仅用于位置参数，不应该与Arg::short或Arg::long一起使用。

当与[Arg::num_args（1…）]一起使用时，只有最后一个位置参数可以定义为具有可变数量的参数（即具有最高索引）

`trailing_var_arg()`

pub fn trailing_var_arg(self, yes: bool) -> Arg

这是一个“var arg”，接下来的所有内容都应该被它捕获，就好像用户使用了--。

注意：

要在未知标志（而不仅仅是位置值）上启动尾随的“var arg”，请设置allow_hyphen_values。无论哪种方式，用户仍然可以选择使用--显式逃逸模棱两可的参数。

如果设置Arg::value_delimiter仍然适用。

设置此项需要Arg::num_args(…)。

`last()`

pub fn last(self, yes: bool) -> Arg

这个arg是最后一个或最后一个位置参数参数（即具有最高索引），只能通过--语法（即$prog args--last_arg）访问。

甚至，如果没有其他参数可供解析，如果用户省略--语法，他们将收到一个未知参数错误。将参数设置为. last(true)还允许使用--语法提前访问此参数。否则不可能提前访问arg，即使使用--语法。

设置last可确保arg具有所有位置arg的最高索引，并要求使用--语法提前访问它。即使标记为Last的位置参数是唯一需要解析的参数，未能使用--语法也会导致错误。

`required()`

pub fn required(self, yes: bool) -> Arg

指定参数必须存在。设置为必需，然后在运行时不提供该参数是错误的。

当没有评估其他冲突规则或覆盖时，默认表示它是必需的。冲突规则优先于必需规则。

专业提示：默认不需要标志（即非位置或取值的参数）。这是因为如果需要标志，它应该是隐含的。用户不需要额外的信息。标志本质上只是 Boolean on/off 。唯一需要用户使用标志的时候是操作本质上是破坏性的，用户基本上是在向你证明，“是的，我知道我在做什么。”

`requires()`

pub fn requires(self, arg_id: impl IntoResettable<Id>) -> Arg

设置此参数存在时所需的参数。即当使用此参数时，必须存在以下参数。

注意：冲突规则和覆盖规则优先于必需规则

设置Arg::requires(name)要求在运行时使用定义参数。如果没有使用定义参数，则不需要其他参数

`exclusive()`

pub fn exclusive(self, yes: bool) -> Arg

此参数必须单独传递；它与所有其他参数冲突。

`global()`

pub fn global(self, yes: bool) -> Arg

指定参数可以与所有子子命令匹配。

注意：全局参数只向下传播，而不是向上传播（到父命令），但是一旦用户使用它们，它们的值将被传播回父命令。实际上，这意味着应该在顶层定义所有全局参数，但是用户在哪里使用全局参数并不重要。

假设一个有两个子命令的应用程序，想定义一个可以在任何子命令和父命令上调用的--verbose，但不想用三个重复的Arg定义使源代码混乱。

let m = Command::new("prog")
    .arg(Arg::new("verb")
        .long("verbose")
        .short('v')
        .action(ArgAction::SetTrue)
        .global(true))
    .subcommand(Command::new("test"))
    .subcommand(Command::new("do-stuff"))
    .get_matches_from(vec![
        "prog", "do-stuff", "--verbose"
    ]);

assert_eq!(m.subcommand_name(), Some("do-stuff"));
let sub_m = m.subcommand_matches("do-stuff").unwrap();
assert_eq!(sub_m.get_flag("verb"), true);

`add()`

pub fn add <T>(self, Tagged: T) -> Arg
where
T: ArgExt + Extension

使用ArgExt数据扩展Arg

Value 处理器

`action()`

pub fn action ( self, action: impl IntoResettable <ArgAction> ) -> Arg

指定解析参数时如何对其作出反应。默认操作是ArgAction::Set

用新值覆盖先前的值
将新值附加到所有先前的值
计算标志出现的次数

`value_parser()`

pub fn value_parser(self, parser: impl IntoResettable<ValueParser>) -> Arg

指定参数的类型化行为。允许在将值作为给定类型存储到ArgMatches之前解析和验证值。默认值是ValueParser::String。

可能的值解析器包括：

value_parser!(T)用于为给定类型自动选择值解析器，或者像0..=1范围表达式作为RangedI64ValueParser的简写
Fn(&str)->Result<T， E>
`[&str]和PossibleValuesParser静态枚举值
用于替代 boolean 实现的BoolishValueParser和`FalseyValueParser``
`NonEmptyStringValueParser字符串的基本验证
或任何其他TyedValueParser实现

`num_args()`

pub fn num_args(self, qty: impl IntoResettable<ValueRange>) -> Arg

指定每次发生解析的参数数

例如，如果有一个-f <file>参数，只需要3个“文件”，将设置：num_args(3)，除非用户提供3个且仅提供3个值，否则此参数将不会得到满足。

用户可以在以下任何方法中为参数指定值

使用空格，例如-o value或--option value
使用等于且没有空格，例如-o=value或--ption=value
使用简短且无空格，例如-ovalue

警告：

在某些情况下，为没有其他详细信息的参数设置可变数量的值（例如1..=10）可能是危险的。因为允许多个值，--option val1 val2 val3是完全有效的。在设计位置参数或子命令也需要的CLI时要小心，因为clap将继续解析值，直到发生以下情况之一：

它达到值的最大数量

它达到特定数量的值

它会找到另一个标志或选项（即以-开头的东西）

如果设置了Arg::value_terminator，且到达终止符

在Arg::value_delimiter值之间使用分隔符

要求每个值出现一个标志ArgAction::Append

要求位置参数Arg::last出现在--之后

`value_name()`、`value_names()`

pub fn value_name(self, name: impl IntoResettable<Str>) -> Arg

pub fn value_names(self, names: impl IntoIterator<Item = impl Into<Str>>) -> Arg

帮助 message/usage 中参数值的占位符。

此名称只是装饰性的；该名称不用于访问参数。此设置在描述用户应该使用的输入类型时非常有用，例如FILE、INTERFACE等。虽然不是必需的，但在某种程度上使用所有大写字母作为值名称是惯例。

let m = Command::new("prog")
.arg(Arg::new("config")
    .long("config")
    .value_name("FILE")
    .help("Some help text"))
.get_matches_from(vec![
    "prog", "--help"
]);

image-20250816203309495转存失败，建议直接上传图片文件

参数的值按数字顺序访问（即，如果指定两个名称，A和B，A将是第一个匹配的值，B将是第二个）

`value_hint()`

// 向shell提供有关如何完成此参数的提示
pub fn value_hint(self, value_hint: impl IntoResettable<ValueHint>) -> Arg

`ignore_case()`

pub fn ignore_case(self, yes: bool) -> Arg

不匹配大小写，将值与PossibleValuesParser匹配。

当基于不区分大小写的参数的值有条件地需要其他参数时，Arg::required_if_eq、Arg::required_if_eq_any或Arg::required_if_eq_all进行的相等性检查不区分大小写。

注意：要进行unicode大小写折叠，请启用unicode功能标志。

`allow_hyphen_values()`

pub fn allow_hyphen_values(self, yes: bool) -> Arg

允许以前导连字符（-）开头的值

警告：allow_hyphen_values(true)的先前参数优先于已知标志，但已知标志优先于allow_hyphen_values(true)的下一个可能的位置参数。当与[Arg::num_args(..)]结合使用时，Arg::value_terminator是确保处理停止的一种方法。

`allow_negative_numbers()`

pub fn allow_negative_numbers(self, yes: bool) -> Arg

允许负数作为值传递。

`require_equals()`

pub fn require_equals(self, yes: bool) -> Arg

要求选项使用--ption=val语法，即选项和相关值之间的等于（设置require_equals要求选项与关联值之间有一个等号。）。

`value_delimiter()`

pub fn value_delimiter(self, d: impl IntoResettable<char>) -> Arg

允许通过分隔符对多个值进行分组。即允许将值（val1、val2、val3）解析为三个值（val1、val2和val3）而不是一个值（val1、val2、val3）。

`value_terminator()`

pub fn value_terminator(self, term: impl IntoResettable<Str>) -> Arg

指定停止解析给定参数的多个值。

此设置仅适用于选项和位置参数

默认情况下，当一个参数设置num_args(1..)时，clap将继续解析该参数的值，直到它到达另一个有效参数，或者使用多个值的其他更具体的设置之一（例如num_args）。

当终止符在命令行上传入时，它不会存储为值

`raw()`

pub fn raw(self, yes: bool) -> Arg

使用以下所有参数。不要单独解析它们，而是完整地传递它们。

值得注意的是，设置this要求所有值都在--之后，以指示它们都应该被捕获。

--foo something -- -v -v -v -b -b -b --baz -q -u -x

会导致--之后的一切被认为是一个原始参数。这种行为可能不是所期望的，使用Arg::trailing_var_arg可能更合适。

隐式设置Arg::action(ArgAction::Set)，Arg::num_args(1..)，Arg::allow_hyphen_values(true)，Arg::last(true)时设置为true。

`default_value()`、`default_values()`

pub fn default_value(self, val: impl IntoResettable<OsStr>) -> Arg

pub fn default_values(
    self,
    vals: impl IntoIterator<Item = impl Into<OsStr>>,
) -> Arg

设置参数的默认值，与命令行值一样，这将由Arg::value_delimiter拆分。

注意：如果用户在运行时不使用此参数ArgMatches::contains_id仍将返回true。如果希望确定参数是否在运行时使用，请考虑ArgMatches::value_source。

注意：此设置与Arg::default_value_if完全兼容，但略有不同。

Arg::default_value仅在用户未在运行时提供此arg时生效。

Arg::default_value_if仅在用户未在运行时提供值并且满足这些其他条件时生效。

如果设置了Arg::default_value和Arg::default_value_if，并且用户未在运行时提供此arg，也未满足Arg::default_value_if的条件，则将应用Arg::default_value。

`default_missing_value()`、`default_missing_value_os()`、`default_missing_values()`、`default_missing_values_os()`

pub fn default_missing_value(self, val: impl IntoResettable<OsStr>) -> Arg

pub fn default_missing_value_os(self, val: impl Into<OsStr>) -> Arg

pub fn default_missing_values(
    self,
    vals: impl IntoIterator<Item = impl Into<OsStr>>,
) -> Arg

pub fn default_missing_values_os(
    self,
    vals: impl IntoIterator<Item = impl Into<OsStr>>,
) -> Arg

标志存在但未指定值时参数的值。

此配置选项通常用于为用户提供快捷方式，并允许他们在不需要显式值的情况下有效地指定选项参数。--color参数是一个常见的示例。通过提供默认值，例如default_missing_value("always")，用户可以快速地将--color添加到命令行以生成所需的颜色输出。

与命令行值一样，这将由Arg::value_delimiter拆分。

注意：使用此配置选项需要使用.num_args(0..N)和.require_equals(true)配置选项。这些是必需的，以便明确确定为参数提供了什么值（如果有的话）。

`env()`

pub fn env(self, name: impl IntoResettable<OsStr>) -> Arg

当参数参数不存在时，从名称环境变量中读取。如果环境中不存在，则将应用默认规则。

如果用户在环境中设置参数：

当Arg::action(ArgAction::Set)未设置时，标志被认为已升起。
当Arg::action(ArgAction::Set)被设置时，ArgMatches::get_one将返回环境变量的值。

如果user没有在环境中设置参数：

当Arg::action(ArgAction::Set)未设置时，该标志被视为关闭。
设置Arg::action(ArgAction::Set)时，ArgMatches::get_one将返回指定的默认值。

与命令行值一样，这将由Arg::value_delimiter拆分。

请注意，值解析器控制如何解析标志。在这种情况下，选择了FalseyValueParser。false文字是n、no、f、false、off或0。不存在的环境变量也将被视为false。其他任何内容都将被视为true。

高级参数

`group()`、`groups()`

pub fn group(self, group_id: impl IntoResettable<Id>) -> Arg

pub fn groups(self, group_ids: impl IntoIterator<Item = impl Into<Id>>) -> Arg

参数所属的ArgGroup的名称。

`default_value_if()`、`default_value_ifs()`

pub fn default_value_if(
    self,
    arg_id: impl Into<Id>,
    predicate: impl Into<ArgPredicate>,
    default: impl IntoResettable<OsStr>,
) -> Arg

pub fn default_value_ifs(
    self,
    ifs: impl IntoIterator<Item = (impl Into<Id>, impl Into<ArgPredicate>, impl IntoResettable<OsStr>)>,
) -> Arg

如果在运行时使用了arg，则指定参数的值。

如果default设置为None，default_value将被删除。

与命令行值一样，这将由Arg::value_delimiter拆分。

`required_unless_present()`、`required_unless_present_all()`、`required_unless_present_any()`

pub fn required_unless_present(self, arg_id: impl IntoResettable<Id>) -> Arg

pub fn required_unless_present_all(
    self,
    names: impl IntoIterator<Item = impl Into<Id>>,
) -> Arg

pub fn required_unless_present_any(
    self,
    names: impl IntoIterator<Item = impl Into<Id>>,
) -> Arg

只要指定的参数在运行时不存在，就根据需要设置此参数。

`required_if_eq()`、`required_if_eq_any()`、`required_if_eq_all()`

pub fn required_if_eq(self, arg_id: impl Into<Id>, val: impl Into<OsStr>) -> Arg

pub fn required_if_eq_any(
    self,
    ifs: impl IntoIterator<Item = (impl Into<Id>, impl Into<OsStr>)>,
) -> Arg

pub fn required_if_eq_all(
    self,
    ifs: impl IntoIterator<Item = (impl Into<Id>, impl Into<OsStr>)>,
) -> Arg

仅当指定的arg在运行时存在并且其值等于val时，才需要此参数。

`requires_if()`、`requires_ifs()`

pub fn requires_if(
    self,
    val: impl Into<ArgPredicate>,
    arg_id: impl Into<Id>,
) -> Arg

pub fn requires_ifs(
    self,
    ifs: impl IntoIterator<Item = (impl Into<ArgPredicate>, impl Into<Id>)>,
) -> Arg

如果此参数与ArgPredicate匹配，则需要另一个参数

`conflicts_with()`、`conflicts_with_all()`

pub fn conflicts_with(self, arg_id: impl IntoResettable<Id>) -> Arg

pub fn conflicts_with_all(
    self,
    names: impl IntoIterator<Item = impl Into<Id>>,
) -> Arg

此参数与指定的参数相互排斥。

注意：

冲突规则优先于默认需要。冲突规则只需要为两个参数中的一个设置，不需要为每个参数设置。定义冲突是双向的，但不需要为两个参数都定义（即如果A与B冲突，定义A.conflicts_with(B)就足够了。不需要同时做B.conflicts_with(A)）

Arg::conflicts_with_all(name)允许指定与多个参数冲突的参数。

Arg::exclusive(true)允许指定与其他参数冲突的参数。

所有参数都隐含地与自身冲突。

`overrides_with_all()`

pub fn overrides_with(self, arg_id: impl IntoResettable<Id>) -> Arg

设置可覆盖的参数。即此参数和以下参数将以POSIX样式相互覆盖（在运行时最后“获胜”指定的参数）

注意：当一个参数被覆盖时，它基本上就像它从未被使用过一样，任何冲突、要求等都会在删除所有“覆盖”后进行评估；覆盖参数意味着它们冲突。

`Command`结构体方法列表

基本方法

`new()`

pub fn new(name: impl Into<Str>) -> Command

创建命令的新实例。

使用二进制名称作为名称很常见，但不是必需的。此名称仅在用户请求打印版本或帮助和使用信息时才会显示给用户。

`arg()`、`args()`、`mut_arg()`、`mut_args()`

// 将参数添加到有效可能性列表中
pub fn arg(self, a: impl Into<Arg>) -> Command

// 将多个参数添加到有效可能性列表中
pub fn args(self, args: impl IntoIterator<Item = impl Into<Arg>>) -> Command

// 允许在将Arg添加到命令后对其进行修改
// panic: 如果参数未定义
pub fn mut_arg<F>(self, arg_id: impl AsRef<str>, f: F) -> Command
where
    F: FnOnce(Arg) -> Arg,

pub fn mut_args<F>(self, f: F) -> Command
where
    F: FnMut(Arg) -> Arg,

`group()`、`groups()`、`mut_group()`

// 将ArgGroup添加到应用程序
pub fn group(self, group: impl Into<ArgGroup>) -> Command

pub fn groups(
    self,
    groups: impl IntoIterator<Item = impl Into<ArgGroup>>,
) -> Command

ArgGroup是一系列相关参数。通过将它们放在一个逻辑组中，可以构建更简单的需求和排除规则。

// 允许在将ArgGroup添加到命令后对其进行改变
// panic: 如果参数未定义
pub fn mut_group<F>(self, arg_id: impl AsRef<str>, f: F) -> Command
where
    F: FnOnce(ArgGroup) -> ArgGroup,

`subcommand()`、`subcommands()`、`mut_subcommand()`、`mut_subcommands()`

// 将子命令添加到有效可能性列表中。
// 子命令实际上是子命令，因为它们可以包含自己的参数、子命令、版本、用法等。
// 子命令也像命令一样起作用，因为它们有自己自动生成的帮助、版本和用法。
pub fn subcommand(self, subcmd: impl Into<Command>) -> Command

pub fn subcommands(
    self,
    subcmds: impl IntoIterator<Item = impl Into<Command>>,
) -> Command

子命令Command::name将用于：

用户传入的参数
以编程方式查找子命令

// 允许在将命令添加为子命令后对其进行修改
// 对于使用Command::mut_arg修改嵌套子命令的自动生成参数很有用。
pub fn mut_subcommand<F>(self, name: impl AsRef<str>, f: F) -> Command
where
    F: FnOnce(Command) -> Command,

pub fn mut_subcommands<F>(self, f: F) -> Command
where
    F: FnMut(Command) -> Command,

`defer()`

// 命令部分的延迟初始化(对于大型应用程序延迟子命令的定义直到调用它们很有用)
pub fn defer(self, deferred: fn(Command) -> Command) -> Command

`error()`

// 解析后验证的自定义错误消息
pub fn error(&mut self, kind: ErrorKind, message: impl Display) -> Error

`get_matches()`、`get_matches_mut()`、`try_get_matches()`

// 解析env::args_os，失败退出
// panic: 如果存在矛盾的参数或设置（调试版本）。
pub fn get_matches(self) -> ArgMatches

// 该方法不会消费命令
pub fn get_matches_mut(&mut self) -> ArgMatches

// Parse env::args_os, returning a clap::Result on failure.
pub fn try_get_matches(self) -> Result<ArgMatches, Error>

注意：当使用--help或--version（或短版本）时，此方法不会退出。它将返回一个clap::Error，其中类型分别为ErrorKind::Displayhelp或ErrorKind::DisplayVersion。必须调用Error::exit或std::process::exit。

`get_matches_from()`、`try_get_matches_from()`、`try_get_matches_from_mut()`

// 解析指定的参数，失败退出
pub fn get_matches_from<I, T>(self, itr: I) -> ArgMatches
where
    I: IntoIterator<Item = T>,
    T: Into<OsString> + Clone,

pub fn try_get_matches_from<I, T>(self, itr: I) -> Result<ArgMatches, Error>
where
    I: IntoIterator<Item = T>,
    T: Into<OsString> + Clone,

注意：除非使用Command::no_binary_name，否则第一个参数将被解析为二进制名称。

pub fn try_get_matches_from_mut<I, T>(
    &mut self,
    itr: I,
) -> Result<ArgMatches, Error>
where
    I: IntoIterator<Item = T>,
    T: Into<OsString> + Clone,

`print_help()`、`print_long_help()`

// Prints the short help message (-h) to io::stdout().
pub fn print_help(&mut self) -> Result<(), Error>

pub fn print_long_help(&mut self) -> Result<(), Error>

`render_help()`、`render_long_help()`

// Render the short help message (-h) to a StyledStr
pub fn render_help(&mut self) -> StyledStr

pub fn render_long_help(&mut self) -> StyledStr

`render_version()`、`render_long_version()`

// Version message rendered as if the user ran -V.
pub fn render_version(&self) -> String

pub fn render_long_version(&self) -> String

`render_usage()`

pub fn render_usage(&mut self) -> StyledStr

`add()`

// 使用Command Ext数据扩展命令
pub fn add<T>(self, tagged: T) -> Command
where
    T: CommandExt + Extension,

应用程序范围设置

`no_binary_name()`

pub fn no_binary_name(self, yes: bool) -> Command

指定解析器，不假定传递的第一个参数是二进制名称。使用“守护程序”样式模式时通常会出现这种情况。

`ignore_errors()`

pub fn ignore_errors(self, yes: bool) -> Command

尽量不要在解析错误时失败，例如缺少选项值。

注意：此选择会传播到所有子命令。

`args_override_self()`

pub fn args_override_self(self, yes: bool) -> Command

替换先前出现的参数而不是错误

对于默认情况下与自身冲突的任何参数（例如ArgAction::Set，它现在将覆盖自身。

这相当于说foo arg使用Arg::overrides_with("foo")为所有定义的参数。

dont_delimit_trailing_values()

禁用在使用Arg::trailing_var_arg之后或--时自动定界的值。

`color()`

pub fn color(self, color: ColorChoice) -> Command

设置何时颜色输出。

`styles()`

pub fn styles(self, styles: Styles) -> Command

设置终端输出的样式。注意：此选择会传播到所有子命令。

`term_width()、max_term_width()`

pub fn term_width(self, width: usize) -> Command

pub fn max_term_width(self, width: usize) -> Command

设置包装帮助消息的终端宽度。

使用0将忽略终端宽度并使用源格式。

启用功能标志时默认为当前wrap_help终端宽度。如果无法确定当前宽度，则默认为100。

注意：此设置适用于全局，而不是基于每个命令。

`disable_version_flag()`、`disable_help_flag()`

// 禁用-V和--version标志
pub fn disable_version_flag(self, yes: bool) -> Command

// Disables -h and --help flag.
pub fn disable_help_flag(self, yes: bool) -> Command

`propagate_version()`

// 指定对所有子命令使用当前命令的版本
pub fn propagate_version(self, yes: bool) -> Command

默认为false；子命令具有来自其父命令的独立版本字符串。

`next_line_help()`

pub fn next_line_help(self, yes: bool) -> Command

将所有参数和子命令的帮助字符串放在它们之后的行上。

`disable_help_subcommand()`

// Disables the help subcommand.
pub fn disable_help_subcommand(self, yes: bool) -> Command

`disable_colored_help()`

// Disables colorized help messages.
pub fn disable_colored_help(self, yes: bool) -> Command

`help_expected()`

// 如果省略帮助描述，则会panic
pub fn help_expected(self, yes: bool) -> Command

注意：使用派生解析器时，可以在编译时使用#![deny(missing_docs)]检查它

`hide_possible_values()`

pub fn hide_possible_values(self, yes: bool) -> Command

告诉clap在显示帮助信息时不要打印可能的值。如果有许多值，或者它们在其他地方被解释，这可能很有用。

`infer_long_args()`

pub fn infer_long_args(self, yes: bool) -> Command

允许长参数或其别名的部分匹配。例如，要匹配名为--test的参数，可以使用--t、--te、--tes和--test。

注意：匹配必须完全不含糊才能成功。即要将--te匹配到--test，也不能有另一个参数或别名--temp，因为两者都以--te开头

`infer_subcommands()`

pub fn infer_subcommands(self, yes: bool) -> Command

允许子命令名称及其别名的部分匹配。例如，要匹配名为test的子命令，可以使用t、te、tes和test。

特定命令的设置

`name()`

// 重新设置程序的名称
pub fn name(self, name: impl Into<Str>) -> Command

`bin_name()`

// 覆盖帮助和错误消息的二进制文件的运行时确定名称。
pub fn bin_name(self, name: impl IntoResettable<String>) -> Command

这只应在绝对必要时使用，例如当您的应用程序的二进制名称具有误导性时，或者可能不是用户应该如何调用您的程序时。

`display_name()`

// 覆盖程序的运行时确定的显示名称以获取帮助和错误消息。
pub fn display_name(self, name: impl IntoResettable<String>) -> Command

`author()`

// 作者
pub fn author(self, author: impl IntoResettable<Str>) -> Command

`about()`、`long_about()`

// 设置程序描述。在使用-h时显示
pub fn about(self, about: impl IntoResettable<StyledStr>) -> Command

pub fn long_about(self, long_about: impl IntoResettable<StyledStr>) -> Command

`after_help()`、`after_long_help()`

// 自动生成简短帮助（-h）后的自由格式帮助文本。
pub fn after_help(self, help: impl IntoResettable<StyledStr>) -> Command

pub fn after_long_help(self, help: impl IntoResettable<StyledStr>) -> Command

`before_help()`、`before_long_help()`

// 自动生成简短帮助（-h）之前的自由格式帮助文本。这通常用于标头、版权或许可证信息。
pub fn before_help(self, help: impl IntoResettable<StyledStr>) -> Command

pub fn before_long_help(self, help: impl IntoResettable<StyledStr>) -> Command

`version()`、`long_version()`

// 版本信息
pub fn version(self, ver: impl IntoResettable<Str>) -> Command

pub fn long_version(self, ver: impl IntoResettable<Str>) -> Command

`override_usage()`

// 重写clap生成的使用字符串以获取帮助和错误消息。
pub fn override_usage(self, usage: impl IntoResettable<StyledStr>) -> Command

`override_help()`

// 重写帮助文档
pub fn override_help(self, help: impl IntoResettable<StyledStr>) -> Command

`help_template()`

// 帮助文档模板
pub fn help_template(self, s: impl IntoResettable<StyledStr>) -> Command

`flatten_help()`

// 将子命令帮助展平为当前命令的帮助
// 这显示了当前命令的用法和帮助中的子命令摘要，类似于git stash --help显示有关推送、弹出等的信息。要查看更多信息，用户仍然可以将--help传递给各个子命令。
pub fn flatten_help(self, yes: bool) -> Command

`next_help_heading()`

// 为将来的参数设置默认部分标题。将用于任何没有Arg::help_heading调用的arg。
pub fn next_help_heading(self, heading: impl IntoResettable<Str>) -> Command

`next_display_order()`

// 更改为args分配未来显示订单的起始值。
pub fn next_display_order(self, disp_ord: impl IntoResettable<usize>) -> Command

`arg_required_else_help()`

// 如果不存在参数，则优雅地退出
pub fn arg_required_else_help(self, yes: bool) -> Command

`allow_missing_positional()`

// 允许实现两种样式的CLI，其中位置可以乱序使用。
pub fn allow_missing_positional(self, yes: bool) -> Command

第一个示例是CLI，其中倒数第二个位置参数是可选的，但最后一个位置参数是必需的。例如$ prog [optional] <required>其中允许以下两种用法之一：

prog [optional] <required>
prog <required>

特定子命令的设置

`short_flag()`、`long_flag()`

// 设置子命令标志的简短版本
// 允许使用子命令，就好像它是一个Arg::short
pub fn short_flag(self, short: impl IntoResettable<char>) -> Command

pub fn long_flag(self, long: impl Into<Str>) -> Command

`alias()`、`short_flag_alias()`、`long_flag_alias()`

// 设置此子命令的隐藏别名
pub fn alias(self, name: impl IntoResettable<Str>) -> Command

// 添加一个别名，用作“隐藏”短标志子命令
pub fn short_flag_alias(self, name: impl IntoResettable<char>) -> Command

// 添加一个别名，它用作“隐藏”的长标志子命令。
pub fn long_flag_alias(self, name: impl IntoResettable<Str>) -> Command

这允许通过原始名称或此给定别名访问子命令。这比创建多个隐藏子命令更有效、更容易，因为只需要检查此命令的存在，而不是所有别名变体。

注意：使用此方法定义的别名在帮助消息中隐藏。

注意：使用别名并检查ArgMatches结构中是否存在特定子命令时，只需要搜索原始名称而不是所有别名。

`aliases()`、`short_flag_aliases()`、`long_flag_aliases()`

pub fn aliases(self, names: impl IntoIterator<Item = impl Into<Str>>) -> Command

pub fn short_flag_aliases(
    self,
    names: impl IntoIterator<Item = char>,
) -> Command

pub fn long_flag_aliases(
    self,
    names: impl IntoIterator<Item = impl Into<Str>>,
) -> Command

`visible_alias()`、`visible_short_flag_alias()`、`visible_long_flag_alias()`

// 设置此子命令的可见别名。
pub fn visible_alias(self, name: impl IntoResettable<Str>) -> Command

pub fn visible_short_flag_alias(
    self,
    name: impl IntoResettable<char>,
) -> Command

pub fn visible_long_flag_alias(self, name: impl IntoResettable<Str>) -> Command

`visible_aliases()`、visible_short_flag_aliases()``visible_long_flag_aliases()

pub fn visible_aliases(
    self,
    names: impl IntoIterator<Item = impl Into<Str>>,
) -> Command

pub fn visible_short_flag_aliases(
    self,
    names: impl IntoIterator<Item = char>,
) -> Command

pub fn visible_long_flag_aliases(
    self,
    names: impl IntoIterator<Item = impl Into<Str>>,
) -> Command

`display_order()`

// 设置此子命令在帮助中的位置，排序
pub fn display_order(self, ord: impl IntoResettable<usize>) -> Command

值较低的子命令将首先显示在帮助消息中。具有相同显示顺序的将被排序。命令会根据添加到其父命令的顺序自动分配显示顺序。当添加的顺序命令与显示顺序不同时，覆盖这一点很有帮助，无论是一次性情况还是自动排序命令。

`hide()`

// 指定此子命令应从帮助消息中隐藏
pub fn hide(self, yes: bool) -> Command

`subcommand_required()`

// 如果运行时不存在子命令，请错误并优雅地退出。
pub fn subcommand_required(self, yes: bool) -> Command

`allow_external_subcommands()`

// 假设意外的位置参数是子命令
pub fn allow_external_subcommands(self, yes: bool) -> Command

注意：谨慎使用此设置，因为真正意外的参数（即不是外部子命令的参数）不会导致错误，而是被视为潜在的子命令。应该手动检查这种情况并适当地通知用户。

注意：当使用--转义时，内置子命令将被解析为外部子命令。

`external_subcommand_value_parser()`

// 指定如何解析外部子命令参数。
// 默认解析器用于OsString。这可用于将其切换到String或其他类型。
pub fn external_subcommand_value_parser(
    self,
    parser: impl IntoResettable<ValueParser>,
) -> Command

`args_conflicts_with_subcommands()`

// 指定使用参数可以防止使用子命令。
pub fn args_conflicts_with_subcommands(self, yes: bool) -> Command

默认情况下，clap允许子命令之间的参数，例如<cmd> [cmd_args] <subcmd> [subcmd_args] <subsubcmd> [subsubcmd_args]，此设置禁用该功能，并表示参数只能跟随最终子命令。例如，使用此设置只能进行以下调用：

<cmd> <subcmd> <subsubcmd> [subsubcmd_args]
<cmd> <subcmd> [subcmd_args]
<cmd> [cmd_args]

`subcommand_precedence_over_arg()`

// 防止子命令被用作参数值。
pub fn subcommand_precedence_over_arg(self, yes: bool) -> Command

默认情况下，如果接受多个值的选项后跟一个子命令，则该子命令将被解析为另一个值。此设置指示解析器在遇到子命令时停止，而不是贪婪地使用参数。

image-20250817100048425转存失败，建议直接上传图片文件

`subcommand_negates_reqs()`

// 允许子命令覆盖父命令的所有要求。
pub fn subcommand_negates_reqs(self, yes: bool) -> Command

例如，如果子命令或顶级应用程序具有仅在没有子命令时才需要的必需参数，则使用此设置将允许您将这些参数设置为 Arg::required(true)，并且只要用户使用有效的子命令，就不会收到错误。

注意：这默认为false（使用子命令不会否定要求）

let err = Command::new("myprog")
    .subcommand_negates_reqs(true)
    .arg(Arg::new("opt").required(true))
    .subcommand(Command::new("test"))
    .try_get_matches_from(vec![
        "myprog"
    ]); // 示例表明不使用必需的参数是错误的
assert!(err.is_err());
assert_eq!(err.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);

let noerr = Command::new("myprog")
    .subcommand_negates_reqs(true)
    .arg(Arg::new("opt").required(true))
    .subcommand(Command::new("test"))
    .try_get_matches_from(vec![
        "myprog", "test"
    ]); // 示例表明，如果使用了有效的子命令，则不使用必需的参数不再是错误的。
assert!(noerr.is_ok());

`multicall()`

pub fn multicall(self, yes: bool) -> Command

`subcommand_value_name()`

// 设置打印用法和帮助时用于子命令的值名称。
pub fn subcommand_value_name(
    self,
    value_name: impl IntoResettable<Str>,
) -> Command

默认值是：COMMAND

Command::new("myprog")
    .subcommand(Command::new("sub1"))
    .subcommand_value_name("THING")
    .print_help()

image-20250817100849063转存失败，建议直接上传图片文件

`subcommand_help_heading()`

// 设置打印用法和帮助时用于子命令的帮助标题。
pub fn subcommand_help_heading(
    self,
    heading: impl IntoResettable<Str>,
) -> Command

默认值：Commands

 Command::new("myprog")
     .subcommand(Command::new("sub1"))
     .subcommand_help_heading("Things")
     .print_help()

image-20250817100934308转存失败，建议直接上传图片文件

`ArgMatches`结构体

用于解析结果的容器。获取有关用户在运行时提供给程序的参数的信息。此结构的新实例通过使用Command::get_matches方法系列获得。

get_one()

 /**
  * 获取特定选项或位置参数的值。即在运行时获取附加值的参数。
  * - 如果使用了错误的类型，则返回错误。
  * - 如果选项不存在，则返回None。
  * panic: 如果参数定义和访问不匹配
  */
 pub fn get_one<T>(&self, id: &str) -> Option<&T>
 where
     T: Any + Clone + Send + Sync + 'static,
 pub fn try_get_one<T>(&self, id: &str) -> Result<Option<&T>, MatchesError>
 where
     T: Any + Clone + Send + Sync + 'static,
 
 /**
  * 获取特定选项或位置参数的值
  * panic: 如果参数的动作不是ArgAction::Count
  */
 pub fn get_count(&self, id: &str) -> u8
 
 /**
  * 获取特定ArgAction::SetTrue或ArgAction::SetFalse标志的值
  * panic: 如果参数的动作不是ArgAction::SetTrue或ArgAction::SetFalse
  */
 pub fn get_flag(&self, id: &str) -> bool
 
 /**
  * 迭代特定选项或位置参数的值。即在运行时接受多个值的参数。
  * - 如果使用了错误的类型，则返回错误。
  * - 如果选项不存在，则返回None。
  * panic: 如果参数定义和访问不匹配。
  */
 pub fn get_many<T>(&self, id: &str) -> Option<ValuesRef<'_, T>>
 where
     T: Any + Clone + Send + Sync + 'static,
 pub fn try_get_many<T>(
     &self,
     id: &str,
 ) -> Result<Option<ValuesRef<'_, T>>, MatchesError>
 where
     T: Any + Clone + Send + Sync + 'static,
 
 /**
  * 遍历传递给选项每次出现的值。
  * 每个项目本身就是一个迭代器，其中包含传递给选项的单个匹配项的参数。
  * - 如果该选项不支持多次出现，或者只有一次出现，则迭代器将仅包含单个项目。
  * - 如果选项不存在，则返回None。
  */
 pub fn get_occurrences<T>(&self, id: &str) -> Option<OccurrencesRef<'_, T>>
 where
     T: Any + Clone + Send + Sync + 'static,
 pub fn try_get_occurrences<T>(
     &self,
     id: &str,
 ) -> Result<Option<OccurrencesRef<'_, T>>, MatchesError>
 where
     T: Any + Clone + Send + Sync + 'static,
 
 /**
  * 迭代原始参数值。
  * 类Unix系统上的OsStr是任意一系列字节，无论它们是否包含有效的UTF-8。
  * 由于Rust中的字符串保证是有效的UTF-8，因此Unix系统上作为参数值的有效文件名可能包含无效的UTF-8。
  * - 如果选项不存在，则返回None。
  */
 pub fn get_raw(&self, id: &str) -> Option<RawValues<'_>>
 pub fn try_get_raw(
     &self,
     id: &str,
 ) -> Result<Option<RawValues<'_>>, MatchesError>
 
 /**
  * 迭代选项每次出现的原始值。类似于ArgMatches::get_occurrences但返回原始值。
  */
 pub fn get_raw_occurrences(&self, id: &str) -> Option<RawOccurrences<'_>>
 pub fn try_get_raw_occurrences(
     &self,
     id: &str,
 ) -> Result<Option<RawOccurrences<'_>>, MatchesError>
 
 /**
  * 返回特定选项或位置参数的值。即在运行时获取附加值的参数。
  * - 如果使用了错误的类型，则返回错误。不会删除任何项目。
  */
 pub fn remove_one<T>(&mut self, id: &str) -> Option<T>
 where
     T: Any + Clone + Send + Sync + 'static,
 pub fn try_remove_one<T>(&mut self, id: &str) -> Result<Option<T>, MatchesError>
 where
     T: Any + Clone + Send + Sync + 'static,
 
 // 返回特定选项或位置参数的值
 pub fn remove_many<T>(&mut self, id: &str) -> Option<Values<T>>
 where
     T: Any + Clone + Send + Sync + 'static,
 pub fn try_remove_many<T>(
     &mut self,
     id: &str,
 ) -> Result<Option<Values<T>>, MatchesError>
 where
     T: Any + Clone + Send + Sync + 'static,
 
 // 返回选项每次出现的值。
 pub fn remove_occurrences<T>(&mut self, id: &str) -> Option<Occurrences<T>>
 where
     T: Any + Clone + Send + Sync + 'static,
 pub fn try_remove_occurrences<T>(
     &mut self,
     id: &str,
 ) -> Result<Option<Occurrences<T>>, MatchesError>
 where
     T: Any + Clone + Send + Sync + 'static,
 
 // 检查参数或组id是否存在值
 // 注意：如果已设置default_value，这将始终返回true。ArgMatches::value_source可用于检查运行时是否存在值。
 pub fn contains_id(&self, id: &str) -> bool
 pub fn try_contains_id(&self, id: &str) -> Result<bool, MatchesError>
 
 // 通过ArgMatches迭代Arg和ArgGroup::ids
 pub fn ids(&self) -> IdsRef<'_>
 
 // 检查命令行上是否存在任何Args
 pub fn args_present(&self) -> bool
 
 // 报告参数值来自哪里
 pub fn value_source(&self, id: &str) -> Option<ValueSource>
 
 // 出现第一个参数的索引
 pub fn index_of(&self, id: &str) -> Option<usize>
 pub fn indices_of(&self, id: &str) -> Option<Indices<'_>>
 
 // 当前子命令的名称和ArgMatches，子命令值放在子ArgMatches中
 pub fn subcommand(&self) -> Option<(&str, &ArgMatches)>
 
 // 返回当前子命令的名称和ArgMatches。
 pub fn remove_subcommand(&mut self) -> Option<(String, ArgMatches)>
 
 // 当前子命令的ArgMatches
 pub fn subcommand_matches(&self, name: &str) -> Option<&ArgMatches>
 
 // 当前子命令的名称
 pub fn subcommand_name(&self) -> Option<&str>
 
 // 清除给定id的值
 pub fn try_clear_id(&mut self, id: &str) -> Result<bool, MatchesError>

`ValueParser`结构体

解析并验证参数用Arg::value_parser指定的值。ValueParser定义如何将原始参数值转换为经过验证和类型化的值以在应用程序中使用。

value_parser!宏用于自动选择给定类型的实现
ValueParser::new可以使用的额外类型TypedValueParser

 /**
  * 参数值的自定义解析器
  * 预先存在的TyedValueParser实现包括：
  * - Fn（&str）->结果<T， E>
  * - 用于静态枚举值的EnumValueParser和PossibleValuesParser
  * - 用于替代bool实现的BoolishValueParser和FalseyValueParser
  * - RangedI64ValueParser和RangedU64ValueParser
  * - NonEmptyStringValueParser
  */
 pub fn new<P>(other: P) -> ValueParser
 where
     P: TypedValueParser,
 
 // 参数值的bool解析器
 pub const fn bool() -> ValueParser
 
 // 字符串参数值解析器
 pub const fn string() -> ValueParser
 
 // OsString类型参数值解析器
 pub const fn os_string() -> ValueParser
 
 // PathBuf类型
 pub const fn path_buf() -> ValueParser
 
 // 描述AnyValue的内容
 pub fn type_id(&self) -> AnyValueId
 
 // 反映枚举值属性
 pub fn possible_values(
     &self,
 ) -> Option<Box<dyn Iterator<Item = PossibleValue> + '_>>

`value_parser`宏

 #[macro_export]
 macro_rules! value_parser {
     ($name:ty) => {{
         use $crate::builder::impl_prelude::*;
         let auto = $crate::builder::_infer_ValueParser_for::<$name>::new();
         (&&&&&&auto).value_parser()
     }};
 }

从预期类型中选择ValueParser实现，支持的类型：

ValueParserFactory类型，包括
- 原生类型：bool、String、OsString、PathBuf
- 数字类型范围：u8、i8、u16、i16、u32、i32、u64、i64
ValueEnum类型
From<OsString>类型和From<&OsStr>类型
From<String>类型和From<&str>类型
FromStr类型，包括usize、isize

 let mut cmd = clap::Command::new("raw")
     .arg(
         clap::Arg::new("output")
             .value_parser(clap::value_parser!(PathBuf))
             .required(true)
     );
 
 let m = cmd.try_get_matches_from_mut(["cmd", "file.txt"]).unwrap();
 let port: &PathBuf = m.get_one("output")
     .expect("required");
 assert_eq!(port, Path::new("file.txt"));

`command`宏

 #[cfg(feature = "cargo")]
 #[macro_export]
 macro_rules! command {
     () => {{
         $crate::command!($crate::crate_name!())
     }};
     ($name:expr) => {{
         let mut cmd = $crate::Command::new($name).version($crate::crate_version!());
 
         let author = $crate::crate_authors!();
         if !author.is_empty() {
             cmd = cmd.author(author)
         }
 
         let about = $crate::crate_description!();
         if !about.is_empty() {
             cmd = cmd.about(about)
         }
         cmd
     }};
 }

允许您在编译时从Cargo.toml构建Command实例。

注意：更改Cargo.toml中的值不会自动触发重新构建，因此在重新编译之前不会更改生成的输出。

在某些情况下，当Cargo.toml被更改时，可以通过在src/main.rs文件include_str!("../Cargo.toml")中包含它来“欺骗”编译器触发重建；

 let m = command!().get_matches();

Command结构体的关联函数都可以在类属性宏#[]中指定一个属性

`arg`宏

 #[macro_export]
 macro_rules! arg {
     ( -$($tail:tt)+ ) => {{
         let arg = $crate::Arg::default();
         let arg = $crate::arg_impl! {
             @arg (arg) -$($tail)+
         };
         debug_assert_ne!(arg.get_id(), "", "Without a value or long flag, the `name:` prefix is required");
         arg
     }};
     ( $name:ident: $($tail:tt)+ ) => {{
         let arg = $crate::Arg::new($crate::arg_impl! { @string $name });
         let arg = $crate::arg_impl! {
             @arg (arg) $($tail)+
         };
         arg
     }};
     ( $name:literal: $($tail:tt)+ ) => {{
         let arg = $crate::Arg::new($crate::arg_impl! { @string $name });
         let arg = $crate::arg_impl! {
             @arg (arg) $($tail)+
         };
         arg
     }};
     ( $($tail:tt)+ ) => {{
         let arg = $crate::Arg::default();
         let arg = $crate::arg_impl! {
             @arg (arg) $($tail)+
         };
         debug_assert_ne!(arg.get_id(), "", "Without a value or long flag, the `name:` prefix is required");
         arg
     }};
 }

从使用字符串创建一个Arg。允许为Arg创建基本设置。

注意：并非所有设置都可以使用字符串方法设置。某些属性只能通过构建器模式获得。

用法字符串通常遵循以下形式：

[explicit name] [short] [long] [value names] [...] [help string]

explicit name：可以是裸词或字符串，后跟:，如name:或"name":。

注意：这是一个可选字段，如果省略，参数将使用以下优先级顺序使用其中一个附加字段作为名称：

Explicit Name
Long
Value Name

short：短标志是一个-后跟一个裸字符或带引号的字符，如-f或-'f'。

long：长标志是一个——后跟一个裸词或一个字符串，例如--foo或--"foo"。

注意：不支持长名称中的破折号（例如--foo-bar），需要引用（例如--"foo-bar"）。

value names：这是通过在以下之间放置裸词来设置的：

[]类似于[FOO]
- 位置参数：可选
- 命名参数：可选值
<>类似于<FOO>：必填

...：（三个连续的点/周期）指定此参数可以多次出现（不要与每次出现的多个值混淆）。

help string：帮助字符串表示在一对双引号""之间，并且可以包含任何字符。

let cmd = Command::new("prog")
    .args(&[
        arg!(--config <FILE> "a required file for the configuration and no short"),
        arg!(-d --debug ... "turns on debugging information and allows multiples"),
        arg!([input] "an optional input file to use")
    ]);

let m = cmd.try_get_matches_from(["prog", "--config", "file.toml"]).unwrap();
assert_eq!(m.get_one::<String>("config").unwrap(), "file.toml");
assert_eq!(*m.get_one::<u8>("debug").unwrap(), 0);
assert_eq!(m.get_one::<String>("input"), None);

Arg结构体的关联函数都可以在类属性宏#[]中指定一个属性

`ArgAction`枚举

// 解析时遇到参数时的行为
#[non_exhaustive]
pub enum ArgAction {
    /**
     * 将关联的值存储在ArgMatches中，只能出现一次
     * 注意：如果之前已经看到参数，它将导致ArgumentConflict，除非设置了Command::args_override_self(true)
     */
    Set,
    /**
     * 将关联值存储在ArgMatches中，可以出现多次
     */
    Append,
    /**
     * 就像在命令行上遇到“true”一样，不允许存在值
     * 如果没有设置默认值，将被设置为false
     */
    SetTrue,
    /**
     * 如果没有设置默认值，将被设置为true
     */
    SetFalse,
    /**
     * 从0开始递增计数器，不允许存在值
     * 如果没有设置默认值，将被设置为0
     */
    Count,
    /**
     * 显示帮助信息
     */
    Help,
    HelpShort,
    HelpLong,
    /**
     * 显示版本信息
     */
    Version,
}

`Parser` trait

将命令行参数解析为Self。

用于创建clap Command实例、进行解析并将生成的ArgMatches转换回用户结构的具体实例的主要一站式特征。

这个特性主要是FromArgMatches+CommandFactory使用这两个基本特性来构建两个基本函数解析，使用std::env::args_os迭代器，和parse_from允许消费者提供迭代器（以及每个错误的选项）。

注意：派生需要derive特征标志

// 解析来自std::env::args_os()，在错误时退出
fn parse() -> Self

// 在发生错误时返回Result类型
fn try_parse() -> Result<Self, Error>

// 解析来自迭代器的数据
fn parse_from<I, T>(itr: I) -> Self
where
    I: IntoIterator<Item = T>,
    T: Into<OsString> + Clone,

fn try_parse_from<I, T>(itr: I) -> Result<Self, Error>
where
    I: IntoIterator<Item = T>,
    T: Into<OsString> + Clone,

Rust库clap：命令行工具

clap 命令行解析

导入依赖

Arg结构体方法列表

基本方法

new()

id()

short()

long()

alias()、short_alias()

aliases()、short_aliases()

visible_alias()、visible_short_alias()

visible_aliases()、visible_short_aliases()

index()

trailing_var_arg()

last()

required()

requires()

exclusive()

global()

add()

Value 处理器

action()

value_parser()

num_args()

value_name()、value_names()

value_hint()

ignore_case()

allow_hyphen_values()

allow_negative_numbers()

require_equals()

value_delimiter()

value_terminator()

raw()

default_value()、default_values()

default_missing_value()、default_missing_value_os()、default_missing_values()、default_missing_values_os()

env()

高级参数

group()、groups()

default_value_if()、default_value_ifs()

required_unless_present()、required_unless_present_all()、required_unless_present_any()

required_if_eq()、required_if_eq_any()、required_if_eq_all()

requires_if()、requires_ifs()

conflicts_with()、conflicts_with_all()

overrides_with_all()

Command结构体方法列表

基本方法

new()

arg()、args()、mut_arg()、mut_args()

group()、groups()、mut_group()

subcommand()、subcommands()、mut_subcommand()、mut_subcommands()

defer()

error()

get_matches()、get_matches_mut()、try_get_matches()

get_matches_from()、try_get_matches_from()、try_get_matches_from_mut()

print_help()、print_long_help()

render_help()、render_long_help()

render_version()、render_long_version()

render_usage()

add()

应用程序范围设置

no_binary_name()

ignore_errors()

args_override_self()

color()

styles()

term_width()、max_term_width()

disable_version_flag()、disable_help_flag()

propagate_version()

next_line_help()

disable_help_subcommand()

disable_colored_help()

help_expected()

hide_possible_values()

infer_long_args()

infer_subcommands()

特定命令的设置

name()

bin_name()

display_name()

`Arg`结构体方法列表

`new()`

`id()`

`short()`

`long()`

`alias()`、`short_alias()`

`aliases()`、`short_aliases()`

`visible_alias()`、`visible_short_alias()`

`visible_aliases()`、`visible_short_aliases()`

`index()`

`trailing_var_arg()`

`last()`

`required()`

`requires()`

`exclusive()`

`global()`

`add()`

`action()`

`value_parser()`

`num_args()`

`value_name()`、`value_names()`

`value_hint()`

`ignore_case()`

`allow_hyphen_values()`

`allow_negative_numbers()`

`require_equals()`

`value_delimiter()`

`value_terminator()`

`raw()`

`default_value()`、`default_values()`

`default_missing_value()`、`default_missing_value_os()`、`default_missing_values()`、`default_missing_values_os()`

`env()`

`group()`、`groups()`

`default_value_if()`、`default_value_ifs()`

`required_unless_present()`、`required_unless_present_all()`、`required_unless_present_any()`

`required_if_eq()`、`required_if_eq_any()`、`required_if_eq_all()`

`requires_if()`、`requires_ifs()`

`conflicts_with()`、`conflicts_with_all()`

`overrides_with_all()`

`Command`结构体方法列表

`new()`

`arg()`、`args()`、`mut_arg()`、`mut_args()`

`group()`、`groups()`、`mut_group()`

`subcommand()`、`subcommands()`、`mut_subcommand()`、`mut_subcommands()`

`defer()`

`error()`

`get_matches()`、`get_matches_mut()`、`try_get_matches()`

`get_matches_from()`、`try_get_matches_from()`、`try_get_matches_from_mut()`

`print_help()`、`print_long_help()`

`render_help()`、`render_long_help()`

`render_version()`、`render_long_version()`

`render_usage()`

`add()`

`no_binary_name()`

`ignore_errors()`

`args_override_self()`

`color()`

`styles()`

`term_width()、max_term_width()`

`disable_version_flag()`、`disable_help_flag()`

`propagate_version()`

`next_line_help()`

`disable_help_subcommand()`

`disable_colored_help()`

`help_expected()`

`hide_possible_values()`

`infer_long_args()`

`infer_subcommands()`

`name()`

`bin_name()`

`display_name()`

`author()`

`about()`、`long_about()`

`after_help()`、`after_long_help()`

`before_help()`、`before_long_help()`

`version()`、`long_version()`

`override_usage()`

`override_help()`

`help_template()`

`flatten_help()`