Struct clap::builder::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())
            .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

impl ValueParser

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

where P: TypedValueParser, P::Value: Send + Sync + Clone,

Custom parser for argument values

To create a custom parser, see TypedValueParser

Pre-existing implementations include:

• 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<'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

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<'static>>,

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

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

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

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

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

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

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

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

Converts to this type from the input type.