Trait TypedValueParser

pub trait TypedValueParser:
    Clone
    + Send
    + Sync
    + 'static {
    type Value: Send + Sync + Clone;

    // Required method
    fn parse_ref(
        &self,
        cmd: &Command,
        arg: Option<&Arg>,
        value: &OsStr,
    ) -> Result<Self::Value, Error>;

    // Provided methods
    fn parse_ref_(
        &self,
        cmd: &Command,
        arg: Option<&Arg>,
        value: &OsStr,
        _source: ValueSource,
    ) -> Result<Self::Value, Error> { ... }
    fn parse(
        &self,
        cmd: &Command,
        arg: Option<&Arg>,
        value: OsString,
    ) -> Result<Self::Value, Error> { ... }
    fn parse_(
        &self,
        cmd: &Command,
        arg: Option<&Arg>,
        value: OsString,
        _source: ValueSource,
    ) -> Result<Self::Value, Error> { ... }
    fn possible_values(
        &self,
    ) -> Option<Box<dyn Iterator<Item = PossibleValue> + '_>> { ... }
    fn map<T, F>(self, func: F) -> MapValueParser<Self, F>
       where T: Send + Sync + Clone,
             F: Fn(Self::Value) -> T + Clone { ... }
    fn try_map<T, E, F>(self, func: F) -> TryMapValueParser<Self, F>
       where F: Fn(Self::Value) -> Result<T, E> + Clone + Send + Sync + 'static,
             T: Send + Sync + Clone,
             E: Into<Box<dyn Error + Send + Sync>> { ... }
}

Parse/validate argument values

As alternatives to implementing TypedValueParser,

• Use Fn(&str) -> Result<T, E> which implements TypedValueParser
• TypedValueParser::map or TypedValueParser::try_map to adapt an existing TypedValueParser

See ValueParserFactory to register TypedValueParser::Value with value_parser!.

Example

#[derive(Clone)]
struct Custom(u32);

#[derive(Clone)]
struct CustomValueParser;

impl clap::builder::TypedValueParser for CustomValueParser {
    type Value = Custom;

    fn parse_ref(
        &self,
        cmd: &clap::Command,
        arg: Option<&clap::Arg>,
        value: &std::ffi::OsStr,
    ) -> Result<Self::Value, clap::Error> {
        let inner = clap::value_parser!(u32);
        let val = inner.parse_ref(cmd, arg, value)?;

        const INVALID_VALUE: u32 = 10;
        if val == INVALID_VALUE {
            let mut err = clap::Error::new(ErrorKind::ValueValidation)
                .with_cmd(cmd);
            if let Some(arg) = arg {
                err.insert(ContextKind::InvalidArg, ContextValue::String(arg.to_string()));
            }
            err.insert(ContextKind::InvalidValue, ContextValue::String(INVALID_VALUE.to_string()));
            return Err(err);
        }

        Ok(Custom(val))
    }
}

Required Associated Types

type Value: Send + Sync + Clone

Argument’s value type

Required Methods

fn parse_ref( &self, cmd: &Command, arg: Option<&Arg>, value: &OsStr, ) -> Result<Self::Value, Error>

Parse the argument value

When arg is None, an external subcommand value is being parsed.

Provided Methods

fn parse_ref_( &self, cmd: &Command, arg: Option<&Arg>, value: &OsStr, _source: ValueSource, ) -> Result<Self::Value, Error>

Parse the argument value

When arg is None, an external subcommand value is being parsed.

fn parse( &self, cmd: &Command, arg: Option<&Arg>, value: OsString, ) -> Result<Self::Value, Error>

Parse the argument value

When arg is None, an external subcommand value is being parsed.

fn parse_( &self, cmd: &Command, arg: Option<&Arg>, value: OsString, _source: ValueSource, ) -> Result<Self::Value, Error>

Parse the argument value

When arg is None, an external subcommand value is being parsed.

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.

fn map<T, F>(self, func: F) -> MapValueParser<Self, F>

where T: Send + Sync + Clone, F: Fn(Self::Value) -> T + Clone,

Adapt a TypedValueParser from one value to another

