fn main() {
    let cmd = clap::Command::new("cargo")
        .bin_name("cargo")
        .subcommand_required(true)
        .subcommand(
            clap::command!("example").arg(
                clap::arg!(--"manifest-path" <PATH>)
                    .value_parser(clap::value_parser!(std::path::PathBuf)),),
        );

    // 从 os:env::args() 获得输入
    let matches = cmd.get_matches();

    // 匹配子命令
    let matches = match matches.subcommand() {
        Some(("example", matches)) => matches,
        _ => unreachable!("clap should ensure we don't get here"),
    };

    // 获得子命令的选项参数
    let manifest_path = matches.get_one::<std::path::PathBuf>("manifest-path");
    println!("{manifest_path:?}");
}

use clap::Parser;

#[derive(Parser)]
#[command(name = "cargo")]
#[command(bin_name = "cargo")]
enum CargoCli {
    ExampleDerive(ExampleDeriveArgs),
}

#[derive(clap::Args)]
#[command(version, about, long_about = None)]
struct ExampleDeriveArgs {
    #[arg(long)]
    manifest_path: Option<std::path::PathBuf>,
}

fn main() {
    let CargoCli::ExampleDerive(args) = CargoCli::parse();
    println!("{:?}", args.manifest_path);
}

// Register a type with value_parser!
pub trait ValueParserFactory {
    // 关联类型 Parser 一般是实现 TypedValueParser 的自定义类型；
    type Parser;

    // Required method
    fn value_parser() -> Self::Parser;
}

// clap 内置注册的类型
impl ValueParserFactory for bool
impl ValueParserFactory for i8
impl ValueParserFactory for i16
impl ValueParserFactory for i32
impl ValueParserFactory for i64
impl ValueParserFactory for u8
impl ValueParserFactory for u16
impl ValueParserFactory for u32
impl ValueParserFactory for u64
impl ValueParserFactory for Box<str>
impl ValueParserFactory for Box<OsStr>
impl ValueParserFactory for Box<Path>
impl ValueParserFactory for String
impl ValueParserFactory for OsString
impl ValueParserFactory for PathBuf

// Parser 需要实现 TypedValueParser trait
impl<T> ValueParserFactory for Box<T>
    where T: ValueParserFactory + Send + Sync + Clone, <T as ValueParserFactory>::Parser: TypedValueParser<Value = T>
impl<T> ValueParserFactory for Arc<T>
    where T: ValueParserFactory + Send + Sync + Clone, <T as ValueParserFactory>::Parser: TypedValueParser<Value = T>
impl<T> ValueParserFactory for Wrapping<T>
    where T: ValueParserFactory + Send + Sync + Clone, <T as ValueParserFactory>::Parser: TypedValueParser<Value = T>,

// Built-in types
let parser = clap::value_parser!(String);
assert_eq!(format!("{parser:?}"), "ValueParser::string");

let parser = clap::value_parser!(std::ffi::OsString);
assert_eq!(format!("{parser:?}"), "ValueParser::os_string");

let parser = clap::value_parser!(std::path::PathBuf);
assert_eq!(format!("{parser:?}"), "ValueParser::path_buf");

clap::value_parser!(u16).range(3000..);
clap::value_parser!(u64).range(3000..);

// FromStr types
let parser = clap::value_parser!(usize);
assert_eq!(format!("{parser:?}"), "_AnonymousValueParser(ValueParser::other(usize))");

// ValueEnum types
pub enum ColorChoice {
    Auto,
    Always,
    Never,
}
clap::value_parser!(ColorChoice);

pub trait TypedValueParser: Clone + Send + Sync + 'static {
    type Value: Send + Sync + Clone;

    // Required method
    // 从传入的 arg/value 来解析出 type Value 类型值;
    fn parse_ref( &self, cmd: &Command, arg: Option<&Arg>, value: &OsStr ) -> Result<Self::Value, Error>;
    //...
}

