Struct clap::builder::PossibleValue

pub struct PossibleValue<'help> { /* private fields */ }

A possible value of an argument.

This is used for specifying possible values of Args.

NOTE: This struct is likely not needed for most usecases 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")
    .takes_value(true)
    .value_name("FILE")
    .value_parser([
        PossibleValue::new("fast"),
        PossibleValue::new("slow").help("slower than fast"),
        PossibleValue::new("secret speed").hide(true)
    ]);

Implementations

impl<'help> PossibleValue<'help>

pub fn new(name: &'help str) -> Self

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

pub fn help(self, help: &'help str) -> Self

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

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

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)

pub fn alias(self, name: &'help str) -> Self

Sets a hidden alias for this argument value.

Examples

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

pub fn aliases<I>(self, names: I) -> Self

where I: IntoIterator<Item = &'help str>,

Sets multiple hidden aliases for this argument value.

Examples

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

impl<'help> PossibleValue<'help>

Reflection

pub fn get_name(&self) -> &'help str

Get the name of the argument value

pub fn get_help(&self) -> Option<&'help str>

Get the help specified for this argument, if any

pub fn is_hidden(&self) -> bool

Deprecated, replaced with PossibleValue::is_hide_set

pub fn is_hide_set(&self) -> bool

Report if PossibleValue::hide is set

pub fn get_visible_name(&self) -> Option<&'help str>

Get the name if argument value is not hidden, None otherwise

pub fn get_name_and_aliases(&self) -> impl Iterator<Item = &'help str> + '_

Returns all valid values of the argument value.

Namely the name and all aliases.

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

Trait Implementations

impl<'help> Clone for PossibleValue<'help>

fn clone(&self) -> PossibleValue<'help>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'help> Debug for PossibleValue<'help>

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

Formats the value using the given formatter.

impl<'help> Default for PossibleValue<'help>

fn default() -> PossibleValue<'help>

Returns the “default value” for a type.

impl<'help> From<&'help &'help str> for PossibleValue<'help>

fn from(s: &'help &'help str) -> Self

Converts to this type from the input type.

impl<'help> From<&'help str> for PossibleValue<'help>

fn from(s: &'help str) -> Self

Converts to this type from the input type.

impl<'help> PartialEq for PossibleValue<'help>

fn eq(&self, other: &PossibleValue<'help>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'help> Eq for PossibleValue<'help>

impl<'help> StructuralPartialEq for PossibleValue<'help>