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

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

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

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

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

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

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

Describes the content of AnyValue

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

Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more

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");
Converts to this type from the input type.

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");
Converts to this type from the input type.

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);
Converts to this type from the input type.

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);
Converts to this type from the input type.

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);
Converts to this type from the input type.

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);
Converts to this type from the input type.

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);
Converts to this type from the input type.

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);
Converts to this type from the input type.
Convert to the intended resettable type
Convert to the intended resettable type

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

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

The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.