docs(cookbook): Provide a custom TypedValueParser

Author: epage

Cargo.lock

@@ -199,6 +199,7 @@ snapbox = { version = "0.6.16", features = ["term-svg"] }
 shlex = "1.3.0"
 automod = "1.0.14"
 clap-cargo = { version = "0.15.0", default-features = false }
+semver = "1.0.26"
 
 [[example]]
 name = "demo"

Cargo.toml

@@ -0,0 +1,40 @@
+Help:
+```console
+$ typed-derive custom --help
+Usage: typed-derive custom [OPTIONS]
+
+Options:
+      --target-version <TARGET_VERSION>
+          Hand-implement `TypedValueParser`
+
+          Possible values:
+          - major: Increase the major version (x.0.0)
+          - minor: Increase the minor version (x.y.0)
+          - patch: Increase the patch version (x.y.z)
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+```
+
+Defines (key-value pairs)
+```console
+$ typed-derive custom --target-version major
+Custom(CustomParser { target_version: Some(Relative(Major)) })
+
+$ typed-derive custom --target-version 10.0.0
+Custom(CustomParser { target_version: Some(Absolute(Version { major: 10, minor: 0, patch: 0 })) })
+
+$ typed-derive custom --target-version 10
+? failed
+error: invalid value '10' for '--target-version <TARGET_VERSION>': unexpected end of input while parsing major version number
+
+For more information, try '--help'.
+
+$ typed-derive custom --target-version blue
+? failed
+error: invalid value 'blue' for '--target-version <TARGET_VERSION>': unexpected character 'b' while parsing major version number
+
+For more information, try '--help'.
+
+```

examples/typed-derive/custom.md

@@ -0,0 +1,83 @@
+use clap::Args;
+
+use crate::implicit::BumpLevel;
+
+#[derive(Args, Debug)]
+pub(crate) struct CustomParser {
+    /// Hand-implement `TypedValueParser`
+    #[arg(long)]
+    target_version: Option<TargetVersion>,
+}
+
+/// Enum or custom value
+#[derive(Clone, Debug)]
+pub(crate) enum TargetVersion {
+    Relative(BumpLevel),
+    Absolute(semver::Version),
+}
+
+impl std::fmt::Display for TargetVersion {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> {
+        match self {
+            TargetVersion::Relative(bump_level) => {
+                write!(f, "{bump_level}")
+            }
+            TargetVersion::Absolute(version) => {
+                write!(f, "{version}")
+            }
+        }
+    }
+}
+
+impl std::str::FromStr for TargetVersion {
+    type Err = String;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        if let Ok(bump_level) = BumpLevel::from_str(s) {
+            Ok(TargetVersion::Relative(bump_level))
+        } else {
+            Ok(TargetVersion::Absolute(
+                semver::Version::parse(s).map_err(|e| e.to_string())?,
+            ))
+        }
+    }
+}
+
+/// Default to `TargetVersionParser` for `TargetVersion`, instead of `FromStr`
+impl clap::builder::ValueParserFactory for TargetVersion {
+    type Parser = TargetVersionParser;
+
+    fn value_parser() -> Self::Parser {
+        TargetVersionParser
+    }
+}
+
+#[derive(Copy, Clone)]
+pub(crate) struct TargetVersionParser;
+
+impl clap::builder::TypedValueParser for TargetVersionParser {
+    type Value = TargetVersion;
+
+    fn parse_ref(
+        &self,
+        cmd: &clap::Command,
+        arg: Option<&clap::Arg>,
+        value: &std::ffi::OsStr,
+    ) -> Result<Self::Value, clap::Error> {
+        let inner_parser = <TargetVersion as std::str::FromStr>::from_str;
+        inner_parser.parse_ref(cmd, arg, value)
+    }
+
+    fn possible_values(
+        &self,
+    ) -> Option<Box<dyn Iterator<Item = clap::builder::PossibleValue> + '_>> {
+        let inner_parser = clap::builder::EnumValueParser::<BumpLevel>::new();
+        #[allow(clippy::needless_collect)] // Erasing a lifetime
+        inner_parser.possible_values().map(|ps| {
+            let ps = ps.collect::<Vec<_>>();
+            let ps: Box<dyn Iterator<Item = clap::builder::PossibleValue> + '_> =
+                Box::new(ps.into_iter());
+            ps
+        })
+    }
+}

examples/typed-derive/custom.rs

@@ -1,6 +1,7 @@
 use clap::Parser;
 
 mod builtin;
+mod custom;
 mod fn_parser;
 mod foreign_crate;
 mod implicit;
@@ -11,6 +12,7 @@ enum Cli {
     Implicit(implicit::ImplicitParsers),
     Builtin(builtin::BuiltInParsers),
     FnParser(fn_parser::FnParser),
+    Custom(custom::CustomParser),
 }
 
 fn main() {

examples/typed-derive/main.rs

@@ -18,10 +18,18 @@
 //!
 #![doc = include_str!("../../examples/typed-derive/builtin.md")]
 //!
-//! ## Custom [`TypedValueParser`][crate::builder::TypedValueParser]
+//! ## Custom parser function
 //!
 //! ```rust
 #![doc = include_str!("../../examples/typed-derive/fn_parser.rs")]
 //! ```
 //!
 #![doc = include_str!("../../examples/typed-derive/fn_parser.md")]
+//!
+//! ## Custom [`TypedValueParser`][crate::builder::TypedValueParser]
+//!
+//! ```rust
+#![doc = include_str!("../../examples/typed-derive/custom.rs")]
+//! ```
+//!
+#![doc = include_str!("../../examples/typed-derive/custom.md")]