Initial vendor packages

Signed-off-by: Valentin Popov <valentin@popov.link>

vendor/clap/examples/tutorial_derive/01_quick.md

@@ -0,0 +1,35 @@
+```console
+$ 01_quick_derive --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 01_quick_derive[EXE] [OPTIONS] [NAME] [COMMAND]
+
+Commands:
+  test  does testing things
+  help  Print this message or the help of the given subcommand(s)
+
+Arguments:
+  [NAME]  Optional name to operate on
+
+Options:
+  -c, --config <FILE>  Sets a custom config file
+  -d, --debug...       Turn debugging information on
+  -h, --help           Print help
+  -V, --version        Print version
+
+```
+
+By default, the program does nothing:
+```console
+$ 01_quick_derive
+Debug mode is off
+
+```
+
+But you can mix and match the various features
+```console
+$ 01_quick_derive -dd test
+Debug mode is on
+Not printing testing lists...
+
+```

vendor/clap/examples/tutorial_derive/01_quick.rs

@@ -0,0 +1,68 @@
+use std::path::PathBuf;
+
+use clap::{Parser, Subcommand};
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    /// Optional name to operate on
+    name: Option<String>,
+
+    /// Sets a custom config file
+    #[arg(short, long, value_name = "FILE")]
+    config: Option<PathBuf>,
+
+    /// Turn debugging information on
+    #[arg(short, long, action = clap::ArgAction::Count)]
+    debug: u8,
+
+    #[command(subcommand)]
+    command: Option<Commands>,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    /// does testing things
+    Test {
+        /// lists test values
+        #[arg(short, long)]
+        list: bool,
+    },
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    // You can check the value provided by positional arguments, or option arguments
+    if let Some(name) = cli.name.as_deref() {
+        println!("Value for name: {name}");
+    }
+
+    if let Some(config_path) = cli.config.as_deref() {
+        println!("Value for config: {}", config_path.display());
+    }
+
+    // You can see how many times a particular flag or argument occurred
+    // Note, only flags can have multiple occurrences
+    match cli.debug {
+        0 => println!("Debug mode is off"),
+        1 => println!("Debug mode is kind of on"),
+        2 => println!("Debug 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 cmd
+    match &cli.command {
+        Some(Commands::Test { list }) => {
+            if *list {
+                println!("Printing testing lists...");
+            } else {
+                println!("Not printing testing lists...");
+            }
+        }
+        None => {}
+    }
+
+    // Continued program logic goes here...
+}

vendor/clap/examples/tutorial_derive/02_app_settings.md

@@ -0,0 +1,17 @@
+```console
+$ 02_app_settings_derive --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 02_app_settings_derive[EXE] --two <TWO> --one <ONE>
+
+Options:
+      --two <TWO>
+          
+      --one <ONE>
+          
+  -h, --help
+          Print help
+  -V, --version
+          Print version
+
+```

vendor/clap/examples/tutorial_derive/02_app_settings.rs

@@ -0,0 +1,18 @@
+use clap::Parser;
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+#[command(next_line_help = true)]
+struct Cli {
+    #[arg(long)]
+    two: String,
+    #[arg(long)]
+    one: String,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    println!("two: {:?}", cli.two);
+    println!("one: {:?}", cli.one);
+}

vendor/clap/examples/tutorial_derive/02_apps.md

@@ -0,0 +1,16 @@
+```console
+$ 02_apps_derive --help
+Does awesome things
+
+Usage: 02_apps_derive[EXE] --two <TWO> --one <ONE>
+
+Options:
+      --two <TWO>  
+      --one <ONE>  
+  -h, --help       Print help
+  -V, --version    Print version
+
+$ 02_apps_derive --version
+MyApp 1.0
+
+```

vendor/clap/examples/tutorial_derive/02_apps.rs

@@ -0,0 +1,20 @@
+use clap::Parser;
+
+#[derive(Parser)]
+#[command(name = "MyApp")]
+#[command(author = "Kevin K. <kbknapp@gmail.com>")]
+#[command(version = "1.0")]
+#[command(about = "Does awesome things", long_about = None)]
+struct Cli {
+    #[arg(long)]
+    two: String,
+    #[arg(long)]
+    one: String,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    println!("two: {:?}", cli.two);
+    println!("one: {:?}", cli.one);
+}

vendor/clap/examples/tutorial_derive/02_crate.md

@@ -0,0 +1,16 @@
+```console
+$ 02_crate_derive --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 02_crate_derive[EXE] --two <TWO> --one <ONE>
+
+Options:
+      --two <TWO>  
+      --one <ONE>  
+  -h, --help       Print help
+  -V, --version    Print version
+
+$ 02_crate_derive --version
+clap [..]
+
+```

vendor/clap/examples/tutorial_derive/02_crate.rs

@@ -0,0 +1,17 @@
+use clap::Parser;
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)] // Read from `Cargo.toml`
+struct Cli {
+    #[arg(long)]
+    two: String,
+    #[arg(long)]
+    one: String,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    println!("two: {:?}", cli.two);
+    println!("one: {:?}", cli.one);
+}

