Struct ValueParser

pub struct ValueParser(/* private fields */);

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 type
• ValueParser::new for additional TypedValueParser 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

impl ValueParser

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

where P: TypedValueParser,

Custom parser for argument values

Pre-existing TypedValueParser implementations include:

• Fn(&str) -> Result<T, E>
• EnumValueParser and PossibleValuesParser for static enumerated values
• BoolishValueParser and FalseyValueParser for alternative bool implementations
• RangedI64ValueParser and RangedU64ValueParser
• 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())));

pub const fn bool() -> Self

bool parser for argument values

See also:

• BoolishValueParser for different human readable bool representations
• FalseyValueParser 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());

pub const fn string() -> Self

String parser for argument values

See also:

• NonEmptyStringValueParser

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

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

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

impl ValueParser

pub fn type_id(&self) -> AnyValueId

Describes the content of AnyValue

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

impl Clone for ValueParser

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ValueParser

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

Formats the value using the given formatter.

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

fn from(values: [P; C]) -> Self

Converts to this type from the input type.

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

fn from(p: P) -> Self

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

fn from(value: RangeFull) -> Self

Converts to this type from the input type.

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

fn from(value: RangeInclusive<i64>) -> Self

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

fn from(value: RangeToInclusive<i64>) -> Self

Converts to this type from the input type.

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

fn from(values: Vec<P>) -> Self

Converts to this type from the input type.

impl IntoResettable<ValueParser> for Option<ValueParser>

fn into_resettable(self) -> Resettable<ValueParser>

Convert to the intended resettable type

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 24 bytes