docs(derive): Show how to override special types

Fixes #3107

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
 

examples/derive_ref/README.md

@@ -191,6 +191,8 @@ In addition to the raw attributes, the following magic attributes are supported:
 | `Option<Vec<T>>`    | `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<Vec<T>>` 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)`
 

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 <FOO> <BOOM>
+
+ARGS:
+    <BOOM>    
+
+OPTIONS:
+        --bar <BAR>    [default: false]
+        --foo <FOO>    
+    -h, --help         Print help information
+    -V, --version      Print version information
+$ custom_bool
+? failed
+error: The following required arguments were not provided:
+    --foo <FOO>
+    <BOOM>
+
+USAGE:
+    custom_bool [OPTIONS] --foo <FOO> <BOOM>
+
+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,
+}
+```

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<bool, &'static str> {
+    match s {
+        "true" => Ok(true),
+        "false" => Ok(false),
+        _ => Err("expected `true` or `false`"),
+    }
+}
+
+fn main() {
+    let opt = Opt::parse();
+    dbg!(opt);
+}