// clap::builder module 提供了如下实现类型：
impl TypedValueParser for BoolValueParser // 返回 bool
impl TypedValueParser for BoolishValueParser // 类似于 bool 值
impl TypedValueParser for FalseyValueParser
impl TypedValueParser for NonEmptyStringValueParser // 返回非空 String
impl TypedValueParser for OsStringValueParser // 返回 OsString
impl TypedValueParser for PathBufValueParser // 返回 PathBuf
impl TypedValueParser for PossibleValuesParser // 可选值列表
impl TypedValueParser for StringValueParser // 返回 String
impl TypedValueParser for UnknownArgumentValueParser
impl<E> TypedValueParser for EnumValueParser<E> where E: ValueEnum + Clone + Send + Sync + 'static // 枚举值

//  Fn(&str) -> Result<T,E> 闭包也实现了 TypedValueParser
impl<F, T, E> TypedValueParser for F
where
    F: Fn(&str) -> Result<T, E> + Clone + Send + Sync + 'static,
    E: Into<Box<dyn Error + Sync + Send>>,
    T: Send + Sync + Clone

impl<P, F, T> TypedValueParser for MapValueParser<P, F>
where
    P: TypedValueParser,
    <P as TypedValueParser>::Value: Send + Sync + Clone,
    F: Fn(<P as TypedValueParser>::Value) -> T + Clone + Send + Sync + 'static,
    T: Send + Sync + Clone

impl<P, F, T, E> TypedValueParser for TryMapValueParser<P, F>
where
    P: TypedValueParser,
    <P as TypedValueParser>::Value: Send + Sync + Clone,
    F: Fn(<P as TypedValueParser>::Value) -> Result<T, E> + Clone + Send + Sync + 'static,
    T: Send + Sync + Clone,
    E: Into<Box<dyn Error + Sync + Send>>

// RangedI64ValueParser 和 RangedU64ValueParser 用于定义一个 range 范围。
impl<T> TypedValueParser for RangedI64ValueParser<T>
where
    T: TryFrom<i64> + Clone + Send + Sync + 'static,
    <T as TryFrom<i64>>::Error: Send + Sync + 'static + Error + ToString

impl<T> TypedValueParser for RangedU64ValueParser<T>
where
    T: TryFrom<u64> + Clone + Send + Sync + 'static,
    <T as TryFrom<u64>>::Error: Send + Sync + 'static + Error + ToString,

// 使用预定义的 ValueParser
let mut cmd = clap::Command::new("raw")
    .arg(
        clap::Arg::new("append")
            // 使用实现 TypedValueParser trait 的对象值作为参数
            .value_parser(clap::builder::NonEmptyStringValueParser::new())
            .required(true)
    );
let m = cmd.try_get_matches_from_mut(["cmd", "true"]).unwrap();
let port: &String = m.get_one("append").expect("required");
assert_eq!(port, "true");

// 使用宏来创建 TypedValueParser
let mut cmd = clap::Command::new("raw")
    .arg(
        clap::Arg::new("port")
            .long("port")
            .value_parser(clap::value_parser!(u16).range(3000..))
            .action(clap::ArgAction::Set)
            .required(true)
    );

let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap();
let port: u16 = *m.get_one("port").expect("required");
assert_eq!(port, 3001);

// 使用 Fn 闭包实现 TypedValueParser，返回的 Ok 值类型需要和 arg 字段类型值 T/Option<T>/Vec<T>/Option<Vec<T>> 中的 T 一致。
fn bytes_from_str(src: &str) -> Result<Bytes, Infallible> {
    Ok(Bytes::from(src.to_string()))
}

#[derive(Subcommand, Debug)]
enum Command {
    Ping {
        // value_parser 的值为实现 TypedValueParser 的类型。
        #[arg(value_parser = bytes_from_str)]
        msg: Option<Bytes>,
    }
}

#[derive(Copy, Clone, Debug)]
pub struct Custom(u32);

// Custom 实现 ValueParserFactory 后才能作为 value_parser!() 宏的参数
impl clap::builder::ValueParserFactory for Custom {
    type Parser = CustomValueParser; // Parser 需要实现 TypedValueParser

