From e23800e10e104084a06e030b205b27620d230415 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Fri, 20 May 2022 19:52:04 -0500
Subject: [PATCH] doc(derive): Update for value_parser

---
 README.md                                        |  4 ++--
 examples/cargo-example-derive.rs                 |  2 +-
 examples/demo.rs                                 |  4 ++--
 examples/derive_ref/README.md                    |  2 +-
 examples/derive_ref/hand_subcommand.rs           |  2 ++
 examples/escaped-positional-derive.rs            |  4 ++--
 examples/git-derive.rs                           | 16 ++++++++++++----
 examples/tutorial_derive/01_quick.rs             |  5 +++--
 examples/tutorial_derive/02_app_settings.rs      |  4 ++--
 examples/tutorial_derive/02_apps.rs              |  4 ++--
 examples/tutorial_derive/02_crate.rs             |  4 ++--
 examples/tutorial_derive/03_01_flag_bool.rs      |  2 +-
 examples/tutorial_derive/03_02_option.rs         |  2 +-
 examples/tutorial_derive/03_03_positional.rs     |  1 +
 examples/tutorial_derive/03_04_subcommands.rs    |  5 ++++-
 .../tutorial_derive/03_04_subcommands_alt.rs     |  1 +
 examples/tutorial_derive/03_05_default_values.rs |  2 +-
 examples/tutorial_derive/04_01_enum.rs           |  2 +-
 examples/tutorial_derive/04_02_parse.rs          |  4 ++--
 examples/tutorial_derive/04_02_validate.rs       |  8 ++++----
 examples/tutorial_derive/04_03_relations.rs      |  8 ++++----
 examples/tutorial_derive/04_04_custom.rs         |  7 ++++---
 examples/tutorial_derive/05_01_assert.rs         |  4 ++--
 examples/tutorial_derive/README.md               |  6 ++++++
 examples/typed-derive.rs                         | 10 +++++-----
 25 files changed, 68 insertions(+), 45 deletions(-)

diff --git a/README.md b/README.md
index 94b9bb9ea9f..ae18179d336 100644
--- a/README.md
+++ b/README.md
@@ -44,11 +44,11 @@ use clap::Parser;
 #[clap(author, version, about, long_about = None)]
 struct Args {
     /// Name of the person to greet
-    #[clap(short, long)]
+    #[clap(short, long, value_parser)]
     name: String,
 
     /// Number of times to greet
-    #[clap(short, long, default_value_t = 1)]
+    #[clap(short, long, value_parser, default_value_t = 1)]
     count: u8,
 }
 