vendor/clap/examples/tutorial_derive/03_01_flag_bool.md

@@ -0,0 +1,26 @@
+```console
+$ 03_01_flag_bool_derive --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 03_01_flag_bool_derive[EXE] [OPTIONS]
+
+Options:
+  -v, --verbose  
+  -h, --help     Print help
+  -V, --version  Print version
+
+$ 03_01_flag_bool_derive
+verbose: false
+
+$ 03_01_flag_bool_derive --verbose
+verbose: true
+
+$ 03_01_flag_bool_derive --verbose --verbose
+? failed
+error: the argument '--verbose' cannot be used multiple times
+
+Usage: 03_01_flag_bool_derive[EXE] [OPTIONS]
+
+For more information, try '--help'.
+
+```

vendor/clap/examples/tutorial_derive/03_01_flag_bool.rs

@@ -0,0 +1,14 @@
+use clap::Parser;
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    #[arg(short, long)]
+    verbose: bool,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    println!("verbose: {:?}", cli.verbose);
+}

vendor/clap/examples/tutorial_derive/03_01_flag_count.md

@@ -0,0 +1,21 @@
+```console
+$ 03_01_flag_count_derive --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 03_01_flag_count_derive[EXE] [OPTIONS]
+
+Options:
+  -v, --verbose...  
+  -h, --help        Print help
+  -V, --version     Print version
+
+$ 03_01_flag_count_derive
+verbose: 0
+
+$ 03_01_flag_count_derive --verbose
+verbose: 1
+
+$ 03_01_flag_count_derive --verbose --verbose
+verbose: 2
+
+```

vendor/clap/examples/tutorial_derive/03_01_flag_count.rs

@@ -0,0 +1,14 @@
+use clap::Parser;
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    #[arg(short, long, action = clap::ArgAction::Count)]
+    verbose: u8,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    println!("verbose: {:?}", cli.verbose);
+}

vendor/clap/examples/tutorial_derive/03_02_option.md

@@ -0,0 +1,30 @@
+```console
+$ 03_02_option_derive --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 03_02_option_derive[EXE] [OPTIONS]
+
+Options:
+  -n, --name <NAME>  
+  -h, --help         Print help
+  -V, --version      Print version
+
+$ 03_02_option_derive
+name: None
+
+$ 03_02_option_derive --name bob
+name: Some("bob")
+
+$ 03_02_option_derive --name=bob
+name: Some("bob")
+
+$ 03_02_option_derive -n bob
+name: Some("bob")
+
+$ 03_02_option_derive -n=bob
+name: Some("bob")
+
+$ 03_02_option_derive -nbob
+name: Some("bob")
+
+```

vendor/clap/examples/tutorial_derive/03_02_option.rs

@@ -0,0 +1,14 @@
+use clap::Parser;
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    #[arg(short, long)]
+    name: Option<String>,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    println!("name: {:?}", cli.name.as_deref());
+}

vendor/clap/examples/tutorial_derive/03_02_option_mult.md

@@ -0,0 +1,30 @@
+```console
+$ 03_02_option_mult_derive --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 03_02_option_mult_derive[EXE] [OPTIONS]
+
+Options:
+  -n, --name <NAME>  
+  -h, --help         Print help
+  -V, --version      Print version
+
+$ 03_02_option_mult_derive
+name: []
+
+$ 03_02_option_mult_derive --name bob
+name: ["bob"]
+
+$ 03_02_option_mult_derive --name=bob
+name: ["bob"]
+
+$ 03_02_option_mult_derive -n bob
+name: ["bob"]
+
+$ 03_02_option_mult_derive -n=bob
+name: ["bob"]
+
+$ 03_02_option_mult_derive -nbob
+name: ["bob"]
+
+```