Example

let cmd = Command::new("mycmd")
    .arg(
        Arg::new("flag")
            .long("flag")
            .action(clap::ArgAction::SetTrue)
            .value_parser(
                BoolishValueParser::new()
                .map(|b| -> usize {
                    if b { 10 } else { 5 }
                })
            )
    );

let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag"]).unwrap();
assert!(matches.contains_id("flag"));
assert_eq!(
    matches.get_one::<usize>("flag").copied(),
    Some(10)
);

let matches = cmd.try_get_matches_from(["mycmd"]).unwrap();
assert!(matches.contains_id("flag"));
assert_eq!(
    matches.get_one::<usize>("flag").copied(),
    Some(5)
);

fn try_map<T, E, F>(self, func: F) -> TryMapValueParser<Self, F>

where F: Fn(Self::Value) -> Result<T, E> + Clone + Send + Sync + 'static, T: Send + Sync + Clone, E: Into<Box<dyn Error + Send + Sync>>,

Adapt a TypedValueParser from one value to another

Example

let cmd = Command::new("mycmd")
    .arg(
        Arg::new("flag")
            .long("flag")
            .value_parser(
                OsStringValueParser::new()
                .try_map(verify_ext)
            )
    );

fn verify_ext(os: OsString) -> Result<PathBuf, &'static str> {
    let path = PathBuf::from(os);
    if path.extension() != Some(OsStr::new("rs")) {
        return Err("only Rust files are supported");
    }
    Ok(path)
}

let error = cmd.clone().try_get_matches_from(["mycmd", "--flag", "foo.txt"]).unwrap_err();
error.print();

let matches = cmd.try_get_matches_from(["mycmd", "--flag", "foo.rs"]).unwrap();
assert!(matches.contains_id("flag"));
assert_eq!(
    matches.get_one::<PathBuf>("flag").map(|s| s.as_path()),
    Some(Path::new("foo.rs"))
);

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl TypedValueParser for BoolValueParser

type Value = bool

impl TypedValueParser for BoolishValueParser

type Value = bool

impl TypedValueParser for FalseyValueParser

type Value = bool

impl TypedValueParser for NonEmptyStringValueParser

type Value = String

impl TypedValueParser for OsStringValueParser

type Value = OsString

impl TypedValueParser for PathBufValueParser

type Value = PathBuf

impl TypedValueParser for PossibleValuesParser

type Value = String

impl TypedValueParser for StringValueParser

type Value = String

impl TypedValueParser for UnknownArgumentValueParser

type Value = String

impl<E> TypedValueParser for EnumValueParser<E>

where E: ValueEnum + Clone + Send + Sync + 'static,

type Value = E

impl<F, T, E> TypedValueParser for F

where F: Fn(&str) -> Result<T, E> + Clone + Send + Sync + 'static, E: Into<Box<dyn Error + Send + Sync>>, T: Send + Sync + Clone,

type Value = T

impl<P, F, T> TypedValueParser for MapValueParser<P, F>

where P: TypedValueParser, <P as TypedValueParser>::Value: Send + Sync + Clone, F: Fn(<P as TypedValueParser>::Value) -> T + Clone + Send + Sync + 'static, T: Send + Sync + Clone,

type Value = T

impl<P, F, T, E> TypedValueParser for TryMapValueParser<P, F>

where P: TypedValueParser, <P as TypedValueParser>::Value: Send + Sync + Clone, F: Fn(<P as TypedValueParser>::Value) -> Result<T, E> + Clone + Send + Sync + 'static, T: Send + Sync + Clone, E: Into<Box<dyn Error + Send + Sync>>,

type Value = T

impl<T> TypedValueParser for RangedI64ValueParser<T>

where T: TryFrom<i64> + Clone + Send + Sync + 'static, <T as TryFrom<i64>>::Error: Send + Sync + 'static + Error + ToString,

type Value = T

impl<T> TypedValueParser for RangedU64ValueParser<T>

where T: TryFrom<u64> + Clone + Send + Sync + 'static, <T as TryFrom<u64>>::Error: Send + Sync + 'static + Error + ToString,

type Value = T