    fn value_parser() -> Self::Parser {
        CustomValueParser
    }
}

#[derive(Clone, Debug)]
pub struct CustomValueParser;

impl clap::builder::TypedValueParser for CustomValueParser {
    type Value = Custom;

    fn parse_ref(&self, cmd: &clap::Command, arg: Option<&clap::Arg>, value: &std::ffi::OsStr, ) -> Result<Self::Value, clap::Error> {
        // 使用 clap::value_parser!() 宏创建的 CustomValueParser 来解析参数。
        let inner = clap::value_parser!(u32);
        let val = inner.parse_ref(cmd, arg, value)?;
        Ok(Custom(val))
    }
}

// 使用自定义 ValueParser 类型
let parser: CustomValueParser = clap::value_parser!(Custom);

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

// 任何能 `Into<ValueParser>` 的类型值都可以作为 `Arg::value_parser()` 的参数：
impl<I> IntoResettable<ValueParser> for I where I: Into<ValueParser>

impl IntoResettable<ValueParser> for Option<ValueParser>

impl<I> IntoResettable<ValueRange> for I where I: Into<ValueRange>

// 从实现 TypedValueParser 的自定义类型值创建 ValueParser
pub fn new<P>(other: P) -> ValueParser where P: TypedValueParser

// 从 [P; C] 和 Vec<P> 转换为 ValueParser, 其中 P 需要实现 Into<PossibleValue>，一般为 String/&str 等；
impl<P, const C: usize> From<[P; C]> for ValueParser where P: Into<PossibleValue>
impl<P> From<Vec<P>> for ValueParser where P: Into<PossibleValue>

// 从 TypedValueParser 转换为 ValueParser
impl<P> From<P> for ValueParser where P: TypedValueParser + Send + Sync + 'static,

// 从 RangeXX 转换为 ValueParser
impl From<Range<i64>> for ValueParser
impl From<RangeFrom<i64>> for ValueParser
impl From<RangeFull> for ValueParser
impl From<RangeInclusive<i64>> for ValueParser
impl From<RangeTo<i64>> for ValueParser
impl From<RangeToInclusive<i64>> for ValueParser

// 从预定义的关联函数创建 ValueParser
pub const fn bool() -> ValueParser
pub const fn string() -> ValueParser
pub const fn os_string() -> ValueParser
pub const fn path_buf() -> ValueParser

pub struct PossibleValue { /* private fields */ }

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

// 为可生成 str 的任意对象转换为 PossibleValue
impl<S> From<S> for PossibleValue where S: Into<Str>

impl PossibleValuesParser
    pub fn new(values: impl Into<PossibleValuesParser>) -> PossibleValuesParser

// 为可迭代对象，如 &[&str], Vec<&str>, [&str; N] 等转换为 PossibleValuesParser
impl<I, T> From<I> for PossibleValuesParser where I: IntoIterator<Item = T>, T: Into<PossibleValue>

impl TypedValueParser for PossibleValuesParser

// 示例
let mut cmd = clap::Command::new("raw")
    .arg(
        clap::Arg::new("color")
            // 必须都是字符串列表
            //.value_parser(vec!["always", "auto", "never"]))
            //.value_parser(["always", "auto", "never"])
            .value_parser(clap::builder::PossibleValuesParser::new(["always", "auto", "never"]))
            .required(true)
        );

let m = cmd.try_get_matches_from_mut(["cmd", "always"]).unwrap();
let port: &String = m.get_one("color").expect("required");
assert_eq!(port, "always");

use std::path::PathBuf;
use clap::{arg, command, value_parser, ArgAction, Command};

// 手动设置 Command 信息
let m = Command::new("My Program")
    .author("Me, [email protected]")
    .version("1.0.2")
    .about("Explains in brief what the program does")
    .arg(
        Arg::new("in_file")
    )
    .after_help("Longer explanation to appear after the options when displaying the help information from --help or -h")
    .get_matches();

