Clap

https://docs.rs/clap/latest
Admin
Clap is a command-line argument parser for Rust that provides a polished CLI experience with...
Tokens:1,041,282
Snippets:7,227
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Quick start example (01_quick.rs)

Source: https://docs.rs/clap/latest/src/clap/_tutorial.rs.html?search=u32+-%3E+bool

Preview of a clap application using the builder API. This example is included from the file `examples/tutorial_builder/01_quick.rs`.

```rust
#![doc = include_str!("../examples/tutorial_builder/01_quick.rs")]
```

--------------------------------

### Quick start example for derive API

Source: https://docs.rs/clap/latest/src/clap/_derive/_tutorial.rs.html?search=std%3A%3Avec

A basic example showing how to create a command-line application using the derive API.

```rust
#![doc = include_str!("../../examples/tutorial_derive/01_quick.rs")]
```

--------------------------------

### Configure parser with Command (02_apps.rs)

Source: https://docs.rs/clap/latest/src/clap/_tutorial.rs.html?search=u32+-%3E+bool

Shows how to use `Command` to start building a parser. This example is included from `examples/tutorial_builder/02_apps.rs`.

```rust
#![doc = include_str!("../examples/tutorial_builder/02_apps.rs")]
```

--------------------------------

### Repository example: CLI builder with templates

Source: https://docs.rs/clap/latest/clap/builder/struct.Command.html?search=

Partial example from examples/repl.rs showing the start of a CLI builder function. It defines templates to strip out usage and name/version from help output.

```rust
fn cli() -> Command {
    // strip out usage
    const PARSER_TEMPLATE: &str = "\
        {all-args}
    ";
    // strip out name/version
    const APPLET_TEMPLATE: &str = "\
        {about-with-newline}\n\
```

--------------------------------

### Quick start example: clap builder application

Source: https://docs.rs/clap/latest/clap/_tutorial/index.html?search=

A complete example of a clap builder application that defines positional, option, flag, and subcommand arguments. It demonstrates using command!(), arg!(), value_parser!, and ArgAction::SetTrue. The example shows how to access argument values, check flag counts, and handle subcommands.

```rust
use std::path::PathBuf;

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

fn main() {
    let matches = command!() // requires `cargo` feature
        .arg(arg!([name] "Optional name to operate on"))
        .arg(
            arg!(
                -c --config <FILE> "Sets a custom config file"
            )
            // We don't have syntax yet for optional options, so manually calling `required`
            .required(false)
            .value_parser(value_parser!(PathBuf)),
        )
        .arg(arg!(
            -d --debug ... "Turn debugging information on"
        ))
        .subcommand(
            Command::new("test")
                .about("does testing things")
                .arg(arg!(-l --list "lists test values").action(ArgAction::SetTrue)),
        )
        .get_matches();

    // You can check the value provided by positional arguments, or option arguments
    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());
    }

    // You can see how many times a particular flag or argument occurred
    // Note, only flags can have multiple occurrences
    match matches
        .get_one::<u8>("debug")
        .expect("Counts are defaulted")
    {
        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
    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...");
        }
    }

    // Continued program logic goes here...
}
```

--------------------------------

### Derive example using include_str!

Source: https://docs.rs/clap/latest/src/clap/_derive/mod.rs.html?search=

Shows how to include an external example file in documentation using the include_str! macro. This is a documentation pattern, not a runnable example.

```rust
#![doc = include_str!("../../examples/demo.rs")]
```

--------------------------------

### Output of default value example

Source: https://docs.rs/clap/latest/clap/_tutorial/index.html?search=

Shows the help output and example runs for the default value example. The help displays the default value, and running without arguments uses the default, while providing an argument overrides it.

```bash
$ 03_05_default_values --help
A simple to use, efficient, and full-featured Command Line Argument Parser

Usage: 03_05_default_values[EXE] [PORT]

Arguments:
  [PORT]  [default: 2020]

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

$ 03_05_default_values
port: 2020

$ 03_05_default_values 22
port: 22

```

--------------------------------

### Panic example: empty range

