Skip to main content

## PossibleValue

# Struct PossibleValue

Source

    pub struct PossibleValue { /* private fields */ }

Expand description

A possible value of an argument.

This is used for specifying possible values of Args.

See also `PossibleValuesParser`

NOTE: Most likely you can use strings, rather than `PossibleValue` as it is only required to hide single values from help messages and shell completions or to attach help to possible values.

## §Examples

    let cfg = Arg::new("config")
        .action(ArgAction::Set)
        .value_name("FILE")
        .value_parser([
            PossibleValue::new("fast"),
            PossibleValue::new("slow").help("slower than fast"),
            PossibleValue::new("secret speed").hide(true)
        ]);

## Implementations§

Source§

### impl PossibleValue

Source

#### pub fn new(name: impl Into<Str>) -> PossibleValue

Create a `PossibleValue` with its name.

The name will be used to decide whether this value was provided by the user to an argument.

NOTE: In case it is not hidden it will also be shown in help messages for arguments that use it as a possible value and have not hidden them through `Arg::hide_possible_values(true)`.

##### §Examples

    PossibleValue::new("fast")

Source

#### pub fn help(self, help: impl IntoResettable<StyledStr>) -> PossibleValue

Sets the help description of the value.

This is typically displayed in completions (where supported) and should be a short, one-line description.

##### §Examples

    PossibleValue::new("slow")
        .help("not fast")

Source

#### pub fn hide(self, yes: bool) -> PossibleValue

Hides this value from help and shell completions.

This is an alternative to hiding through `Arg::hide_possible_values(true)`, if you only want to hide some values.

##### §Examples

    PossibleValue::new("secret")
        .hide(true)

Source

#### pub fn alias(self, name: impl IntoResettable<Str>) -> PossibleValue

Sets a hidden alias for this argument value.

##### §Examples

    PossibleValue::new("slow")
        .alias("not-fast")

Source

#### pub fn aliases( self, names: impl IntoIterator<Item = impl Into<Str>>, ) -> PossibleValue

Sets multiple hidden aliases for this argument value.

##### §Examples

    PossibleValue::new("slow")
        .aliases(["not-fast", "snake-like"])

Source§

### impl PossibleValue

Reflection

Source

#### pub fn get_name(&self) -> &str

Get the name of the argument value

##### Examples found in repository?

examples/git-derive.rs (line 72)

    69    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
    70        self.to_possible_value()
    71            .expect("no values are skipped")
    72            .get_name()
    73            .fmt(f)
    74    }

More examples
Hide additional examples
examples/typed-derive/implicit.rs (line 44)

    39    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
    40        use clap::ValueEnum;
    41
    42        self.to_possible_value()
    43            .expect("no values are skipped")
    44            .get_name()
    45            .fmt(f)
    46    }

Source

#### pub fn get_help(&self) -> Option<&StyledStr>

Get the help specified for this argument, if any

Source

#### pub fn is_hide_set(&self) -> bool

Report if `PossibleValue::hide` is set

Source

#### pub fn get_name_and_aliases(&self) -> impl Iterator<Item = &str>

Returns all valid values of the argument value.

Namely the name and all aliases.

Source

#### pub fn matches(&self, value: &str, ignore_case: bool) -> bool

Tests if the value is valid for this argument value

The value is valid if it is either the name or one of the aliases.

##### §Examples

    let arg_value = PossibleValue::new("fast").alias("not-slow");

    assert!(arg_value.matches("fast", false));
    assert!(arg_value.matches("not-slow", false));

    assert!(arg_value.matches("FAST", true));
    assert!(!arg_value.matches("FAST", false));

##### Examples found in repository?

examples/typed-derive/implicit.rs (line 56)

    52    fn from_str(s: &str) -> Result<Self, Self::Err> {
    53        use clap::ValueEnum;
    54
    55        for variant in Self::value_variants() {
    56            if variant.to_possible_value().unwrap().matches(s, false) {
    57                return Ok(*variant);
    58            }
    59        }
    60        Err(format!("Invalid variant: {s}"))
    61    }

## Trait Implementations§

Source§

### impl Clone for PossibleValue

Source§

#### fn clone(&self) -> PossibleValue

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from `source`. Read more
Source§

### impl Debug for PossibleValue

Source§

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

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

### impl Default for PossibleValue

Source§

#### fn default() -> PossibleValue

Returns the “default value” for a type. Read more
Source§

### impl Eq for PossibleValue

Source§

### impl<S> From<S> for PossibleValue
where S: Into<Str>,

Source§

#### fn from(s: S) -> PossibleValue

Converts to this type from the input type.
Source§

### impl PartialEq for PossibleValue

Source§

#### fn eq(&self, other: &PossibleValue) -> bool

Equality operator `==`. Read more
1.0.0 (const: unstable) · Source§

#### fn ne(&self, other: &Rhs) -> bool

Inequality operator `!=`. Read more
Source§

### impl StructuralPartialEq for PossibleValue

## Auto Trait Implementations§

§

### impl Freeze for PossibleValue

§

### impl RefUnwindSafe for PossibleValue

§

### impl Send for PossibleValue

§

### impl Sync for PossibleValue

§

### impl Unpin for PossibleValue

§

### impl UnsafeUnpin for PossibleValue

§

### impl UnwindSafe for PossibleValue

## 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, dest: *mut u8)

🔬This is a nightly-only experimental API. (`clone_to_uninit`)
Performs copy-assignment from `self` to `dest`. 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<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.