Struct clap::Arg

pub struct Arg<'n, 'l, 'h, 'b, 'p, 'r> {
    pub name: &'n str,
    pub short: Option<char>,
    pub long: Option<&'l str>,
    pub help: Option<&'h str>,
    pub required: bool,
    pub takes_value: bool,
    pub index: Option<u8>,
    pub multiple: bool,
    pub blacklist: Option<Vec<&'b str>>,
    pub possible_vals: Option<Vec<&'p str>>,
    pub requires: Option<Vec<&'r str>>,
}

The abstract representation of a command line argument used by the consumer of the library.

This struct is used by the library consumer and describes the command line arguments for their program. and then evaluates the settings the consumer provided and determines the concret argument struct to use when parsing.

Example

Arg::new("conifg")
      .short("c")
      .long("config")
      .takes_value(true)
      .help("Provides a config file to myprog")

Fields

name: &'n str

The unique name of the argument, required

short: Option<char>

The short version (i.e. single character) of the argument, no preceding - NOTE: short is mutually exclusive with index

long: Option<&'l str>

The long version of the flag (i.e. word) without the preceding -- NOTE: long is mutually exclusive with index

help: Option<&'h str>

The string of text that will displayed to the user when the application's help text is displayed

required: bool

If this is a required by default when using the command line program i.e. a configuration file that's required for the program to function NOTE: required by default means, it is required until mutually exclusive arguments are evaluated.

takes_value: bool

Determines if this argument is an option, vice a flag or positional and is mutually exclusive with index and multiple

index: Option<u8>

The index of the argument. index is mutually exclusive with takes_value and multiple

multiple: bool

Determines if multiple instances of the same flag are allowed. multiple is mutually exclusive with index and takes_value. I.e. -v -v -v or -vvv

blacklist: Option<Vec<&'b str>>

A list of names for other arguments that may not be used with this flag

possible_vals: Option<Vec<&'p str>>

A list of possible values for an option or positional argument

requires: Option<Vec<&'r str>>

A list of names of other arguments that are required to be used when this flag is used

Methods

impl<'n, 'l, 'h, 'b, 'p, 'r> Arg<'n, 'l, 'h, 'b, 'p, 'r>

fn new(n: &'n str) -> Arg<'n, 'l, 'h, 'b, 'p, 'r>

Creates a new instace of Arg using a unique string name. The name will be used by the library consumer to get information about whether or not the argument was used at runtime.

NOTE: in the case of arguments that take values (i.e. takes_value(true)) and positional arguments (i.e. those without a - or --) the name will also be displayed when the user prints the usage/help information of the program.

Example:

Arg::new("conifg")

fn short(self, s: &str) -> Arg<'n, 'l, 'h, 'b, 'p, 'r>

Sets the short version of the argument without the preceding -.

By default clap automatically assigns v and h to display version and help information respectivly. You may use v or h for your own purposes, in which case clap simply will not asign those to the displaying of version or help.

NOTE: Any leading - characters will be stripped, and only the first non - chacter will be used as the short version, i.e. for when the user mistakenly sets the short to -o or the like. Example:

.short("c")

fn long(self, l: &'l str) -> Arg<'n, 'l, 'h, 'b, 'p, 'r>

Sets the long version of the argument without the preceding --.

By default clap automatically assigns version and help to display version and help information respectivly. You may use version or help for your own purposes, in which case clap simply will not asign those to the displaying of version or help automatically, and you will have to do so manually.

NOTE: Any leading - characters will be stripped i.e. for when the user mistakenly sets the short to --out or the like.

Example:

.long("config")

fn help(self, h: &'h str) -> Arg<'n, 'l, 'h, 'b, 'p, 'r>

Sets the help text of the argument that will be displayed to the user when they print the usage/help information.

Example:

.help("The config file used by the myprog")

fn required(self, r: bool) -> Arg<'n, 'l, 'h, 'b, 'p, 'r>

Sets whether or not the argument is required by default. Required by default means it is required, when no other mutually exlusive rules have been evaluated. Mutually exclusive rules take precedence over being required by default.

NOTE: Flags (i.e. not positional, or arguments that take values) cannot be required by default. when they print the usage/help information.

Example:

.required(true)

fn mutually_excludes(self, name: &'b str) -> Arg<'n, 'l, 'h, 'b, 'p, 'r>

Sets a mutually exclusive argument by name. I.e. when using this argument, the following argument can't be present.

NOTE: Mutually exclusive rules take precedence over being required by default. Mutually exclusive rules only need to be set for one of the two arguments, they do not need to be set for each.

Example:

.mutually_excludes("debug")

fn mutually_excludes_all(self, names: Vec<&'b str>) -> Arg<'n, 'l, 'h, 'b, 'p, 'r>

Sets a mutually exclusive arguments by names. I.e. when using this argument, the following argument can't be present.

NOTE: Mutually exclusive rules take precedence over being required by default. Mutually exclusive rules only need to be set for one of the two arguments, they do not need to be set for each.

Example:

.mutually_excludes_all(
       vec!["debug", "input"])

fn requires(self, name: &'r str) -> Arg<'n, 'l, 'h, 'b, 'p, 'r>

Sets an argument by name that is required when this one is presnet I.e. when using this argument, the following argument must be present.

NOTE: Mutually exclusive rules take precedence over being required

Example:

.requires("debug")

fn requires_all(self, names: Vec<&'r str>) -> Arg<'n, 'l, 'h, 'b, 'p, 'r>

Sets arguments by names that are required when this one is presnet I.e. when using this argument, the following arguments must be present.

NOTE: Mutually exclusive rules take precedence over being required by default.

Example:

.requires_all(
       vec!["debug", "input"])

fn takes_value(self, tv: bool) -> Arg<'n, 'l, 'h, 'b, 'p, 'r>

Specifies that the argument takes an additional value at run time.

NOTE: When setting this to true the name of the argument will be used when printing the help/usage information to the user.

Example:

.takes_value(true)

fn index(self, idx: u8) -> Arg<'n, 'l, 'h, 'b, 'p, 'r>

Specifies the index of a positional argument starting at 1.

NOTE: When setting this, any short or long values you set are ignored as positional arguments cannot have a short or long. Also, the name will be used when printing the help/usage information to the user.

Example:

.index(1)

fn multiple(self, multi: bool) -> Arg<'n, 'l, 'h, 'b, 'p, 'r>

Specifies if the flag may appear more than once such as for multiple debugging levels (as an example). -ddd for three levels of debugging, or -d -d -d. When this is set to true you recieve the number of occurances the user supplied of a particular flag at runtime.

NOTE: When setting this, any takes_value or index values you set are ignored as flags cannot have a values or an index.

Example:

.multiple(true)

fn possible_values(self, names: Vec<&'p str>) -> Arg<'n, 'l, 'h, 'b, 'p, 'r>

Specifies a list of possible values for this argument. At runtime, clap verifies that only one of the specified values was used, or fails with a usage string.

NOTE: This setting only applies to options and positional arguments

Example:

.possible_values(vec!["fast", "slow"])