// 使用 crate_xx!() 宏来设置 Command 信息
let m = Command::new(crate_name!())
    .author(crate_authors!("\n"))
    .version(crate_version!())
    .about(crate_description!())
    .get_matches();

// command!() 从 Cargo.toml 中读取和设置 Command 的 name/version/authors/description 信息。
let matches = command!()
    // 使用 arg!() 宏来快捷创建 Arg。
    // name 或 config 为 arg id，后续用来匹配查找参数值
    .arg(arg!([name] "Optional name to operate on"))
    .arg(arg!(-c --config <FILE> "Sets a custom config file" )
        .required(false) // 可选参数（默认是必选的）
        .value_parser(value_parser!(PathBuf))) // 设置参数解析类型（默认为 String）
    .arg(arg!( -d --debug ... "Turn debugging information on" ))
    .subcommand(
        // new 的参数为 command id，后续用来匹配 command
        Command::new("test")
            .about("does testing things")
            .arg(arg!(-l --list "lists test values").action(ArgAction::SetTrue)))
    .get_matches();

if let Some(name) = matches.get_one::<String>("name") {
    println!("Value for name: {name}");
}
if let Some(config_path) = matches.get_one::<PathBuf>("config") {
    println!("Value for config: {}", config_path.display());
}
if let Some(matches) = matches.subcommand_matches("test") {
    // "$ myapp test" was run
    if matches.get_flag("list") {
        // "$ myapp test -l" was run
        println!("Printing testing lists...");
    } else {
        println!("Not printing testing lists...");
    }
}

let m = cmd.clone().get_matches_from(vec!["prog", "-F", "in-file", "out-file"]);

// 使用 arg!() 来创建 Arg：
// [name]: 位置参数 name，name 作为 arg id，外围的 [] 表示时可选的。
let input = arg!([name] "Optional name to operate on").required(false)
// -i： short flag
// --input： long flag，同时 input 作为 arg id
// <FILE>: value_name，在现实参数的 help 信息时使用
// "Provides an input file to the program": 帮助信息
let input = arg!(-i --input <FILE> "Provides an input file to the program");

let cmd = Command::new().arg(
    Arg::new("in_file")
)

let matches = command!()
    // 位置参数，id 为 name
    .arg(arg!([name] "Optional name to operate on").required(false))
    // flag 参数，id 为 list
    .arg(arg!(-l --list "lists test values").action(ArgAction::SetTrue))

// 为 Command 使用 args!() 来创建 Arg 对象，使用 value_parser!() 来指定解析后的值类型；
let matches = command!()
    .arg(
        arg!([PORT])
            .value_parser(value_parser!(u16)) // Rust 内置类型
            .default_value("2020"),
    )
    .get_matches();


let cfg = Arg::new("config") // 未调用 short 或 long 方法，所以为位置参数
        .action(ArgAction::Set)
        .value_name("FILE")
        // RangeFull 实现了 ValueParser
        .value_parser(2..5);

let cfg = Arg::new("config")
          .short('c')
          .long("config")
          .action(ArgAction::Set)
          .value_name("FILE") // 在显示参数的帮助信息时使用
          .help("Provides a config file to myprog");

use clap::{arg, command, ArgAction};

fn main() {
    let matches = command!()
        .next_line_help(true)
        // 未指定 ValueParser 时默认为 StringValueParser
        .arg(arg!(--two <VALUE>).required(true).action(ArgAction::Set))
        .arg(arg!(--one <VALUE>).required(true).action(ArgAction::Set))
        .get_matches();

    println!( "two: {:?}", matches.get_one::<String>("two").expect("required") );
    println!( "one: {:?}", matches.get_one::<String>("one").expect("required") );
}

let mut cmd = clap::Command::new("raw")
    .arg(
        clap::Arg::new("color")
            .long("color")
            // [&str; 3] 实现了 ValueParser
            .value_parser(["always", "auto", "never"])
            .default_value("auto")
    );

let mut cmd = clap::Command::new("raw")
    .arg(
        clap::Arg::new("output")
            .value_parser(clap::value_parser!(PathBuf))
            .required(true)
    );

