Struct clap::Arg
[−]
[src]
pub struct Arg<'n, 'l, 'h, 'b, 'p, 'r> { // some fields omitted }
The abstract representation of a command line argument used by the consumer of the library. Used to set all the options and relationships that define a valid argument for the program.
This struct is used by the library consumer and describes the command line arguments for their program. Then evaluates the settings the consumer provided and determines the concret argument type to use when parsing.
There are two methods for constructing Arg
s, using the builder pattern and setting options
manually, or using a usage string which is far less verbose. You can also use a combination
of the two methods to achieve the best of both worlds.
Example
// Using the traditional builder pattern and setting each option manually Arg::with_name("conifg") .short("c") .long("config") .takes_value(true) .help("Provides a config file to myprog") // Using a usage string (setting a similar argument to the one above) Arg::from_usage("-i --input=[input] 'Provides an input file to the program'")
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.
NOTE: this function is deprecated in favor of Arg::with_name() to stay consistant with Rust APIs
Example
Arg::new("conifg")
fn with_name(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::with_name("conifg")
fn from_usage(u: &'n str) -> Arg<'n, 'n, 'n, 'b, 'p, 'r>
Creates a new instace of Arg
from a usage string. Allows creation of basic settings
for Arg (i.e. everything except relational rules). The syntax is flexible, but there are
some rules to follow.
NOTE: only properties which you wish to set must be present
- Name (arguments with a
long
or that take a value can ommit this if desired), use[]
for non-required arguments, or<>
for required arguments. - Short preceded by a
-
- Long preceded by a
--
(this may be used as the name, if the name is omitted. If the name is not omittied, the name takes precedence over thelong
) - Value (this can be used as the name if the name is not manually specified. If the name
is manually specified, it takes precedence. If this value is used as the name, it uses the
same
[]
and<>
requirement specification rules. If it is not used as the name, it still needs to be surrounded by either[]
or<>
but there is no requirement effect, as the requirement rule is determined by the real name. This value may follow theshort
orlong
, it doesn't matter. If it follows thelong
, it may follow either a=
orthere is no difference, just personal preference. If this follows a
short
it can only be after a) i.e.
-c [name]
,--config [name]
,--config=[name]
, etc. - Multiple specifier
...
(the...
may follow the name,short
,long
, or value without aspace) i.e.
<name>... -c
,--config <name>...
,[name] -c...
, etc. - The help info surrounded by
'
s (single quotes) - The index of a positional argument will be the next available index (you don't need to
specify one) i.e. all arguments without a
short
orlong
will be treated as positional
Example
.args(vec![ // A option argument with a long, named "conf" (note: because the name was specified // the portion after the long can be called anything, only the first name will be displayed // to the user. Also, requirement is set with the *name*, so the portion after the long could // be either <> or [] and it wouldn't matter, so long as it's one of them. Had the name been // omitted, the name would have been derived from the portion after the long and those rules // would have mattered) Arg::from_usage("[conf] --config=[c] 'a required file for the configuration'"), // A flag with a short, a long, named "debug", and accepts multiple values Arg::from_usage("-d --debug... 'turns on debugging information"), // A required positional argument named "input" Arg::from_usage("<input> 'the input file to use'") ])
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
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
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"])