pub struct ValueParser(/* private fields */);
Expand description
Parse/validate argument values
Specified with Arg::value_parser
.
ValueParser
defines how to convert a raw argument value into a validated and typed value for
use within an application.
See
value_parser!
for automatically selecting an implementation for a given typeValueParser::new
for additionalTypedValueParser
that can be used
§Example
let mut cmd = clap::Command::new("raw")
.arg(
clap::Arg::new("color")
.long("color")
.value_parser(["always", "auto", "never"])
.default_value("auto")
)
.arg(
clap::Arg::new("hostname")
.long("hostname")
.value_parser(clap::builder::NonEmptyStringValueParser::new())
.action(clap::ArgAction::Set)
.required(true)
)
.arg(
clap::Arg::new("port")
.long("port")
.value_parser(clap::value_parser!(u16).range(3000..))
.action(clap::ArgAction::Set)
.required(true)
);
let m = cmd.try_get_matches_from_mut(
["cmd", "--hostname", "rust-lang.org", "--port", "3001"]
).unwrap();
let color: &String = m.get_one("color")
.expect("default");
assert_eq!(color, "auto");
let hostname: &String = m.get_one("hostname")
.expect("required");
assert_eq!(hostname, "rust-lang.org");
let port: u16 = *m.get_one("port")
.expect("required");
assert_eq!(port, 3001);
Implementations§
source§impl ValueParser
impl ValueParser
sourcepub fn new<P>(other: P) -> ValueParserwhere
P: TypedValueParser,
pub fn new<P>(other: P) -> ValueParserwhere
P: TypedValueParser,
Custom parser for argument values
Pre-existing TypedValueParser
implementations include:
Fn(&str) -> Result<T, E>
EnumValueParser
andPossibleValuesParser
for static enumerated valuesBoolishValueParser
andFalseyValueParser
for alternativebool
implementationsRangedI64ValueParser
andRangedU64ValueParser
NonEmptyStringValueParser
§Example
type EnvVar = (String, Option<String>);
fn parse_env_var(env: &str) -> Result<EnvVar, std::io::Error> {
if let Some((var, value)) = env.split_once('=') {
Ok((var.to_owned(), Some(value.to_owned())))
} else {
Ok((env.to_owned(), None))
}
}
let mut cmd = clap::Command::new("raw")
.arg(
clap::Arg::new("env")
.value_parser(clap::builder::ValueParser::new(parse_env_var))
.required(true)
);
let m = cmd.try_get_matches_from_mut(["cmd", "key=value"]).unwrap();
let port: &EnvVar = m.get_one("env")
.expect("required");
assert_eq!(*port, ("key".into(), Some("value".into())));
sourcepub const fn bool() -> ValueParser
pub const fn bool() -> ValueParser
bool
parser for argument values
See also:
BoolishValueParser
for different human readable bool representationsFalseyValueParser
for assuming non-false is true
§Example
let mut cmd = clap::Command::new("raw")
.arg(
clap::Arg::new("download")
.value_parser(clap::value_parser!(bool))
.required(true)
);
let m = cmd.try_get_matches_from_mut(["cmd", "true"]).unwrap();
let port: bool = *m.get_one("download")
.expect("required");
assert_eq!(port, true);
assert!(cmd.try_get_matches_from_mut(["cmd", "forever"]).is_err());
sourcepub const fn string() -> ValueParser
pub const fn string() -> ValueParser
String
parser for argument values
See also:
§Example
let mut cmd = clap::Command::new("raw")
.arg(
clap::Arg::new("port")
.value_parser(clap::value_parser!(String))
.required(true)
);
let m = cmd.try_get_matches_from_mut(["cmd", "80"]).unwrap();
let port: &String = m.get_one("port")
.expect("required");
assert_eq!(port, "80");
sourcepub const fn os_string() -> ValueParser
pub const fn os_string() -> ValueParser
OsString
parser for argument values
§Example
use std::ffi::OsString;
use std::os::unix::ffi::{OsStrExt,OsStringExt};
let r = Command::new("myprog")
.arg(
Arg::new("arg")
.required(true)
.value_parser(ValueParser::os_string())
)
.try_get_matches_from(vec![
OsString::from("myprog"),
OsString::from_vec(vec![0xe9])
]);
assert!(r.is_ok());
let m = r.unwrap();
let arg: &OsString = m.get_one("arg")
.expect("required");
assert_eq!(arg.as_bytes(), &[0xe9]);
sourcepub const fn path_buf() -> ValueParser
pub const fn path_buf() -> ValueParser
PathBuf
parser for argument values
§Example
let mut cmd = clap::Command::new("raw")
.arg(
clap::Arg::new("output")
.value_parser(clap::value_parser!(PathBuf))
.required(true)
);
let m = cmd.try_get_matches_from_mut(["cmd", "hello.txt"]).unwrap();
let port: &PathBuf = m.get_one("output")
.expect("required");
assert_eq!(port, Path::new("hello.txt"));
assert!(cmd.try_get_matches_from_mut(["cmd", ""]).is_err());
source§impl ValueParser
impl ValueParser
sourcepub fn possible_values(
&self,
) -> Option<Box<dyn Iterator<Item = PossibleValue> + '_>>
pub fn possible_values( &self, ) -> Option<Box<dyn Iterator<Item = PossibleValue> + '_>>
Reflect on enumerated value properties
Error checking should not be done with this; it is mostly targeted at user-facing applications like errors and completion.
Trait Implementations§
source§impl Clone for ValueParser
impl Clone for ValueParser
source§fn clone(&self) -> ValueParser
fn clone(&self) -> ValueParser
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for ValueParser
impl Debug for ValueParser
source§impl<P, const C: usize> From<[P; C]> for ValueParserwhere
P: Into<PossibleValue>,
impl<P, const C: usize> From<[P; C]> for ValueParserwhere
P: Into<PossibleValue>,
Create a ValueParser
with PossibleValuesParser
See PossibleValuesParser
for more flexibility in creating the
PossibleValue
s.
§Examples
let mut cmd = clap::Command::new("raw")
.arg(
clap::Arg::new("color")
.long("color")
.value_parser(["always", "auto", "never"])
.default_value("auto")
);
let m = cmd.try_get_matches_from_mut(
["cmd", "--color", "never"]
).unwrap();
let color: &String = m.get_one("color")
.expect("default");
assert_eq!(color, "never");
source§fn from(values: [P; C]) -> ValueParser
fn from(values: [P; C]) -> ValueParser
source§impl<P> From<P> for ValueParser
impl<P> From<P> for ValueParser
Convert a TypedValueParser
to ValueParser
§Example
let mut cmd = clap::Command::new("raw")
.arg(
clap::Arg::new("hostname")
.long("hostname")
.value_parser(clap::builder::NonEmptyStringValueParser::new())
.action(clap::ArgAction::Set)
.required(true)
);
let m = cmd.try_get_matches_from_mut(
["cmd", "--hostname", "rust-lang.org"]
).unwrap();
let hostname: &String = m.get_one("hostname")
.expect("required");
assert_eq!(hostname, "rust-lang.org");
source§fn from(p: P) -> ValueParser
fn from(p: P) -> ValueParser
source§impl From<Range<i64>> for ValueParser
impl From<Range<i64>> for ValueParser
Create an i64
ValueParser
from a N..M
range
See RangedI64ValueParser
for more control over the output type.
See also RangedU64ValueParser
§Examples
let mut cmd = clap::Command::new("raw")
.arg(
clap::Arg::new("port")
.long("port")
.value_parser(3000..4000)
.action(clap::ArgAction::Set)
.required(true)
);
let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap();
let port: i64 = *m.get_one("port")
.expect("required");
assert_eq!(port, 3001);
source§impl From<RangeFrom<i64>> for ValueParser
impl From<RangeFrom<i64>> for ValueParser
Create an i64
ValueParser
from a N..
range
See RangedI64ValueParser
for more control over the output type.
See also RangedU64ValueParser
§Examples
let mut cmd = clap::Command::new("raw")
.arg(
clap::Arg::new("port")
.long("port")
.value_parser(3000..)
.action(clap::ArgAction::Set)
.required(true)
);
let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap();
let port: i64 = *m.get_one("port")
.expect("required");
assert_eq!(port, 3001);
source§impl From<RangeFull> for ValueParser
impl From<RangeFull> for ValueParser
Create an i64
ValueParser
from a ..
range
See RangedI64ValueParser
for more control over the output type.
See also RangedU64ValueParser
§Examples
let mut cmd = clap::Command::new("raw")
.arg(
clap::Arg::new("port")
.long("port")
.value_parser(..)
.action(clap::ArgAction::Set)
.required(true)
);
let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap();
let port: i64 = *m.get_one("port")
.expect("required");
assert_eq!(port, 3001);
source§fn from(value: RangeFull) -> ValueParser
fn from(value: RangeFull) -> ValueParser
source§impl From<RangeInclusive<i64>> for ValueParser
impl From<RangeInclusive<i64>> for ValueParser
Create an i64
ValueParser
from a N..=M
range
See RangedI64ValueParser
for more control over the output type.
See also RangedU64ValueParser
§Examples
let mut cmd = clap::Command::new("raw")
.arg(
clap::Arg::new("port")
.long("port")
.value_parser(3000..=4000)
.action(clap::ArgAction::Set)
.required(true)
);
let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap();
let port: i64 = *m.get_one("port")
.expect("required");
assert_eq!(port, 3001);
source§fn from(value: RangeInclusive<i64>) -> ValueParser
fn from(value: RangeInclusive<i64>) -> ValueParser
source§impl From<RangeTo<i64>> for ValueParser
impl From<RangeTo<i64>> for ValueParser
Create an i64
ValueParser
from a ..M
range
See RangedI64ValueParser
for more control over the output type.
See also RangedU64ValueParser
§Examples
let mut cmd = clap::Command::new("raw")
.arg(
clap::Arg::new("port")
.long("port")
.value_parser(..3000)
.action(clap::ArgAction::Set)
.required(true)
);
let m = cmd.try_get_matches_from_mut(["cmd", "--port", "80"]).unwrap();
let port: i64 = *m.get_one("port")
.expect("required");
assert_eq!(port, 80);
source§impl From<RangeToInclusive<i64>> for ValueParser
impl From<RangeToInclusive<i64>> for ValueParser
Create an i64
ValueParser
from a ..=M
range
See RangedI64ValueParser
for more control over the output type.
See also RangedU64ValueParser
§Examples
let mut cmd = clap::Command::new("raw")
.arg(
clap::Arg::new("port")
.long("port")
.value_parser(..=3000)
.action(clap::ArgAction::Set)
.required(true)
);
let m = cmd.try_get_matches_from_mut(["cmd", "--port", "80"]).unwrap();
let port: i64 = *m.get_one("port")
.expect("required");
assert_eq!(port, 80);
source§fn from(value: RangeToInclusive<i64>) -> ValueParser
fn from(value: RangeToInclusive<i64>) -> ValueParser
source§impl<P> From<Vec<P>> for ValueParserwhere
P: Into<PossibleValue>,
impl<P> From<Vec<P>> for ValueParserwhere
P: Into<PossibleValue>,
Create a ValueParser
with PossibleValuesParser
See PossibleValuesParser
for more flexibility in creating the
PossibleValue
s.
§Examples
let possible = vec!["always", "auto", "never"];
let mut cmd = clap::Command::new("raw")
.arg(
clap::Arg::new("color")
.long("color")
.value_parser(possible)
.default_value("auto")
);
let m = cmd.try_get_matches_from_mut(
["cmd", "--color", "never"]
).unwrap();
let color: &String = m.get_one("color")
.expect("default");
assert_eq!(color, "never");
source§fn from(values: Vec<P>) -> ValueParser
fn from(values: Vec<P>) -> ValueParser
source§impl IntoResettable<ValueParser> for Option<ValueParser>
impl IntoResettable<ValueParser> for Option<ValueParser>
source§fn into_resettable(self) -> Resettable<ValueParser>
fn into_resettable(self) -> Resettable<ValueParser>
Auto Trait Implementations§
impl Freeze for ValueParser
impl !RefUnwindSafe for ValueParser
impl Send for ValueParser
impl Sync for ValueParser
impl Unpin for ValueParser
impl !UnwindSafe for ValueParser
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)