let cfg = Arg::new("config")
        .action(ArgAction::Set)
        .value_name("FILE")
        // [PossibleValue; 3] 实现了 ValueParser
        .value_parser([
            PossibleValue::new("fast"),
            PossibleValue::new("slow").help("slower than fast"),
            PossibleValue::new("secret speed").hide(true)
        ]);

// derive 风格：
#[derive(Parser, Debug)]
struct RemoveArgs {
    // flag 参数
    #[arg(short, long)]
    force: bool,

    // 未加 #[arg]，所以为位置参数。
    // name 是可选的位置参数，未指定时为空 Vec
    name: Vec<String>,
}

// builder 风格
let cmd = Command::new("mycmd")
    .arg(
        Arg::new("flag")
            .long("flag") // 调用 short/long 方法后则表明为 flag 参数
            .action(clap::ArgAction::Append)
    );

let matches = cmd.try_get_matches_from(["mycmd", "--flag", "value", "--flag" "value2"]).unwrap();
assert!(matches.contains_id("flag"));
assert_eq!(
    matches.get_many::<String>("flag").unwrap_or_default().map(|v| v.as_str()).collect::<Vec<_>>(),
    vec!["value", "value2"]
);

// num_args 指定参数值的个数
// 这里表示 -F 有两个参数值，如 -F in-file out-file
let cmd = Command::new("prog")
    .arg(Arg::new("file")
        .action(ArgAction::Set)
        .num_args(2) // 2 个参数值，也可以指定 Range，如 2.. 表示至少 2 个位置参数
        .short('F'));
let m = cmd.clone().get_matches_from(vec!["prog", "-F", "in-file", "out-file"]);
assert_eq!(
    m.get_many::<String>("file").unwrap_or_default().map(|v| v.as_str()).collect::<Vec<_>>(),
    vec!["in-file", "out-file"]
);
let res = cmd.clone().try_get_matches_from(vec!["prog", "-F", "file1"]);
assert_eq!(res.unwrap_err().kind(), ErrorKind::WrongNumberOfValues);

let mut cmd = clap::Command::new("raw")
    .arg(
        clap::Arg::new("append")
            .value_parser(clap::builder::FalseyValueParser::new())
            .required(false)
    );

// 使用 Fn 闭包来实现 TypedValueParser:
// Result 的 Ok 值类型需要和 arg 字段类型值 T/Option<T>/Vec<T>/Option<Vec<T>> 中的 T 一致。
fn bytes_from_str(src: &str) -> Result<Bytes, Infallible> {
    Ok(Bytes::from(src.to_string()))
}

#[derive(Subcommand, Debug)]
enum Command {
    Ping {
        // 手动指定实现 TypedValueParser 的类型。
        #[clap(value_parser = bytes_from_str)]
        msg: Option<Bytes>,
    }
}

use std::collections::BTreeMap;

use clap::{command, value_parser, Arg, ArgAction, ArgGroup, ArgMatches, Command};

fn main() {
    let matches = cli().get_matches();
    let values = Value::from_matches(&matches);
    println!("{values:#?}");
}

fn cli() -> Command {
    command!()
        .group(ArgGroup::new("tests").multiple(true))
        .next_help_heading("TESTS")
        .args([
            position_sensitive_flag(Arg::new("empty"))
                .long("empty")
                .action(ArgAction::Append)
                .help("File is empty and is either a regular file or a directory")
                .group("tests"),
            Arg::new("name")
                .long("name")
                .action(ArgAction::Append)
                .help("Base of file name (the path with the leading directories removed) matches shell pattern pattern")
                .group("tests")
        ])
        .group(ArgGroup::new("operators").multiple(true))
        .next_help_heading("OPERATORS")
        .args([
            position_sensitive_flag(Arg::new("or"))
                .short('o')
                .long("or")
                .action(ArgAction::Append)
                .help("expr2 is not evaluate if exp1 is true")
                .group("operators"),
            position_sensitive_flag(Arg::new("and"))
                .short('a')
                .long("and")
                .action(ArgAction::Append)
                .help("Same as `expr1 expr1`")
                .group("operators"),
        ])
}