vendor/clap/examples/tutorial_derive/03_02_option_mult.rs

@@ -0,0 +1,14 @@
+use clap::Parser;
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    #[arg(short, long)]
+    name: Vec<String>,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    println!("name: {:?}", cli.name);
+}

vendor/clap/examples/tutorial_derive/03_03_positional.md

@@ -0,0 +1,20 @@
+```console
+$ 03_03_positional_derive --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 03_03_positional_derive[EXE] [NAME]
+
+Arguments:
+  [NAME]  
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+
+$ 03_03_positional_derive
+name: None
+
+$ 03_03_positional_derive bob
+name: Some("bob")
+
+```

vendor/clap/examples/tutorial_derive/03_03_positional.rs

@@ -0,0 +1,13 @@
+use clap::Parser;
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    name: Option<String>,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    println!("name: {:?}", cli.name.as_deref());
+}

vendor/clap/examples/tutorial_derive/03_03_positional_mult.md

@@ -0,0 +1,23 @@
+```console
+$ 03_03_positional_mult_derive --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 03_03_positional_mult_derive[EXE] [NAME]...
+
+Arguments:
+  [NAME]...  
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+
+$ 03_03_positional_mult_derive
+name: []
+
+$ 03_03_positional_mult_derive bob
+name: ["bob"]
+
+$ 03_03_positional_mult_derive bob john
+name: ["bob", "john"]
+
+```

vendor/clap/examples/tutorial_derive/03_03_positional_mult.rs

@@ -0,0 +1,13 @@
+use clap::Parser;
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    name: Vec<String>,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    println!("name: {:?}", cli.name);
+}

vendor/clap/examples/tutorial_derive/03_04_subcommands.md

@@ -0,0 +1,60 @@
+```console
+$ 03_04_subcommands_derive help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 03_04_subcommands_derive[EXE] <COMMAND>
+
+Commands:
+  add   Adds files to myapp
+  help  Print this message or the help of the given subcommand(s)
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+
+$ 03_04_subcommands_derive help add
+Adds files to myapp
+
+Usage: 03_04_subcommands_derive[EXE] add [NAME]
+
+Arguments:
+  [NAME]  
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+
+$ 03_04_subcommands_derive add bob
+'myapp add' was used, name is: Some("bob")
+
+```
+
+When specifying commands with `command: Commands`, they are required.
+Alternatively, you could do `command: Option<Commands>` to make it optional.
+```console
+$ 03_04_subcommands_derive
+? failed
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 03_04_subcommands_derive[EXE] <COMMAND>
+
+Commands:
+  add   Adds files to myapp
+  help  Print this message or the help of the given subcommand(s)
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+
+```
+
+Since we specified [`#[command(propagate_version = true)]`][crate::Command::propagate_version],
+the `--version` flag is available in all subcommands:
+```console
+$ 03_04_subcommands_derive --version
+clap [..]
+
+$ 03_04_subcommands_derive add --version
+clap-add [..]
+
+```

vendor/clap/examples/tutorial_derive/03_04_subcommands.rs

@@ -0,0 +1,27 @@
+use clap::{Parser, Subcommand};
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+#[command(propagate_version = true)]
+struct Cli {
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    /// Adds files to myapp
+    Add { name: Option<String> },
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    // You can check for the existence of subcommands, and if found use their
+    // matches just as you would the top level cmd
+    match &cli.command {
+        Commands::Add { name } => {
+            println!("'myapp add' was used, name is: {name:?}")
+        }
+    }
+}

vendor/clap/examples/tutorial_derive/03_04_subcommands_alt.rs

@@ -0,0 +1,32 @@
+use clap::{Args, Parser, Subcommand};
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+#[command(propagate_version = true)]
+struct Cli {
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    /// Adds files to myapp
+    Add(AddArgs),
+}
+
+#[derive(Args)]
+struct AddArgs {
+    name: Option<String>,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    // You can check for the existence of subcommands, and if found use their
+    // matches just as you would the top level cmd
+    match &cli.command {
+        Commands::Add(name) => {
+            println!("'myapp add' was used, name is: {:?}", name.name)
+        }
+    }
+}

vendor/clap/examples/tutorial_derive/03_05_default_values.md

