clap::builder

Struct ValueParser

source
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

§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

source

pub fn new<P>(other: P) -> ValueParser

Custom parser for argument values

Pre-existing TypedValueParser implementations include:

§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())));
source

pub const fn bool() -> ValueParser

bool parser for argument values

See also:

§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());
source

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");
source

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]);
source

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

source

pub fn type_id(&self) -> AnyValueId

Describes the content of AnyValue

source

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

source§

fn clone(&self) -> ValueParser

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for ValueParser

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
source§

impl<P, const C: usize> From<[P; C]> for ValueParser
where P: Into<PossibleValue>,

Create a ValueParser with PossibleValuesParser

See PossibleValuesParser for more flexibility in creating the PossibleValues.

§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

Converts to this type from the input type.
source§

impl<P> From<P> for ValueParser
where P: TypedValueParser + Send + Sync + 'static,

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

Converts to this type from the input type.
source§

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§

fn from(value: Range<i64>) -> ValueParser

Converts to this type from the input type.
source§

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§

fn from(value: RangeFrom<i64>) -> ValueParser

Converts to this type from the input type.
source§

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

Converts to this type from the input type.
source§

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

Converts to this type from the input type.
source§

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§

fn from(value: RangeTo<i64>) -> ValueParser

Converts to this type from the input type.
source§

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

Converts to this type from the input type.
source§

impl<P> From<Vec<P>> for ValueParser
where P: Into<PossibleValue>,

Create a ValueParser with PossibleValuesParser

See PossibleValuesParser for more flexibility in creating the PossibleValues.

§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

Converts to this type from the input type.
source§

impl IntoResettable<ValueParser> for Option<ValueParser>

source§

fn into_resettable(self) -> Resettable<ValueParser>

Convert to the intended resettable type

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<I> IntoResettable<ValueParser> for I
where I: Into<ValueParser>,

source§

fn into_resettable(self) -> Resettable<ValueParser>

Convert to the intended resettable type
source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.