fn position_sensitive_flag(arg: Arg) -> Arg {
    // Flags don't track the position of each occurrence, so we need to emulate flags with
    // value-less options to get the same result
    arg.num_args(0)
        .value_parser(value_parser!(bool))
        .default_missing_value("true")
        .default_value("false")
}

#[derive(Clone, PartialEq, Eq, Hash, Debug)]
pub enum Value {
    Bool(bool),
    String(String),
}

impl Value {
    pub fn from_matches(matches: &ArgMatches) -> Vec<(clap::Id, Self)> {
        let mut values = BTreeMap::new();
        for id in matches.ids() {
            if matches.try_get_many::<clap::Id>(id.as_str()).is_ok() {
                // ignore groups
                continue;
            }
            let value_source = matches
                .value_source(id.as_str())
                .expect("id came from matches");
            if value_source != clap::parser::ValueSource::CommandLine {
                // Any other source just gets tacked on at the end (like default values)
                continue;
            }
            if Self::extract::<String>(matches, id, &mut values) {
                continue;
            }
            if Self::extract::<bool>(matches, id, &mut values) {
                continue;
            }
            unimplemented!("unknown type for {id}: {matches:?}");
        }
        values.into_values().collect::<Vec<_>>()
    }

    fn extract<T: Clone + Into<Value> + Send + Sync + 'static>(
        matches: &ArgMatches,
        id: &clap::Id,
        output: &mut BTreeMap<usize, (clap::Id, Self)>,
    ) -> bool {
        match matches.try_get_many::<T>(id.as_str()) {
            Ok(Some(values)) => {
                for (value, index) in values.zip(
                    matches
                        .indices_of(id.as_str())
                        .expect("id came from matches"),
                ) {
                    output.insert(index, (id.clone(), value.clone().into()));
                }
                true
            }
            Ok(None) => {
                unreachable!("`ids` only reports what is present")
            }
            Err(clap::parser::MatchesError::UnknownArgument { .. }) => {
                unreachable!("id came from matches")
            }
            Err(clap::parser::MatchesError::Downcast { .. }) => false,
            Err(_) => {
                unreachable!("id came from matches")
            }
        }
    }
}

impl From<String> for Value {
    fn from(other: String) -> Self {
        Self::String(other)
    }
}

impl From<bool> for Value {
    fn from(other: bool) -> Self {
        Self::Bool(other)
    }
}

// $ find --help
// A simple to use, efficient, and full-featured Command Line Argument Parser

// Usage: find[EXE] [OPTIONS]

// Options:
//   -h, --help     Print help
//   -V, --version  Print version

// TESTS:
//       --empty        File is empty and is either a regular file or a directory
//       --name <name>  Base of file name (the path with the leading directories removed) matches shell
//                      pattern pattern

// OPERATORS:
//   -o, --or   expr2 is not evaluate if exp1 is true
//   -a, --and  Same as `expr1 expr1`

pub trait Parser: FromArgMatches + CommandFactory + Sized {
    // Provided methods
    fn parse() -> Self
    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

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

#[command(author = "Author Name", version, about)]
/// A Very simple Package Hunter
struct Arguments {...}

// 等效于

#[derive(Parser, Debug)]
#[command(author = "Author Name", version, about="A Very simple Package Hunter")]
struct Arguments{...}

use clap::Parser;

#[derive(Parser)]
// auth/version/about 等均为 Command builder 方法
// 1. 如果未赋值，则默认 Cargo.toml 获取缺省值。
#[command(author, version, about, long_about = None)]
// 2. 或者指定缺省值
#[command(name = "MyApp")]
// 可以调用 Command builder 的各种方法
#[command(next_line_help = true)]
struct Cli {
    // 对于 flag 参数必须指定 #[arg], 否则为位置参数。
    #[arg(long)]
    two: String,

