Struct clap::Arg
[−]
[src]
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>
[src]
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"])