diff --git a/examples/cargo-example-derive.rs b/examples/cargo-example-derive.rs
index 1ee0a02551f..6667a4a7df9 100644
--- a/examples/cargo-example-derive.rs
+++ b/examples/cargo-example-derive.rs
@@ -12,7 +12,7 @@ enum Cargo {
 #[derive(clap::Args)]
 #[clap(author, version, about, long_about = None)]
 struct ExampleDerive {
-    #[clap(long, parse(from_os_str))]
+    #[clap(long, value_parser)]
     manifest_path: Option<std::path::PathBuf>,
 }
 
diff --git a/examples/demo.rs b/examples/demo.rs
index 262a81a2c1a..95748972444 100644
--- a/examples/demo.rs
+++ b/examples/demo.rs
@@ -7,11 +7,11 @@ use clap::Parser;
 #[clap(author, version, about, long_about = None)]
 struct Args {
     /// Name of the person to greet
-    #[clap(short, long)]
+    #[clap(short, long, value_parser)]
     name: String,
 
     /// Number of times to greet
-    #[clap(short, long, default_value_t = 1)]
+    #[clap(short, long, value_parser, default_value_t = 1)]
     count: u8,
 }
 
diff --git a/examples/derive_ref/README.md b/examples/derive_ref/README.md
index 78f9179dfc4..2cde95ff913 100644
--- a/examples/derive_ref/README.md
+++ b/examples/derive_ref/README.md
@@ -200,7 +200,7 @@ These correspond to a `clap::Arg`.
   - When `Option<T>`, the subcommand becomes optional
 - `from_global`: Read a `clap::Arg::global` argument (raw attribute), regardless of what subcommand you are in
 - `parse(<kind> [= <function>])`: `clap::Arg::validator` and `clap::ArgMatches::values_of_t`
-  - **Deprecated:** See `value_parser`
+  - **Deprecated:** except for `from_flag` or `from_occurrences`, instead use `value_parser`
   - Default: `try_from_str`
   - Warning: for `Path` / `OsString`, be sure to use `try_from_os_str`
   - See [Arg Types](#arg-types) for more details
diff --git a/examples/derive_ref/hand_subcommand.rs b/examples/derive_ref/hand_subcommand.rs
index 5afd9413271..d85a29493cd 100644
--- a/examples/derive_ref/hand_subcommand.rs
+++ b/examples/derive_ref/hand_subcommand.rs
@@ -3,12 +3,14 @@ use clap::{ArgMatches, Args as _, Command, FromArgMatches, Parser, Subcommand};
 
 #[derive(Parser, Debug)]
 struct AddArgs {
+    #[clap(value_parser)]
     name: Vec<String>,
 }
 #[derive(Parser, Debug)]
 struct RemoveArgs {
     #[clap(short, long)]
     force: bool,
+    #[clap(value_parser)]
     name: Vec<String>,
 }
 
diff --git a/examples/escaped-positional-derive.rs b/examples/escaped-positional-derive.rs
index 8038395aff2..dd52c090cc1 100644
--- a/examples/escaped-positional-derive.rs
+++ b/examples/escaped-positional-derive.rs
@@ -8,10 +8,10 @@ struct Cli {
     #[clap(short = 'f')]
     eff: bool,
 
-    #[clap(short = 'p', value_name = "PEAR")]
+    #[clap(short = 'p', value_name = "PEAR", value_parser)]
     pea: Option<String>,
 
-    #[clap(last = true)]
+    #[clap(last = true, value_parser)]
     slop: Vec<String>,
 }
 
diff --git a/examples/git-derive.rs b/examples/git-derive.rs
index 7e44edb1aff..ecbda3fe9d3 100644
--- a/examples/git-derive.rs
+++ b/examples/git-derive.rs
@@ -20,19 +20,21 @@ enum Commands {
     #[clap(arg_required_else_help = true)]
     Clone {
         /// The remote to clone
+        #[clap(value_parser)]
         remote: String,
     },
     /// pushes things
     #[clap(arg_required_else_help = true)]
     Push {
         /// The remote to target
+        #[clap(value_parser)]
         remote: String,
     },
     /// adds things
     #[clap(arg_required_else_help = true)]
     Add {
         /// Stuff to add
-        #[clap(required = true, parse(from_os_str))]
+        #[clap(required = true, value_parser)]
         path: Vec<PathBuf>,
     },
     Stash(Stash),
@@ -53,13 +55,19 @@ struct Stash {
 #[derive(Debug, Subcommand)]
 enum StashCommands {
     Push(StashPush),
-    Pop { stash: Option<String> },
-    Apply { stash: Option<String> },
+    Pop {
+        #[clap(value_parser)]
+        stash: Option<String>,
+    },
+    Apply {
+        #[clap(value_parser)]
+        stash: Option<String>,
+    },
 }
 
 #[derive(Debug, Args)]
 struct StashPush {
-    #[clap(short, long)]
+    #[clap(short, long, value_parser)]
     message: Option<String>,
 }
 
diff --git a/examples/tutorial_derive/01_quick.rs b/examples/tutorial_derive/01_quick.rs
index f840b8a9b2f..7bc55b2a62d 100644
--- a/examples/tutorial_derive/01_quick.rs
+++ b/examples/tutorial_derive/01_quick.rs
@@ -6,10 +6,11 @@ use clap::{Parser, Subcommand};
 #[clap(author, version, about, long_about = None)]
 struct Cli {
     /// Optional name to operate on
+    #[clap(value_parser)]
     name: Option<String>,
 
     /// Sets a custom config file
-    #[clap(short, long, parse(from_os_str), value_name = "FILE")]
+    #[clap(short, long, value_parser, value_name = "FILE")]
     config: Option<PathBuf>,
 
     /// Turn debugging information on
@@ -25,7 +26,7 @@ enum Commands {
     /// does testing things
     Test {
         /// lists test values
-        #[clap(short, long)]
+        #[clap(short, long, value_parser)]
         list: bool,
     },
 }
diff --git a/examples/tutorial_derive/02_app_settings.rs b/examples/tutorial_derive/02_app_settings.rs
index bccd353f602..87965cd36bb 100644
--- a/examples/tutorial_derive/02_app_settings.rs
+++ b/examples/tutorial_derive/02_app_settings.rs
@@ -6,9 +6,9 @@ use clap::{AppSettings, Parser};
 #[clap(allow_negative_numbers = true)]
 #[clap(global_setting(AppSettings::DeriveDisplayOrder))]
 struct Cli {
-    #[clap(long)]
+    #[clap(long, value_parser)]
     two: String,
-    #[clap(long)]
+    #[clap(long, value_parser)]
     one: String,
 }
 
diff --git a/examples/tutorial_derive/02_apps.rs b/examples/tutorial_derive/02_apps.rs
index 442e928a9f6..b97ce1eed6a 100644
--- a/examples/tutorial_derive/02_apps.rs
+++ b/examples/tutorial_derive/02_apps.rs
@@ -6,9 +6,9 @@ use clap::Parser;
 #[clap(version = "1.0")]
 #[clap(about = "Does awesome things", long_about = None)]
 struct Cli {
-    #[clap(long)]
+    #[clap(long, value_parser)]
     two: String,
-    #[clap(long)]
+    #[clap(long, value_parser)]
     one: String,
 }
 
diff --git a/examples/tutorial_derive/02_crate.rs b/examples/tutorial_derive/02_crate.rs
index 93f7888af31..df16468d0bb 100644
--- a/examples/tutorial_derive/02_crate.rs
+++ b/examples/tutorial_derive/02_crate.rs
@@ -3,9 +3,9 @@ use clap::Parser;
 #[derive(Parser)]
 #[clap(author, version, about, long_about = None)]
 struct Cli {
-    #[clap(long)]
+    #[clap(long, value_parser)]
     two: String,
-    #[clap(long)]
+    #[clap(long, value_parser)]
     one: String,
 }
 
diff --git a/examples/tutorial_derive/03_01_flag_bool.rs b/examples/tutorial_derive/03_01_flag_bool.rs
index 8b574b7481e..34c9a352a46 100644
--- a/examples/tutorial_derive/03_01_flag_bool.rs
+++ b/examples/tutorial_derive/03_01_flag_bool.rs
@@ -3,7 +3,7 @@ use clap::Parser;
 #[derive(Parser)]
 #[clap(author, version, about, long_about = None)]
 struct Cli {
-    #[clap(short, long)]
+    #[clap(short, long, value_parser)]
     verbose: bool,
 }
 
diff --git a/examples/tutorial_derive/03_02_option.rs b/examples/tutorial_derive/03_02_option.rs
index b09aadf20de..75b67afe753 100644
--- a/examples/tutorial_derive/03_02_option.rs
+++ b/examples/tutorial_derive/03_02_option.rs
@@ -3,7 +3,7 @@ use clap::Parser;
 #[derive(Parser)]
 #[clap(author, version, about, long_about = None)]
 struct Cli {
-    #[clap(short, long)]
+    #[clap(short, long, value_parser)]
     name: Option<String>,
 }
 
diff --git a/examples/tutorial_derive/03_03_positional.rs b/examples/tutorial_derive/03_03_positional.rs
index f7850ddccfe..7478951f1a8 100644
--- a/examples/tutorial_derive/03_03_positional.rs
+++ b/examples/tutorial_derive/03_03_positional.rs
@@ -3,6 +3,7 @@ use clap::Parser;
 #[derive(Parser)]
 #[clap(author, version, about, long_about = None)]
 struct Cli {
+    #[clap(value_parser)]
     name: Option<String>,
 }
 
diff --git a/examples/tutorial_derive/03_04_subcommands.rs b/examples/tutorial_derive/03_04_subcommands.rs
index 86cf444c21b..62a45a97eaf 100644
--- a/examples/tutorial_derive/03_04_subcommands.rs
+++ b/examples/tutorial_derive/03_04_subcommands.rs
@@ -11,7 +11,10 @@ struct Cli {
 #[derive(Subcommand)]
 enum Commands {
     /// Adds files to myapp
-    Add { name: Option<String> },
+    Add {
+        #[clap(value_parser)]
+        name: Option<String>,
+    },
 }
 
 fn main() {
diff --git a/examples/tutorial_derive/03_04_subcommands_alt.rs b/examples/tutorial_derive/03_04_subcommands_alt.rs
index 0a5b60682d4..b6124936c93 100644
--- a/examples/tutorial_derive/03_04_subcommands_alt.rs
+++ b/examples/tutorial_derive/03_04_subcommands_alt.rs
@@ -16,6 +16,7 @@ enum Commands {
 
 #[derive(Args)]
 struct Add {
+    #[clap(value_parser)]
     name: Option<String>,
 }
 
diff --git a/examples/tutorial_derive/03_05_default_values.rs b/examples/tutorial_derive/03_05_default_values.rs
index af4532bbc7d..10a1ec80880 100644
--- a/examples/tutorial_derive/03_05_default_values.rs
+++ b/examples/tutorial_derive/03_05_default_values.rs
@@ -3,7 +3,7 @@ use clap::Parser;
 #[derive(Parser)]
 #[clap(author, version, about, long_about = None)]
 struct Cli {
-    #[clap(default_value_t = String::from("alice"))]
+    #[clap(default_value_t = String::from("alice"), value_parser)]
     name: String,
 }
 
diff --git a/examples/tutorial_derive/04_01_enum.rs b/examples/tutorial_derive/04_01_enum.rs
index 3a2df391ffb..84b4cace495 100644
--- a/examples/tutorial_derive/04_01_enum.rs
+++ b/examples/tutorial_derive/04_01_enum.rs
@@ -4,7 +4,7 @@ use clap::{ArgEnum, Parser};
 #[clap(author, version, about, long_about = None)]
 struct Cli {
     /// What mode to run the program in
-    #[clap(arg_enum)]
+    #[clap(arg_enum, value_parser)]
     mode: Mode,
 }
 
diff --git a/examples/tutorial_derive/04_02_parse.rs b/examples/tutorial_derive/04_02_parse.rs
index 5f4cbadc045..6336a9cf155 100644
--- a/examples/tutorial_derive/04_02_parse.rs
+++ b/examples/tutorial_derive/04_02_parse.rs
@@ -4,8 +4,8 @@ use clap::Parser;
 #[clap(author, version, about, long_about = None)]
 struct Cli {
     /// Network port to use
-    #[clap(parse(try_from_str))]
-    port: usize,
+    #[clap(value_parser = clap::value_parser!(u16).range(1..))]
+    port: u16,
 }
 
 fn main() {
diff --git a/examples/tutorial_derive/04_02_validate.rs b/examples/tutorial_derive/04_02_validate.rs
index 434f40c869f..7dac79c9fb7 100644
--- a/examples/tutorial_derive/04_02_validate.rs
+++ b/examples/tutorial_derive/04_02_validate.rs
@@ -6,8 +6,8 @@ use clap::Parser;
 #[clap(author, version, about, long_about = None)]
 struct Cli {
     /// Network port to use
-    #[clap(parse(try_from_str=port_in_range))]
-    port: usize,
+    #[clap(value_parser = port_in_range)]
+    port: u16,
 }
 
 fn main() {
@@ -18,12 +18,12 @@ fn main() {
 
 const PORT_RANGE: RangeInclusive<usize> = 1..=65535;
 
-fn port_in_range(s: &str) -> Result<usize, String> {
+fn port_in_range(s: &str) -> Result<u16, String> {
     let port: usize = s
         .parse()
         .map_err(|_| format!("`{}` isn't a port number", s))?;
     if PORT_RANGE.contains(&port) {
-        Ok(port)
+        Ok(port as u16)
     } else {
         Err(format!(
             "Port not in range {}-{}",
diff --git a/examples/tutorial_derive/04_03_relations.rs b/examples/tutorial_derive/04_03_relations.rs
index f0e1e5913ba..32b85805658 100644
--- a/examples/tutorial_derive/04_03_relations.rs
+++ b/examples/tutorial_derive/04_03_relations.rs
@@ -9,7 +9,7 @@ use clap::{ArgGroup, Parser};
         ))]
 struct Cli {
     /// set version manually
-    #[clap(long, value_name = "VER")]
+    #[clap(long, value_name = "VER", value_parser)]
     set_ver: Option<String>,
 
     /// auto inc major
@@ -25,14 +25,14 @@ struct Cli {
     patch: bool,
 
     /// some regular input
-    #[clap(group = "input")]
+    #[clap(group = "input", value_parser)]
     input_file: Option<String>,
 
     /// some special input argument
-    #[clap(long, group = "input")]
+    #[clap(long, group = "input", value_parser)]
     spec_in: Option<String>,
 
-    #[clap(short, requires = "input")]
+    #[clap(short, requires = "input", value_parser)]
     config: Option<String>,
 }
 
diff --git a/examples/tutorial_derive/04_04_custom.rs b/examples/tutorial_derive/04_04_custom.rs
index a03345b8297..d163e20ef24 100644
--- a/examples/tutorial_derive/04_04_custom.rs
+++ b/examples/tutorial_derive/04_04_custom.rs
@@ -4,7 +4,7 @@ use clap::{CommandFactory, ErrorKind, Parser};
 #[clap(author, version, about, long_about = None)]
 struct Cli {
     /// set version manually
-    #[clap(long, value_name = "VER")]
+    #[clap(long, value_name = "VER", value_parser)]
     set_ver: Option<String>,
 
     /// auto inc major
@@ -20,13 +20,14 @@ struct Cli {
     patch: bool,
 
     /// some regular input
+    #[clap(value_parser)]
     input_file: Option<String>,
 
     /// some special input argument
-    #[clap(long)]
+    #[clap(long, value_parser)]
     spec_in: Option<String>,
 
-    #[clap(short)]
+    #[clap(short, value_parser)]
     config: Option<String>,
 }
 
diff --git a/examples/tutorial_derive/05_01_assert.rs b/examples/tutorial_derive/05_01_assert.rs
index 12fdba9b923..f5fa3f6c599 100644
--- a/examples/tutorial_derive/05_01_assert.rs
+++ b/examples/tutorial_derive/05_01_assert.rs
@@ -4,8 +4,8 @@ use clap::Parser;
 #[clap(author, version, about, long_about = None)]
 struct Cli {
     /// Network port to use
-    #[clap(parse(try_from_str))]
-    port: usize,
+    #[clap(value_parser)]
+    port: u16,
 }
 
 fn main() {
diff --git a/examples/tutorial_derive/README.md b/examples/tutorial_derive/README.md
index 706e76c09e7..01b122421b6 100644
--- a/examples/tutorial_derive/README.md
+++ b/examples/tutorial_derive/README.md
@@ -453,6 +453,12 @@ error: Invalid value "foobar" for '<PORT>': invalid digit found in string
 
 For more information try --help
 
+$ 04_02_parse_derive 0
+? failed
+error: Invalid value "0" for '<PORT>': 0 is not in 1..=65535
+
+For more information try --help
+
 ```
 
 A custom parser can be used to improve the error messages or provide additional validation:
diff --git a/examples/typed-derive.rs b/examples/typed-derive.rs
index 237bbe15e8d..b99370780df 100644
--- a/examples/typed-derive.rs
+++ b/examples/typed-derive.rs
@@ -6,23 +6,23 @@ use std::error::Error;
 #[derive(Parser, Debug)]
 struct Args {
     /// Implicitly using `std::str::FromStr`
-    #[clap(short = 'O')]
+    #[clap(short = 'O', value_parser)]
     optimization: Option<usize>,
 
     /// Allow invalid UTF-8 paths
-    #[clap(short = 'I', parse(from_os_str), value_name = "DIR", value_hint = clap::ValueHint::DirPath)]
+    #[clap(short = 'I', value_parser, value_name = "DIR", value_hint = clap::ValueHint::DirPath)]
     include: Option<std::path::PathBuf>,
 
     /// Handle IP addresses
-    #[clap(long)]
+    #[clap(long, value_parser)]
     bind: Option<std::net::IpAddr>,
 
     /// Allow human-readable durations
-    #[clap(long)]
+    #[clap(long, value_parser)]
     sleep: Option<humantime::Duration>,
 
     /// Hand-written parser for tuples
-    #[clap(short = 'D', parse(try_from_str = parse_key_val), multiple_occurrences(true))]
+    #[clap(short = 'D', value_parser = parse_key_val::<String, i32>, multiple_occurrences(true))]
     defines: Vec<(String, i32)>,
 }