    // #[arg] 可以指定 Arg builder 的所有方法，如 default_value_t 来指定缺省值表达式，
    // 对于 short、long 参数，未设置值时自动推导。
    #[arg(short, long, default_value_t = 1)]
    one: String,

    #[arg(default_value_t = usize::MAX, short, long)]
    max_depth: usize,

    #[arg(short, long, default_value_t = String::from("default"))]
    namespace: String,

    // 位置参数：Option<T> 表示是可选的。
    name: Option<String>,

    // flag 参数：参数值用 : 分割，结果都合并到一个 Vec 中（默认空格分隔）
    #[arg(short, long, value_delimiter = ':')]
    name2: Vec<String>,

    #[arg(value_parser = validate_package_name)] // 使用自定义解析函数
    package_name: String,

    #[arg(short, long, action = clap::ArgAction::Count)] // 自定义 action 类型
    verbosity: u8,

    // 可以使用 clap::builder::Arg 的各种方法来设置 arg 的参数
    #[arg(short = 'n')]
    #[arg(long = "name")]
    #[arg(short, long)] // 根据 field name 自动推断
    name: Option<String>, // field 类型可以是任何 clap 支持的类型
}

fn validate_package_name(name: &str) -> Result<(), String> {
    if name.trim().len() != name.len() {
        Err(String::from(
            "package name cannot have leading and trailing space",
        ))
    } else {
        Ok(())
    }
}

fn main() {
    let cli = Cli::parse();
    println!("two: {:?}", cli.two);
    println!("one: {:?}", cli.one);
    println!("name: {:?}", cli.name.as_deref());
}

pub fn test_clap() {
    use clap::{Args, Parser, Subcommand};
    use std::fmt::Debug;

    /// Cli command
    #[derive(Parser, Debug)]
    struct Cli {
        #[command(flatten)]
        // Parser/Args 场景下，flatten 的 field type 必须是 struct 类型，该类型必须实现 Args，它的 field 作为命令行 Arg
        delegate: Struct,

        // 必须修饰 enum 类型
        #[command(subcommand)]
        command: Command,
    }

    // Args 必须修饰 struct，不需要对每个 field 添加 #[arg]
    #[derive(Args, Debug)]
    struct Struct {
        /// field arg
        field: u8,
    }

    /// sub command
    #[derive(Subcommand, Debug)]
    // Subcommand 必须修饰 enum 类型, 各 variant 是 struct 或 newtype 类型，struct 的各 field 为命令的参数 Args,
    // newtype 的 type 必须是 struct 类型。
    enum Command {
        // 每一个 Variant 都是一个 subcommand

        /// cmd1, newtype 类型, Struct 必须实现 Args。
        Cmd1(Struct),

        /// cmd2, 支持 struct variant 类型, struct field 为命令行参数(不需要添加 #[arg])
        Cmd2 {
            // Variant struct 的 field 对应 subcommand 的 args field
            field: u8,
        },

        #[command(flatten)]
        // SubCommand 中也可以使用 flatten，但它必须是实现 Subcommand 的 enum 类型.
        Variant3(SubCmd),
    }

    /// sub command
    #[derive(Subcommand, Debug)]
    enum SubCmd {
        /// Doc comment
        Sub1 { field: u8 },
    }

    let cli = Cli::parse();
    println!("{:?}", cli);
}


// cargo run:

// Usage: foo <FIELD> <COMMAND>

// Commands:
//   cmd1  cmd1, 支持 tuple 类型, 但则只支持一个类型的 newtype, 不支持 2 个及以上的 tuple
//   cmd2  cmd2, 支持 struct 类型, struct field 为命令行参数(不需要添加 #[arg])
//   sub1  Doc comment
//   help  Print this message or the help of the given subcommand(s)

// Arguments:
//   <FIELD>  field arg

// Options:
//   -h, --help  Print help

// cargo run cmd1 -h

// cmd1, 支持 tuple 类型, 但则只支持一个类型的 newtype, 不支持 2 个及以上的 tuple

// Usage: foo <FIELD> cmd1 <FIELD>

// Arguments:
//   <FIELD>  field arg

// Options:
//   -h, --help  Print help

// cargo run cmd2 -h

// cmd2, 支持 struct 类型, struct field 为命令行参数(不需要添加 #[arg])

// Usage: foo <FIELD> cmd2 <FIELD>

// Arguments:
//   <FIELD>  field

// Options:
//   -h, --help  Print help

#[derive(ValueEnum)
pub enum ColorChoice {
    Auto,
    Always,
    Never,
}

let mut cmd = clap::Command::new("raw")
    .arg(
        clap::Arg::new("color")
            .value_parser(clap::builder::EnumValueParser::<ColorChoice>::new())
            .required(true)
    );
let m = cmd.try_get_matches_from_mut(["cmd", "always"]).unwrap();
let port: ColorChoice = *m.get_one("color").expect("required");
assert_eq!(port, ColorChoice::Always);

// 例子
use clap::{Parser, ValueEnum};

#[derive(Parser)]
#[command(author, version, about, long_about = None)]
struct Cli {
    #[arg(value_enum)] // 枚举类型 field
    mode: Mode,
}

// 枚举类型 field 需要使用 ValueEnum 来修饰
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum)]
enum Mode {
    Fast,
    Slow,
}

