Skip to content

Commit

Permalink
doc(derive): Update for value_parser
Browse files Browse the repository at this point in the history
  • Loading branch information
epage committed May 21, 2022
1 parent 852a1b1 commit e23800e
Show file tree
Hide file tree
Showing 25 changed files with 68 additions and 45 deletions.
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}
Expand Down
2 changes: 1 addition & 1 deletion examples/cargo-example-derive.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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>,
}

Expand Down
4 changes: 2 additions & 2 deletions examples/demo.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}

Expand Down
2 changes: 1 addition & 1 deletion examples/derive_ref/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions examples/derive_ref/hand_subcommand.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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>,
}

Expand Down
4 changes: 2 additions & 2 deletions examples/escaped-positional-derive.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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>,
}

Expand Down
16 changes: 12 additions & 4 deletions examples/git-derive.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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),
Expand All @@ -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>,
}

Expand Down
5 changes: 3 additions & 2 deletions examples/tutorial_derive/01_quick.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -25,7 +26,7 @@ enum Commands {
/// does testing things
Test {
/// lists test values
#[clap(short, long)]
#[clap(short, long, value_parser)]
list: bool,
},
}
Expand Down
4 changes: 2 additions & 2 deletions examples/tutorial_derive/02_app_settings.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}

Expand Down
4 changes: 2 additions & 2 deletions examples/tutorial_derive/02_apps.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}

Expand Down
4 changes: 2 additions & 2 deletions examples/tutorial_derive/02_crate.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}

Expand Down
2 changes: 1 addition & 1 deletion examples/tutorial_derive/03_01_flag_bool.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}

Expand Down
2 changes: 1 addition & 1 deletion examples/tutorial_derive/03_02_option.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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>,
}

Expand Down
1 change: 1 addition & 0 deletions examples/tutorial_derive/03_03_positional.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ use clap::Parser;
#[derive(Parser)]
#[clap(author, version, about, long_about = None)]
struct Cli {
#[clap(value_parser)]
name: Option<String>,
}

Expand Down
5 changes: 4 additions & 1 deletion examples/tutorial_derive/03_04_subcommands.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand Down
1 change: 1 addition & 0 deletions examples/tutorial_derive/03_04_subcommands_alt.rs
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ enum Commands {

#[derive(Args)]
struct Add {
#[clap(value_parser)]
name: Option<String>,
}

Expand Down
2 changes: 1 addition & 1 deletion examples/tutorial_derive/03_05_default_values.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}

Expand Down
2 changes: 1 addition & 1 deletion examples/tutorial_derive/04_01_enum.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
}

Expand Down
4 changes: 2 additions & 2 deletions examples/tutorial_derive/04_02_parse.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand Down
8 changes: 4 additions & 4 deletions examples/tutorial_derive/04_02_validate.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand All @@ -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 {}-{}",
Expand Down
8 changes: 4 additions & 4 deletions examples/tutorial_derive/04_03_relations.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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>,
}

Expand Down
7 changes: 4 additions & 3 deletions examples/tutorial_derive/04_04_custom.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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>,
}

Expand Down
4 changes: 2 additions & 2 deletions examples/tutorial_derive/05_01_assert.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand Down
6 changes: 6 additions & 0 deletions examples/tutorial_derive/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
10 changes: 5 additions & 5 deletions examples/typed-derive.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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)>,
}

Expand Down

0 comments on commit e23800e

Please sign in to comment.