@@ -0,0 +1,20 @@
+```console
+$ 03_05_default_values_derive --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 03_05_default_values_derive[EXE] [PORT]
+
+Arguments:
+  [PORT]  [default: 2020]
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+
+$ 03_05_default_values_derive
+port: 2020
+
+$ 03_05_default_values_derive 22
+port: 22
+
+```

vendor/clap/examples/tutorial_derive/03_05_default_values.rs

@@ -0,0 +1,14 @@
+use clap::Parser;
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    #[arg(default_value_t = 2020)]
+    port: u16,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    println!("port: {:?}", cli.port);
+}

vendor/clap/examples/tutorial_derive/04_01_enum.md

@@ -0,0 +1,47 @@
+```console
+$ 04_01_enum_derive --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 04_01_enum_derive[EXE] <MODE>
+
+Arguments:
+  <MODE>
+          What mode to run the program in
+
+          Possible values:
+          - fast: Run swiftly
+          - slow: Crawl slowly but steadily
+
+Options:
+  -h, --help
+          Print help (see a summary with '-h')
+
+  -V, --version
+          Print version
+
+$ 04_01_enum_derive -h
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 04_01_enum_derive[EXE] <MODE>
+
+Arguments:
+  <MODE>  What mode to run the program in [possible values: fast, slow]
+
+Options:
+  -h, --help     Print help (see more with '--help')
+  -V, --version  Print version
+
+$ 04_01_enum_derive fast
+Hare
+
+$ 04_01_enum_derive slow
+Tortoise
+
+$ 04_01_enum_derive medium
+? failed
+error: invalid value 'medium' for '<MODE>'
+  [possible values: fast, slow]
+
+For more information, try '--help'.
+
+```

vendor/clap/examples/tutorial_derive/04_01_enum.rs

@@ -0,0 +1,32 @@
+use clap::{Parser, ValueEnum};
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    /// What mode to run the program in
+    #[arg(value_enum)]
+    mode: Mode,
+}
+
+#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum)]
+enum Mode {
+    /// Run swiftly
+    Fast,
+    /// Crawl slowly but steadily
+    ///
+    /// This paragraph is ignored because there is no long help text for possible values.
+    Slow,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    match cli.mode {
+        Mode::Fast => {
+            println!("Hare");
+        }
+        Mode::Slow => {
+            println!("Tortoise");
+        }
+    }
+}

vendor/clap/examples/tutorial_derive/04_02_parse.md

@@ -0,0 +1,29 @@
+```console
+$ 04_02_parse_derive --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 04_02_parse_derive[EXE] <PORT>
+
+Arguments:
+  <PORT>  Network port to use
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+
+$ 04_02_parse_derive 22
+PORT = 22
+
+$ 04_02_parse_derive foobar
+? failed
+error: invalid value 'foobar' for '<PORT>': invalid digit found in string
+
+For more information, try '--help'.
+
+$ 04_02_parse_derive 0
+? failed
+error: invalid value '0' for '<PORT>': 0 is not in 1..=65535
+
+For more information, try '--help'.
+
+```

vendor/clap/examples/tutorial_derive/04_02_parse.rs

@@ -0,0 +1,15 @@
+use clap::Parser;
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    /// Network port to use
+    #[arg(value_parser = clap::value_parser!(u16).range(1..))]
+    port: u16,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    println!("PORT = {}", cli.port);
+}

vendor/clap/examples/tutorial_derive/04_02_validate.md

@@ -0,0 +1,29 @@
+```console
+$ 04_02_validate_derive --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 04_02_validate_derive[EXE] <PORT>
+
+Arguments:
+  <PORT>  Network port to use
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+
+$ 04_02_validate_derive 22
+PORT = 22
+
+$ 04_02_validate_derive foobar
+? failed
+error: invalid value 'foobar' for '<PORT>': `foobar` isn't a port number
+
+For more information, try '--help'.
+
+$ 04_02_validate_derive 0
+? failed
+error: invalid value '0' for '<PORT>': port not in range 1-65535
+
+For more information, try '--help'.
+
+```

vendor/clap/examples/tutorial_derive/04_02_validate.rs

