diff --git a/Cargo.toml b/Cargo.toml index 7b256e34314..12a48110170 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -311,6 +311,11 @@ name = "04_04_custom_derive" path = "examples/tutorial_derive/04_04_custom.rs" required-features = ["derive"] +[[example]] +name = "custom_bool" +path = "examples/derive_ref/custom_bool.rs" +required-features = ["derive"] + [profile.test] opt-level = 1 diff --git a/examples/derive_ref/README.md b/examples/derive_ref/README.md index b926ce1413d..871aa7b0387 100644 --- a/examples/derive_ref/README.md +++ b/examples/derive_ref/README.md @@ -191,6 +191,8 @@ In addition to the raw attributes, the following magic attributes are supported: | `Option>` | `0..` occurrences of argument | `.takes_value(true).required(false).multiple_occurrences(true)` | Notes: +- For custom type behavior, you can override the implied attributes/settings and/or set additional ones + - For example, see [custom_bool](./custom_bool.md) - `Option>` will be `None` instead of `vec![]` if no arguments are provided. - This gives the user some flexibility in designing their argument, like with `min_values(0)` diff --git a/examples/derive_ref/custom_bool.md b/examples/derive_ref/custom_bool.md new file mode 100644 index 00000000000..22ad500a7e9 --- /dev/null +++ b/examples/derive_ref/custom_bool.md @@ -0,0 +1,44 @@ +*Jump to [source](custom_bool.rs)* + +Example of overriding the magic `bool` behavior + +```bash +$ custom_bool --help +clap [..] + +A simple to use, efficient, and full-featured Command Line Argument Parser + +USAGE: + custom_bool[EXE] [OPTIONS] --foo + +ARGS: + + +OPTIONS: + --bar [default: false] + --foo + -h, --help Print help information + -V, --version Print version information +$ custom_bool +? failed +error: The following required arguments were not provided: + --foo + + +USAGE: + custom_bool [OPTIONS] --foo + +For more information try --help +$ custom_bool --foo true false +[examples/derive_ref/custom_bool.rs:31] opt = Opt { + foo: true, + bar: false, + boom: false, +} +$ custom_bool --foo true --bar true false +[examples/derive_ref/custom_bool.rs:31] opt = Opt { + foo: true, + bar: true, + boom: false, +} +``` diff --git a/examples/derive_ref/custom_bool.rs b/examples/derive_ref/custom_bool.rs new file mode 100644 index 00000000000..15efcd069d2 --- /dev/null +++ b/examples/derive_ref/custom_bool.rs @@ -0,0 +1,32 @@ +use clap::Parser; + +#[derive(Parser, Debug, PartialEq)] +#[clap(about, author, version)] +struct Opt { + // Default parser for `try_from_str` is FromStr::from_str. + // `impl FromStr for bool` parses `true` or `false` so this + // works as expected. + #[clap(long, parse(try_from_str))] + foo: bool, + + // Of course, this could be done with an explicit parser function. + #[clap(long, parse(try_from_str = true_or_false), default_value_t)] + bar: bool, + + // `bool` can be positional only with explicit `parse(...)` annotation + #[clap(parse(try_from_str))] + boom: bool, +} + +fn true_or_false(s: &str) -> Result { + match s { + "true" => Ok(true), + "false" => Ok(false), + _ => Err("expected `true` or `false`"), + } +} + +fn main() { + let opt = Opt::parse(); + dbg!(opt); +}