From c99adcc6c9fd1ecd7ed20fe6bd027ee15660f7d9 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Tue, 7 Dec 2021 19:01:55 -0600
Subject: [PATCH] docs: Add key-value derive example

This is carried over from the clap_derive examples.  Looking over the
other examples, I feel like they are covered by other examples or by the
derive reference.  We should call out deny missing docs though.
---
 Cargo.toml                  |  4 ++++
 examples/README.md          |  1 +
 examples/keyvalue_derive.md | 25 +++++++++++++++++++++++++
 examples/keyvalue_derive.rs | 27 +++++++++++++++++++++++++++
 4 files changed, 57 insertions(+)
 create mode 100644 examples/keyvalue_derive.md
 create mode 100644 examples/keyvalue_derive.rs

diff --git a/Cargo.toml b/Cargo.toml
index 0c44541d..4d388a2d 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -136,6 +136,10 @@ required-features = ["derive"]
 name = "git_derive"
 required-features = ["derive"]
 
+[[example]]
+name = "keyvalue_derive"
+required-features = ["derive"]
+
 [[example]]
 name = "busybox"
 path = "examples/multicall_busybox.rs"
diff --git a/examples/README.md b/examples/README.md
index 9cad26e9..6138cb16 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -1,6 +1,7 @@
 # Examples
 
 - Basic demo: [derive](demo.md)
+- Key-value pair arguments: [derive](keyvalue_derive.md)
 - git-like interface: [builder](git.md), [derive](git_derive.md)
 - pacman-like interface: [builder](git.md)
 - Escaped positionals with `--`: [builder](escaped_positional.md), [derive](escaped_positional_derive.md)
diff --git a/examples/keyvalue_derive.md b/examples/keyvalue_derive.md
new file mode 100644
index 00000000..017bcb44
--- /dev/null
+++ b/examples/keyvalue_derive.md
@@ -0,0 +1,25 @@
+*Jump to [source](keyvalue_derive.rs)*
+
+```bash
+$ keyvalue_derive --help
+clap 
+
+USAGE:
+    keyvalue_derive[EXE] [OPTIONS]
+
+OPTIONS:
+    -D <DEFINES>        
+    -h, --help          Print help information
+$ keyvalue_derive -D Foo=10 -D Alice=30
+Args { defines: [("Foo", 10), ("Alice", 30)] }
+$ keyvalue_derive -D Foo
+? failed
+error: Invalid value for '-D <DEFINES>': invalid KEY=value: no `=` found in `Foo`
+
+For more information try --help
+$ keyvalue_derive -D Foo=Bar
+? failed
+error: Invalid value for '-D <DEFINES>': invalid digit found in string
+
+For more information try --help
+```
diff --git a/examples/keyvalue_derive.rs b/examples/keyvalue_derive.rs
new file mode 100644
index 00000000..5324d89d
--- /dev/null
+++ b/examples/keyvalue_derive.rs
@@ -0,0 +1,27 @@
+use clap::Parser;
+use std::error::Error;
+
+#[derive(Parser, Debug)]
+struct Args {
+    #[clap(short = 'D', parse(try_from_str = parse_key_val), multiple_occurrences(true))]
+    defines: Vec<(String, i32)>,
+}
+
+/// Parse a single key-value pair
+fn parse_key_val<T, U>(s: &str) -> Result<(T, U), Box<dyn Error + Send + Sync + 'static>>
+where
+    T: std::str::FromStr,
+    T::Err: Error + Send + Sync + 'static,
+    U: std::str::FromStr,
+    U::Err: Error + Send + Sync + 'static,
+{
+    let pos = s
+        .find('=')
+        .ok_or_else(|| format!("invalid KEY=value: no `=` found in `{}`", s))?;
+    Ok((s[..pos].parse()?, s[pos + 1..].parse()?))
+}
+
+fn main() {
+    let args = Args::parse();
+    println!("{:?}", args);
+}