Source: https://docs.rs/clap/latest/clap/builder/struct.ValueRange.html

This example panics in debug builds because the range is empty (start equals end).

```rust
let range = ValueRange::new(5..5);  // Panics! (empty)
```

--------------------------------

### Run 01_quick --help

Source: https://docs.rs/clap/latest/clap/_tutorial/index.html?search=

Output of running the example application with the --help flag, showing the generated help message with usage, commands, arguments, and options.

```bash
$ 01_quick --help
A simple to use, efficient, and full-featured Command Line Argument Parser

Usage: 01_quick[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

```

--------------------------------

### Panic example: reversed range

Source: https://docs.rs/clap/latest/clap/builder/struct.ValueRange.html

This example panics in debug builds because the range is reversed (start greater than end).

```rust
let range = ValueRange::new(10..5);  // Panics! (reversed)
```

--------------------------------

### examples/tutorial_builder/02_apps.rs

Source: https://docs.rs/clap/latest/clap/builder/struct.Arg.html?search=

Example from the repository showing required arguments in a full command definition.

```rust
fn main() {
    let matches = Command::new("MyApp")
        .version("1.0")
        .about("Does awesome things")
        .arg(arg!(--two <VALUE>).required(true))
        .arg(arg!(--one <VALUE>).required(true))
        .get_matches();

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

--------------------------------

### Run CLI help and usage examples

Source: https://docs.rs/clap/latest/clap/index.html?search=

Examples of running the generated CLI with help flags and positional arguments.

```bash
$ demo --help
A simple to use, efficient, and full-featured Command Line Argument Parser

Usage: demo[EXE] [OPTIONS] --name <NAME>

Options:
  -n, --name <NAME>    Name of the person to greet
  -c, --count <COUNT>  Number of times to greet [default: 1]
  -h, --help           Print help
  -V, --version        Print version

$ demo --name Me
Hello Me!
```

--------------------------------

### get method example

Source: https://docs.rs/clap/latest/clap/builder/struct.Str.html

Shows how to use the get method from Deref<Target = str> to safely get a subslice of a string, returning None instead of panicking when the index is invalid.

```rust
let v = String::from("🗻∈🌏");

assert_eq!(Some("🗻"), v.get(0..4));

// indices not on UTF-8 sequence boundaries
assert!(v.get(1..).is_none());
assert!(v.get(..8).is_none());

// out of bounds
assert!(v.get(..42).is_none());
```

--------------------------------

### Run demo CLI and show help output

Source: https://docs.rs/clap/latest/clap/index.html

Shows the expected output of running the example CLI. The --help output displays usage, options, and defaults; running with --name Me prints 'Hello Me!'. The version number and .exe extension on Windows are replaced by placeholders.

```bash
$ demo --help
A simple to use, efficient, and full-featured Command Line Argument Parser

Usage: demo[EXE] [OPTIONS] --name <NAME>

Options:
  -n, --name <NAME>    Name of the person to greet
  -c, --count <COUNT>  Number of times to greet [default: 1]
  -h, --help           Print help
  -V, --version        Print version

$ demo --name Me
Hello Me!