fn main() {
    let cli = Cli::parse();
    match cli.mode {
        Mode::Fast => {
            println!("Hare");
        }
        Mode::Slow => {
            println!("Tortoise");
        }
    }
}

use std::io::Write;
use clap::Command;

fn main() -> Result<(), String> {
    loop {
        let line = readline()?;
        let line = line.trim();
        if line.is_empty() {
            continue;
        }

        match respond(line) {
            Ok(quit) => {
                if quit {
                    break;
                }
            }
            Err(err) => {
                write!(std::io::stdout(), "{err}").map_err(|e| e.to_string())?;
                std::io::stdout().flush().map_err(|e| e.to_string())?;
            }
        }
    }

    Ok(())
}

fn respond(line: &str) -> Result<bool, String> {
    let args = shlex::split(line).ok_or("error: Invalid quoting")?;

    let matches = cli()
        .try_get_matches_from(args) // 从自定义输入中解析命令行选项和参数
        .map_err(|e| e.to_string())?;

    match matches.subcommand() {
        Some(("ping", _matches)) => {
            write!(std::io::stdout(), "Pong").map_err(|e| e.to_string())?;
            std::io::stdout().flush().map_err(|e| e.to_string())?;
        }
        Some(("quit", _matches)) => {
            write!(std::io::stdout(), "Exiting ...").map_err(|e| e.to_string())?;
            std::io::stdout().flush().map_err(|e| e.to_string())?;
            return Ok(true);
        }
        Some((name, _matches)) => unimplemented!("{name}"),
        None => unreachable!("subcommand required"),
    }
    Ok(false)
}

fn cli() -> Command {
    // strip out usage
    const PARSER_TEMPLATE: &str = "\
        {all-args}
    ";

    // strip out name/version
    const APPLET_TEMPLATE: &str = "\
        {about-with-newline}\n\
        {usage-heading}\n    {usage}\n\
        \n\
        {all-args}{after-help}\
    ";

    Command::new("repl")
        .multicall(true)
        .arg_required_else_help(true)
        .subcommand_required(true)
        .subcommand_value_name("APPLET")
        .subcommand_help_heading("APPLETS")
        .help_template(PARSER_TEMPLATE)
        .subcommand(
            Command::new("ping")
                .about("Get a response")
                .help_template(APPLET_TEMPLATE),
        )
        .subcommand(
            Command::new("quit")
                .alias("exit")
                .about("Quit the REPL")
                .help_template(APPLET_TEMPLATE),
        )
}

fn readline() -> Result<String, String> {
    write!(std::io::stdout(), "$ ").map_err(|e| e.to_string())?;
    std::io::stdout().flush().map_err(|e| e.to_string())?;
    let mut buffer = String::new();
    std::io::stdin()
        .read_line(&mut buffer)
        .map_err(|e| e.to_string())?;
    Ok(buffer)
}