@@ -0,0 +1,34 @@
+use std::ops::RangeInclusive;
+
+use clap::Parser;
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    /// Network port to use
+    #[arg(value_parser = port_in_range)]
+    port: u16,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    println!("PORT = {}", cli.port);
+}
+
+const PORT_RANGE: RangeInclusive<usize> = 1..=65535;
+
+fn port_in_range(s: &str) -> Result<u16, String> {
+    let port: usize = s
+        .parse()
+        .map_err(|_| format!("`{s}` isn't a port number"))?;
+    if PORT_RANGE.contains(&port) {
+        Ok(port as u16)
+    } else {
+        Err(format!(
+            "port not in range {}-{}",
+            PORT_RANGE.start(),
+            PORT_RANGE.end()
+        ))
+    }
+}

vendor/clap/examples/tutorial_derive/04_03_relations.md

@@ -0,0 +1,53 @@
+```console
+$ 04_03_relations_derive --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 04_03_relations_derive[EXE] [OPTIONS] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE]
+
+Arguments:
+  [INPUT_FILE]  some regular input
+
+Options:
+      --set-ver <VER>      set version manually
+      --major              auto inc major
+      --minor              auto inc minor
+      --patch              auto inc patch
+      --spec-in <SPEC_IN>  some special input argument
+  -c <CONFIG>              
+  -h, --help               Print help
+  -V, --version            Print version
+
+$ 04_03_relations_derive
+? failed
+error: the following required arguments were not provided:
+  <--set-ver <VER>|--major|--minor|--patch>
+
+Usage: 04_03_relations_derive[EXE] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE]
+
+For more information, try '--help'.
+
+$ 04_03_relations_derive --major
+Version: 2.2.3
+
+$ 04_03_relations_derive --major --minor
+? failed
+error: the argument '--major' cannot be used with '--minor'
+
+Usage: 04_03_relations_derive[EXE] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE]
+
+For more information, try '--help'.
+
+$ 04_03_relations_derive --major -c config.toml
+? failed
+error: the following required arguments were not provided:
+  <INPUT_FILE|--spec-in <SPEC_IN>>
+
+Usage: 04_03_relations_derive[EXE] -c <CONFIG> <--set-ver <VER>|--major|--minor|--patch> <INPUT_FILE|--spec-in <SPEC_IN>>
+
+For more information, try '--help'.
+
+$ 04_03_relations_derive --major -c config.toml --spec-in input.txt
+Version: 2.2.3
+Doing work using input input.txt and config config.toml
+
+```

vendor/clap/examples/tutorial_derive/04_03_relations.rs

@@ -0,0 +1,75 @@
+use clap::{Args, Parser};
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    #[command(flatten)]
+    vers: Vers,
+
+    /// some regular input
+    #[arg(group = "input")]
+    input_file: Option<String>,
+
+    /// some special input argument
+    #[arg(long, group = "input")]
+    spec_in: Option<String>,
+
+    #[arg(short, requires = "input")]
+    config: Option<String>,
+}
+
+#[derive(Args)]
+#[group(required = true, multiple = false)]
+struct Vers {
+    /// set version manually
+    #[arg(long, value_name = "VER")]
+    set_ver: Option<String>,
+
+    /// auto inc major
+    #[arg(long)]
+    major: bool,
+
+    /// auto inc minor
+    #[arg(long)]
+    minor: bool,
+
+    /// auto inc patch
+    #[arg(long)]
+    patch: bool,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    // Let's assume the old version 1.2.3
+    let mut major = 1;
+    let mut minor = 2;
+    let mut patch = 3;
+
+    // See if --set_ver was used to set the version manually
+    let vers = &cli.vers;
+    let version = if let Some(ver) = vers.set_ver.as_deref() {
+        ver.to_string()
+    } else {
+        // Increment the one requested (in a real program, we'd reset the lower numbers)
+        let (maj, min, pat) = (vers.major, vers.minor, vers.patch);
+        match (maj, min, pat) {
+            (true, _, _) => major += 1,
+            (_, true, _) => minor += 1,
+            (_, _, true) => patch += 1,
+            _ => unreachable!(),
+        };
+        format!("{major}.{minor}.{patch}")
+    };
+
+    println!("Version: {version}");
+
+    // Check for usage of -c
+    if let Some(config) = cli.config.as_deref() {
+        let input = cli
+            .input_file
+            .as_deref()
+            .unwrap_or_else(|| cli.spec_in.as_deref().unwrap());
+        println!("Doing work using input {input} and config {config}");
+    }
+}

vendor/clap/examples/tutorial_derive/04_04_custom.md