```

--------------------------------

### multicall-busybox.rs example

Source: https://docs.rs/clap/latest/clap/builder/struct.Command.html

Example from examples/multicall-busybox.rs (line 18) showing a multicall command with a busybox subcommand that uses arg_required_else_help and an install argument.

```rust
fn main() {
    let cmd = Command::new(env!("CARGO_CRATE_NAME"))
        .multicall(true)
        .subcommand(
            Command::new("busybox")
                .arg_required_else_help(true)
                .subcommand_value_name("APPLET")
                .subcommand_help_heading("APPLETS")
                .arg(
                    Arg::new("install")
                        .long("install")
                        .help("Install hardlinks for all subcommands in path")
                        .exclusive(true)
                        .action(ArgAction::Set)
                        .default_missing_value("/usr/local/bin")
                        .value_parser(value_parser!(PathBuf)),
                )
                .subcommands(applet_commands()),
        )
        .subcommands(applet_commands());

    let matches = cmd.get_matches();
```

--------------------------------

### Complete example with version and required arguments

Source: https://docs.rs/clap/latest/clap/struct.Command.html

A complete example from the repository (examples/tutorial_builder/02_apps.rs) showing a Command with version "1.0", required arguments, and retrieving the matched values. It uses the `arg!` macro and prints the values with `get_one::<String>()`.

```rust
fn main() {
    let matches = Command::new("MyApp")
        .version("1.0")
        .about("Does awesome things")
        .arg(arg!(--two <VALUE>).required(true))
        .arg(arg!(--one <VALUE>).required(true))
        .get_matches();

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

```

--------------------------------

### Application settings help output

Source: https://docs.rs/clap/latest/clap/_derive/_tutorial/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example output demonstrating the next_line_help setting.

```text
$ 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
```

--------------------------------

### Multicall busybox example with subcommands and install flag

Source: https://docs.rs/clap/latest/clap/builder/struct.Command.html?search=

Example from examples/multicall-busybox.rs showing a multicall binary with a busybox subcommand that has an --install flag and applet subcommands. The parser uses multicall(true) and subcommand_required to ensure valid subcommand names, and the program exits with status 1 for false and 0 for true.

```rust
fn applet_commands() -> [Command; 2] {
    [
        Command::new("true").about("does nothing successfully"),
        Command::new("false").about("does nothing unsuccessfully"),
    ]
}

fn main() {
    let cmd = Command::new(env!("CARGO_CRATE_NAME"))
        .multicall(true)
        .subcommand(
            Command::new("busybox")
                .arg_required_else_help(true)
                .subcommand_value_name("APPLET")
                .subcommand_help_heading("APPLETS")
                .arg(
                    Arg::new("install")
                        .long("install")
                        .help("Install hardlinks for all subcommands in path")
                        .exclusive(true)
                        .action(ArgAction::Set)
                        .default_missing_value("/usr/local/bin")
                        .value_parser(value_parser!(PathBuf)),
                )
                .subcommands(applet_commands()),
        )
        .subcommands(applet_commands());

    let matches = cmd.get_matches();
    let mut subcommand = matches.subcommand();
    if let Some(("busybox", cmd)) = subcommand {
        if cmd.contains_id("install") {
            unimplemented!("Make hardlinks to the executable here");
        }
        subcommand = cmd.subcommand();
    }
    match subcommand {
        Some(("false", _)) => exit(1),
        Some(("true", _)) => exit(0),
        _ => unreachable!("parser should ensure only valid subcommand names are used"),
    }
}
```

--------------------------------

### Output of 02_app --help and --version

Source: https://docs.rs/clap/latest/clap/_tutorial/index.html?search=u32+-%3E+bool

Shows the help and version output for the Command-based example. The help lists usage and options; version prints 'MyApp 1.0'.

```text
$ 02_apps --help
Does awesome things

Usage: 02_apps[EXE] --two <VALUE> --one <VALUE>

Options:
      --two <VALUE>  
      --one <VALUE>  
  -h, --help         Print help
  -V, --version      Print version

$ 02_apps --version
MyApp 1.0

```

--------------------------------

### Basic Command Initialization

Source: https://docs.rs/clap/latest/clap/builder/struct.Command.html

A minimal example showing how to create a new Command instance with an about description.

```rust
Command::new("myprog")
    .about("Does really amazing things for great people")
```

--------------------------------

### Count action example

Source: https://docs.rs/clap/latest/clap/builder/enum.ArgAction.html

Increments a u8 counter starting from 0. No value is allowed. If no default_value is set, it will be 0. The example shows counting occurrences of --flag and asserting the count.

```rust
let cmd = Command::new("mycmd")
    .arg(
        Arg::new("flag")
            .long("flag")
            .action(clap::ArgAction::Count)
    );

let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag", "--flag"]).unwrap();
assert!(matches.contains_id("flag"));
assert_eq!(
    matches.get_count("flag"),
    2
);

let matches = cmd.try_get_matches_from(["mycmd"]).unwrap();
assert!(matches.contains_id("flag"));
assert_eq!(
    matches.get_count("flag"),
    0
);
```

--------------------------------

### subcommand_matches example

Source: https://docs.rs/clap/latest/clap/parser/struct.ArgMatches.html?search=u32+-%3E+bool

Shows how to use subcommand_matches to get the ArgMatches of a specific subcommand. The example creates a command with a debug flag and a test subcommand with an option, then retrieves the subcommand's matches and accesses its value.

```rust
let app_m = Command::new("myprog")
    .arg(Arg::new("debug")
        .short('d')
        .action(ArgAction::SetTrue)
    )
    .subcommand(Command::new("test")
        .arg(Arg::new("opt")
            .long("option")
            .action(ArgAction::Set)))
    .get_matches_from(vec![
        "myprog", "-d", "test", "--option", "val"
    ]);

// Both parent commands, and child subcommands can have arguments present at the same times
assert!(app_m.get_flag("debug"));

// Get the subcommand's ArgMatches instance
if let Some(sub_m) = app_m.subcommand_matches("test") {
    // Use the struct like normal
    assert_eq!(sub_m.get_one::<String>("opt").map(|s| s.as_str()), Some("val"));
}

```

--------------------------------

### len method example

Source: https://docs.rs/clap/latest/clap/builder/struct.Str.html

Shows how to use the len method from Deref<Target = str> to get the length in bytes, not characters or graphemes. The example demonstrates that 'ƒoo' has a byte length of 4 but only 3 characters.

```rust
let len = "foo".len();
assert_eq!(3, len);

assert_eq!("ƒoo".len(), 4); // fancy f!
assert_eq!("ƒoo".chars().count(), 3);
```

--------------------------------

### Help output for 01_quick_derive

Source: https://docs.rs/clap/latest/clap/_derive/_tutorial/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Output of running the example binary with the --help flag, showing usage, commands, arguments, and options.

```bash
$ 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
```

--------------------------------

### Get name from PossibleValue in git-derive example

Source: https://docs.rs/clap/latest/clap/builder/struct.PossibleValue.html?search=

Retrieves the name of a PossibleValue within a custom Display implementation.

```rust
70    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
71        self.to_possible_value()
72            .expect("no values are skipped")
73            .get_name()
74            .fmt(f)
75    }
```

--------------------------------

### Multicall Hostname Example

Source: https://docs.rs/clap/latest/clap/builder/struct.Command.html

Demonstrates a basic multicall setup where subcommands act like independent tools.

```rust
fn main() {
    let cmd = Command::new(env!("CARGO_CRATE_NAME"))
        .multicall(true)
        .arg_required_else_help(true)
        .subcommand_value_name("APPLET")
        .subcommand_help_heading("APPLETS")
        .subcommand(Command::new("hostname").about("show hostname part of FQDN"))
        .subcommand(Command::new("dnsdomainname").about("show domain name part of FQDN"));

    match cmd.get_matches().subcommand_name() {
        Some("hostname") => println!("www"),
        Some("dnsdomainname") => println!("example.com"),
        _ => unreachable!("parser should ensure only valid subcommand names are used"),
    }
}
```

--------------------------------

### Help output for Arg::help example

Source: https://docs.rs/clap/latest/clap/builder/struct.Arg.html?search=

The output displayed when running the previous example with --help. It shows the usage line and the options list including the --config argument with its help text.

```text
helptest

Usage: helptest [OPTIONS]

Options:
    --config     Some help text describing the --config arg
-h, --help       Print help information
-V, --version    Print version information
```

--------------------------------

### Git-like CLI from examples/git.rs

Source: https://docs.rs/clap/latest/clap/builder/struct.Command.html?search=

Example from examples/git.rs (line 49) showing a git-like CLI with subcommands and external subcommands. Demonstrates flatten_help usage context.

```rust
fn cli() -> Command {
    Command::new("git")
        .about("A fictional versioning CLI")
        .subcommand_required(true)
        .arg_required_else_help(true)
        .allow_external_subcommands(true)
        .subcommand(
            Command::new("clone")
                .about("Clones repos")
                .arg(arg!(<REMOTE> "The remote to clone"))
                .arg_required_else_help(true),
        )
        .subcommand(
            Command::new("diff")
                .about("Compare two commits")
                .arg(arg!(base: [COMMIT]))
```

--------------------------------

### default_missing_value example from multicall-busybox.rs

Source: https://docs.rs/clap/latest/clap/struct.Arg.html?search=std%3A%3Avec

Example from `examples/multicall-busybox.rs` line 27, demonstrating the `default_missing_value` method on `Arg`. Shows a multicall binary with a `busybox` subcommand and an `install` argument that defaults to `/usr/local/bin` when the flag is present without a value. The example includes handling of subcommands and uses `exit` codes for `false` and `true`.

```rust
13fn main() {
14    let cmd = Command::new(env!("CARGO_CRATE_NAME"))
15        .multicall(true)
16        .subcommand(
17            Command::new("busybox")
18                .arg_required_else_help(true)
19                .subcommand_value_name("APPLET")
20                .subcommand_help_heading("APPLETS")
21                .arg(
22                    Arg::new("install")
23                        .long("install")
24                        .help("Install hardlinks for all subcommands in path")
25                        .exclusive(true)
26                        .action(ArgAction::Set)
27                        .default_missing_value("/usr/local/bin")
28                        .value_parser(value_parser!(PathBuf)),
29                )
30                .subcommands(applet_commands()),
31        )
32        .subcommands(applet_commands());
33
34    let matches = cmd.get_matches();
35    let mut subcommand = matches.subcommand();
36    if let Some(("busybox", cmd)) = subcommand {
37        if cmd.contains_id("install") {
38            unimplemented!("Make hardlinks to the executable here");
39        }
40        subcommand = cmd.subcommand();
41    }
42    match subcommand {
43        Some(("false", _)) => exit(1),
44        Some(("true", _)) => exit(0),
45        _ => unreachable!("parser should ensure only valid subcommand names are used"),
46    }
47}

```

--------------------------------

### value_names example with Command

Source: https://docs.rs/clap/latest/clap/struct.Arg.html?search=std%3A%3Avec

Complete example using value_names with two placeholders. Running this program prints the help output shown in the next block.

```rust
let m = Command::new("prog")
    .arg(Arg::new("io")
        .long("io-files")
        .value_names(["INFILE", "OUTFILE"]))
    .get_matches_from(vec![
        "prog", "--help"
    ]);
```

--------------------------------

### Augmenting Command Arguments

Source: https://docs.rs/clap/latest/clap/builder/struct.Arg.html

Example showing how to augment a Command with multiple Arg definitions for both initial setup and updates.

```rust
fn augment_args(cmd: Command) -> Command {
        cmd.arg(
            Arg::new("foo")
                .short('f')
                .long("foo")
                .action(ArgAction::SetTrue),
        )
        .arg(
            Arg::new("bar")
                .short('b')
                .long("bar")
                .action(ArgAction::SetTrue),
        )
        .arg(
            Arg::new("quuz")
                .short('q')
                .long("quuz")
                .action(ArgAction::Set),
        )
    }
    fn augment_args_for_update(cmd: Command) -> Command {
        cmd.arg(
            Arg::new("foo")
                .short('f')
                .long("foo")
                .action(ArgAction::SetTrue),
        )
        .arg(
            Arg::new("bar")
                .short('b')
                .long("bar")
                .action(ArgAction::SetTrue),
        )
        .arg(
            Arg::new("quuz")
                .short('q')
                .long("quuz")
                .action(ArgAction::Set),
        )
    }
```

--------------------------------

### REPL CLI with multicall and custom help templates (examples/repl.rs)

Source: https://docs.rs/clap/latest/clap/builder/struct.Command.html?search=std%3A%3Avec

Defines a REPL-style CLI using Command::new(

```rust
fn cli() -> Command {
    // strip out usage
    const PARSER_TEMPLATE: &str = "\
        {all-args}
    ";
    // strip out name/version
    const APPLET_TEMPLATE: &str = "\
        {about-with-newline}
\        {usage-heading}
    {usage}
\        
\        {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),
        )
}
```

--------------------------------

### Example with subcommands and version from pacman.rs

Source: https://docs.rs/clap/latest/clap/struct.Command.html

A real-world example from examples/pacman.rs defining a CLI with two subcommands, query and sync. It sets version "5.2.1", requires a subcommand, and shows how to use ArgAction and conflicts_with for argument relationships.

```rust
fn cli() -> Command {
    Command::new("pacman")
        .about("package manager utility")
        .version("5.2.1")
        .subcommand_required(true)
        .arg_required_else_help(true)
        // Query subcommand
        //
        // Only a few of its arguments are implemented below.
        .subcommand(
            Command::new("query")
                .short_flag('Q')
                .long_flag("query")
                .about("Query the package database.")
                .arg(
                    Arg::new("search")
                        .short('s')
                        .long("search")
                        .help("search locally installed packages for matching strings")
                        .conflicts_with("info")
                        .action(ArgAction::Set)
                        .num_args(1..),
                )
                .arg(
                    Arg::new("info")
                        .long("info")
                        .short('i')
                        .conflicts_with("search")
                        .help("view package information")
                        .action(ArgAction::Set)
                        .num_args(1..),
                ),
        )
        // Sync subcommand
        //
        // Only a few of its arguments are implemented below.
        .subcommand(
            Command::new("sync")
                .short_flag('S')
                .long_flag("sync")
                .about("Synchronize packages.")
                .arg(
                    Arg::new("search")
                        .short('s')
                        .long("search")
                        .conflicts_with("info")
                        .action(ArgAction::Set)
                        .num_args(1..)
                        .help("search remote repositories for matching strings"),
                )
                .arg(
                    Arg::new("info")
                        .long("info")
                        .conflicts_with("search")
                        .short('i')
                        .action(ArgAction::SetTrue)
                        .help("view package information"),
                )
                .arg(
                    Arg::new("package")
                        .help("packages")
                        .required_unless_present("search")
                        .action(ArgAction::Set)
                        .num_args(1..),
                ),
        )
}

```

--------------------------------

### Get name from PossibleValue in typed-derive example

Source: https://docs.rs/clap/latest/clap/builder/struct.PossibleValue.html?search=

Retrieves the name of a PossibleValue within a custom Display implementation using ValueEnum.

```rust
39    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
40        use clap::ValueEnum;
41
42        self.to_possible_value()
43            .expect("no values are skipped")
44            .get_name()
45            .fmt(f)
46    }
```

--------------------------------

### Create and configure a Command

Source: https://docs.rs/clap/latest/clap/builder/struct.Command.html

Example of creating a Command with author, version, about, an argument, and after_help, then calling get_matches.

```rust
let m = Command::new("My Program")
    .author("Me, me@mail.com")
    .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();

// Your program logic starts here...
```

--------------------------------

### Pacman-like CLI with required subcommands

Source: https://docs.rs/clap/latest/clap/builder/struct.Command.html?search=

Example from examples/pacman.rs (line 5). Starts defining a pacman-like CLI with required subcommands and arguments.

```rust
fn cli() -> Command {
    Command::new("pacman")
        .about("package manager utility")
        .version("5.2.1")
        .subcommand_required(true)
        .arg_required_else_help(true)
        // Query subcommand
        //
        // Only a few of its arguments are implemented below.
        .subcommand(
```

--------------------------------

### Render error with err.render()

Source: https://docs.rs/clap/latest/clap/error/struct.Error.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Use `err.render()` to get a `StyledStr` that can be printed or further processed. The example matches on `try_get_matches`, renders the error, and prints it with `println!`.

```rust
use clap::Command;

match Command::new("Command").try_get_matches() {
    Ok(matches) => {
        // do_something
    },
    Err(err) => {
        let err = err.render();
        println!("{err}");
        // do_something
    },
};
```

--------------------------------

### Include demo.rs example in documentation

Source: https://docs.rs/clap/latest/src/clap/lib.rs.html?search=

Shows how the documentation includes the demo.rs example file. The actual CLI definition is in the external file, not shown here.

```rust
# #[cfg(feature = "derive")] {
#![doc = include_str!("../examples/demo.rs")]
# }

```

--------------------------------

### Quick start example: Cli struct with Parser and Subcommand

Source: https://docs.rs/clap/latest/clap/_derive/_tutorial/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

A complete example of a CLI application using clap's derive API. It defines a Cli struct with options for name, config, debug count, and a subcommand, and demonstrates parsing and handling the arguments.

```rust
use std::path::PathBuf;

use clap::{Parser, Subcommand};

#[derive(Parser)]
#[command(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...
}
```

--------------------------------

### value_name example with Command and help output

Source: https://docs.rs/clap/latest/clap/struct.Arg.html?search=std%3A%3Avec

Complete example using value_name with help textpaces. Running this program prints the help output shown in the next block.

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

--------------------------------

### Retrieve subcommand matches with subcommand_matches

Source: https://docs.rs/clap/latest/clap/builder/struct.Command.html?search=std%3A%3Avec

Shows how to get the subcommand name and its matches after parsing. The example asserts the subcommand name is "sync" and that the 

```rust
assert_eq!(matches.subcommand_name().unwrap(), "sync");
let sync_matches = matches.subcommand_matches("sync").unwrap();
assert!(sync_matches.get_flag("search"));
```

--------------------------------

### Parser help and version output

Source: https://docs.rs/clap/latest/clap/_derive/_tutorial/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example output for the configured parser showing help and version information.

```text
$ 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
```

--------------------------------

### hostname-like CLI with Command::multicall (Builder API)

Source: https://docs.rs/clap/latest/clap/_cookbook/multicall_hostname/index.html?search=u32+-%3E+bool

Builder API example for a hostname-like multicall CLI. Requires the `unstable-doc` feature. Uses `Command::multicall(true)` and `arg_required_else_help(true)` to enforce subcommand selection. The example omits address configuration display and cannot demonstrate multicall behavior without the links setup.

```rust
use clap::Command;

fn main() {
    let cmd = Command::new(env!("CARGO_CRATE_NAME"))
        .multicall(true)
        .arg_required_else_help(true)
        .subcommand_value_name("APPLET")
        .subcommand_help_heading("APPLETS")
        .subcommand(Command::new("hostname").about("show hostname part of FQDN"))
        .subcommand(Command::new("dnsdomainname").about("show domain name part of FQDN"));

    match cmd.get_matches().subcommand_name() {
        Some("hostname") => println!("www"),
        Some("dnsdomainname") => println!("example.com"),
        _ => unreachable!("parser should ensure only valid subcommand names are used"),
    }
}
```

--------------------------------

### Get subcommand matches with subcommand_matches

Source: https://docs.rs/clap/latest/clap/parser/struct.ArgMatches.html

Shows how to retrieve the `ArgMatches` for a specific subcommand using `subcommand_matches`. The example builds a command with a parent flag and a subcommand argument, then verifies both are accessible simultaneously.

```rust
let app_m = Command::new("myprog")
    .arg(Arg::new("debug")
        .short('d')
        .action(ArgAction::SetTrue)
    )
    .subcommand(Command::new("test")
        .arg(Arg::new("opt")
            .long("option")
            .action(ArgAction::Set)))
    .get_matches_from(vec![
        "myprog", "-d", "test", "--option", "val"
    ]);

// Both parent commands, and child subcommands can have arguments present at the same times
assert!(app_m.get_flag("debug"));

// Get the subcommand's ArgMatches instance
if let Some(sub_m) = app_m.subcommand_matches("test") {
    // Use the struct like normal
    assert_eq!(sub_m.get_one::<String>("opt").map(|s| s.as_str()), Some("val"));
}
```

--------------------------------

### Include path parsing example

Source: https://docs.rs/clap/latest/clap/_cookbook/typed_derive/index.html?search=u32+-%3E+bool

Demonstrates parsing a directory path.

```text
$ typed-derive implicit -I../hello
Implicit(ImplicitParsers { optimization: None, include: Some("../hello"), bind: None, sleep: None, bump_level: None })
```
Tokens:
Raw