Struct clap::builder::ValueParser
source · pub struct ValueParser(_);
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())
.takes_value(true)
.required(true)
)
.arg(
clap::Arg::new("port")
.long("port")
.value_parser(clap::value_parser!(u16).range(3000..))
.takes_value(true)
.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) -> Selfwhere
P: TypedValueParser,
P::Value: Send + Sync + Clone,
pub fn new<P>(other: P) -> Selfwhere
P: TypedValueParser,
P::Value: Send + Sync + Clone,
Custom parser for argument values
To create a custom parser, see TypedValueParser
Pre-existing implementations include:
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() -> Self
pub const fn bool() -> Self
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() -> Self
pub const fn string() -> Self
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() -> Self
pub const fn os_string() -> Self
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() -> Self
pub const fn path_buf() -> Self
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<'static>> + '_>>
pub fn possible_values(
&self
) -> Option<Box<dyn Iterator<Item = PossibleValue<'static>> + '_>>
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§impl Debug for ValueParser
impl Debug for ValueParser
source§impl<P, const C: usize> From<[P; C]> for ValueParserwhere
P: Into<PossibleValue<'static>>,
impl<P, const C: usize> From<[P; C]> for ValueParserwhere
P: Into<PossibleValue<'static>>,
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§impl<P> From<P> for ValueParserwhere
P: TypedValueParser + Send + Sync + 'static,
P::Value: Send + Sync + Clone,
impl<P> From<P> for ValueParserwhere
P: TypedValueParser + Send + Sync + 'static,
P::Value: Send + Sync + Clone,
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())
.takes_value(true)
.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§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)
.takes_value(true)
.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..)
.takes_value(true)
.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(..)
.takes_value(true)
.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<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)
.takes_value(true)
.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>) -> Self
fn from(value: RangeInclusive<i64>) -> Self
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)
.takes_value(true)
.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)
.takes_value(true)
.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);