@@ -0,0 +1,52 @@
+```console
+$ 04_04_custom_derive --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 04_04_custom_derive[EXE] [OPTIONS] [INPUT_FILE]
+
+Arguments:
+  [INPUT_FILE]  some regular input
+
+Options:
+      --set-ver <VER>      set version manually
+      --major              auto inc major
+      --minor              auto inc minor
+      --patch              auto inc patch
+      --spec-in <SPEC_IN>  some special input argument
+  -c <CONFIG>              
+  -h, --help               Print help
+  -V, --version            Print version
+
+$ 04_04_custom_derive
+? failed
+error: Can only modify one version field
+
+Usage: clap [OPTIONS] [INPUT_FILE]
+
+For more information, try '--help'.
+
+$ 04_04_custom_derive --major
+Version: 2.2.3
+
+$ 04_04_custom_derive --major --minor
+? failed
+error: Can only modify one version field
+
+Usage: clap [OPTIONS] [INPUT_FILE]
+
+For more information, try '--help'.
+
+$ 04_04_custom_derive --major -c config.toml
+? failed
+Version: 2.2.3
+error: INPUT_FILE or --spec-in is required when using --config
+
+Usage: clap [OPTIONS] [INPUT_FILE]
+
+For more information, try '--help'.
+
+$ 04_04_custom_derive --major -c config.toml --spec-in input.txt
+Version: 2.2.3
+Doing work using input input.txt and config config.toml
+
+```

vendor/clap/examples/tutorial_derive/04_04_custom.rs

@@ -0,0 +1,91 @@
+use clap::error::ErrorKind;
+use clap::{CommandFactory, Parser};
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    /// set version manually
+    #[arg(long, value_name = "VER")]
+    set_ver: Option<String>,
+
+    /// auto inc major
+    #[arg(long)]
+    major: bool,
+
+    /// auto inc minor
+    #[arg(long)]
+    minor: bool,
+
+    /// auto inc patch
+    #[arg(long)]
+    patch: bool,
+
+    /// some regular input
+    input_file: Option<String>,
+
+    /// some special input argument
+    #[arg(long)]
+    spec_in: Option<String>,
+
+    #[arg(short)]
+    config: Option<String>,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    // Let's assume the old version 1.2.3
+    let mut major = 1;
+    let mut minor = 2;
+    let mut patch = 3;
+
+    // See if --set-ver was used to set the version manually
+    let version = if let Some(ver) = cli.set_ver.as_deref() {
+        if cli.major || cli.minor || cli.patch {
+            let mut cmd = Cli::command();
+            cmd.error(
+                ErrorKind::ArgumentConflict,
+                "Can't do relative and absolute version change",
+            )
+            .exit();
+        }
+        ver.to_string()
+    } else {
+        // Increment the one requested (in a real program, we'd reset the lower numbers)
+        let (maj, min, pat) = (cli.major, cli.minor, cli.patch);
+        match (maj, min, pat) {
+            (true, false, false) => major += 1,
+            (false, true, false) => minor += 1,
+            (false, false, true) => patch += 1,
+            _ => {
+                let mut cmd = Cli::command();
+                cmd.error(
+                    ErrorKind::ArgumentConflict,
+                    "Can only modify one version field",
+                )
+                .exit();
+            }
+        };
+        format!("{major}.{minor}.{patch}")
+    };
+
+    println!("Version: {version}");
+
+    // Check for usage of -c
+    if let Some(config) = cli.config.as_deref() {
+        let input = cli
+            .input_file
+            .as_deref()
+            // 'or' is preferred to 'or_else' here since `Option::as_deref` is 'const'
+            .or(cli.spec_in.as_deref())
+            .unwrap_or_else(|| {
+                let mut cmd = Cli::command();
+                cmd.error(
+                    ErrorKind::MissingRequiredArgument,
+                    "INPUT_FILE or --spec-in is required when using --config",
+                )
+                .exit()
+            });
+        println!("Doing work using input {input} and config {config}");
+    }
+}

vendor/clap/examples/tutorial_derive/05_01_assert.rs

@@ -0,0 +1,20 @@
+use clap::Parser;
+
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    /// Network port to use
+    port: u16,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    println!("PORT = {}", cli.port);
+}
+
+#[test]
+fn verify_cli() {
+    use clap::CommandFactory;
+    Cli::command().debug_assert()
+}