Struct `PossibleValue`

pub struct PossibleValue { /* private fields */ }

A possible value of an argument.

This is used for specifying possible values of Args.

See also [PossibleValuesParser][crate::builder::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

# use clap_builder as clap;
# use clap::{Arg, builder::PossibleValue, ArgAction};
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

`impl PossibleValue`

fn new(name: impl Into<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

# use clap_builder as clap;
# use clap::builder::PossibleValue;
PossibleValue::new("fast")
# ;

fn help(self, help: impl IntoResettable<StyledStr>) -> 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

# use clap_builder as clap;
# use clap::builder::PossibleValue;
PossibleValue::new("slow")
    .help("not fast")
# ;

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

# use clap_builder as clap;
# use clap::builder::PossibleValue;
PossibleValue::new("secret")
    .hide(true)
# ;

fn alias(self, name: impl IntoResettable<Str>) -> Self

Sets a hidden alias for this argument value.

Examples

# use clap_builder as clap;
# use clap::builder::PossibleValue;
PossibleValue::new("slow")
    .alias("not-fast")
# ;

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

Sets multiple hidden aliases for this argument value.

Examples

# use clap_builder as clap;
# use clap::builder::PossibleValue;
PossibleValue::new("slow")
    .aliases(["not-fast", "snake-like"])
# ;

`impl PossibleValue`

fn get_name(&self) -> &str

Get the name of the argument value

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

Get the help specified for this argument, if any

fn is_hide_set(&self) -> bool

Report if PossibleValue::hide is set

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

Returns all valid values of the argument value.

Namely the name and all aliases.

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

# use clap_builder as clap;
# use clap::builder::PossibleValue;
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));