[go: up one dir, main page]

Struct clap::Arg

source · 
pub struct Arg<'n, 'l, 'h, 'g, 'p, 'r> { /* private fields */ }
Expand description

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 Args, 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'")

Implementations§

source§

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

source

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

WARNING: This function is deprecated. Use Arg::with_name() instead.

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

pub fn with_name(n: &'n str) -> Arg<'n, 'l, 'h, 'g, '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")
source

pub fn from_usage(u: &'n str) -> Arg<'n, 'n, 'n, 'g, '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

  1. Name (arguments with a long or that take a value can ommit this if desired), use [] for non-required arguments, or <> for required arguments.
  2. Short preceded by a -
  3. 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 the long)
  4. 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 the short or long, it doesn’t matter. If it follows the long, it may follow either a = or there 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.
  5. Multiple specifier ... (the ... may follow the name, short, long, or value without a space) i.e. <name>... -c, --config <name>..., [name] -c..., etc.
  6. The help info surrounded by 's (single quotes)
  7. 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 or long will be treated as positional
  8. If the value names are all the same, and their multiple ones (i.e -o <val> <val>) they are counted and used as the number of values. If they are different, they are used as the value names (i.e. --opt <file> <mode>). In this case, if no name was specified prior to the value names, the long is used as the name by which to access the argument.
§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'")
])
source

pub fn short(self, s: &str) -> Arg<'n, 'l, 'h, 'g, '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 respectively. You may use v or h for your own purposes, in which case clap simply will not assign 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")
source

pub fn long(self, l: &'l str) -> Arg<'n, 'l, 'h, 'g, '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 respectively. You may use version or help for your own purposes, in which case clap simply will not assign 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")
source

pub fn help(self, h: &'h str) -> Arg<'n, 'l, 'h, 'g, '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")
source

pub fn required(self, r: bool) -> Arg<'n, 'l, 'h, 'g, '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)
source

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

WARNING: This method is deprecated. Use .conflicts_with() instead.

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

pub fn mutually_excludes_all<T, I>( self, names: I, ) -> Arg<'n, 'l, 'h, 'g, 'p, 'r>
where T: AsRef<str> + 'r, I: IntoIterator<Item = &'r T>,

WARNING: This method is deprecated. Use conflicts_with_all() instead.

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
let conf_excludes = ["debug", "input"];
.mutually_excludes_all(&conf_excludes)
source

pub fn conflicts_with(self, name: &'r str) -> Arg<'n, 'l, 'h, 'g, '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
.conflicts_with("debug")
source

pub fn conflicts_with_all<T, I>(self, names: I) -> Arg<'n, 'l, 'h, 'g, 'p, 'r>
where T: AsRef<str> + 'r, I: IntoIterator<Item = &'r T>,

Sets 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
let config_conflicts = ["debug", "input"];
.conflicts_with_all(&config_conflicts)
source

pub fn requires(self, name: &'r str) -> Arg<'n, 'l, 'h, 'g, '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")
source

pub fn requires_all<T, I>(self, names: I) -> Arg<'n, 'l, 'h, 'g, 'p, 'r>
where T: AsRef<str> + 'r, I: IntoIterator<Item = &'r T>,

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
let config_reqs = ["debug", "input"];
.requires_all(&config_reqs)
source

pub fn takes_value(self, tv: bool) -> Arg<'n, 'l, 'h, 'g, '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)
source

pub fn index(self, idx: u8) -> Arg<'n, 'l, 'h, 'g, '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)
source

pub fn multiple(self, multi: bool) -> Arg<'n, 'l, 'h, 'g, '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 receive the number of occurrences 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)
source

pub fn global(self, g: bool) -> Arg<'n, 'l, 'h, 'g, 'p, 'r>

Specifies that an argument can be matched to all child subcommands.

NOTE: Global arguments only propagate down, not up (to parent commands)

NOTE: Global arguments cannot be required.

NOTE: Global arguments, when matched, only exist in the command’s matches that they were matched to. For example, if you defined a --flag global argument in the top most parent command, but the user supplied the arguments top cmd1 cmd2 --flag only cmd2’s ArgMatches would return true if tested for .is_present("flag").

§Example
.global(true)
source

pub fn empty_values(self, ev: bool) -> Arg<'n, 'l, 'h, 'g, 'p, 'r>

Allows an argument to accept explicit empty values. An empty value must be specified at the command line with an explicit "", or ''

NOTE: Defaults to true (Explicit empty values are allowed)

§Example
.empty_values(true)
source

pub fn possible_values<T, I>(self, names: I) -> Arg<'n, 'l, 'h, 'g, 'p, 'r>
where T: AsRef<str> + 'p, I: IntoIterator<Item = &'p T>,

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
let mode_vals = ["fast", "slow"];
.possible_values(&mode_vals)
source

pub fn group(self, name: &'g str) -> Arg<'n, 'l, 'h, 'g, 'p, 'r>

Specifies the name of the group the argument belongs to.

§Example
.group("mode")
source

pub fn number_of_values(self, qty: u8) -> Arg<'n, 'l, 'h, 'g, 'p, 'r>

Specifies how many values are required to satisfy this argument. For example, if you had a -f <file> argument where you wanted exactly 3 ‘files’ you would set .number_of_values(3), and this argument wouldn’t be satisfied unless the user provided 3 and only 3 values.

NOTE: qty must be > 1

NOTE: Does not require .multiple(true) to be set. Setting .multiple(true) would allow -f <file> <file> <file> -f <file> <file> <file> where as not setting .multiple(true) would only allow one occurrence of this argument.

§Example
.number_of_values(3)
source

pub fn max_values(self, qty: u8) -> Arg<'n, 'l, 'h, 'g, 'p, 'r>

Specifies the maximum number of values are for this argument. For example, if you had a -f <file> argument where you wanted up to 3 ‘files’ you would set .max_values(3), and this argument would be satisfied if the user provided, 1, 2, or 3 values.

NOTE: qty must be > 1

NOTE: This implicity sets .multiple(true)

§Example
.max_values(3)
source

pub fn min_values(self, qty: u8) -> Arg<'n, 'l, 'h, 'g, 'p, 'r>

Specifies the minimum number of values are for this argument. For example, if you had a -f <file> argument where you wanted at least 2 ‘files’ you would set .min_values(2), and this argument would be satisfied if the user provided, 2 or more values.

NOTE: This implicity sets .multiple(true)

NOTE: qty must be > 0

NOTE: qty must be > 0. If you wish to have an argument with 0 or more values prefer two separate arguments (a flag, and an option with multiple values).

§Example
.min_values(2)
source

pub fn value_names<T, I>(self, names: I) -> Arg<'n, 'l, 'h, 'g, 'p, 'r>
where T: AsRef<str> + 'n, I: IntoIterator<Item = &'n T>,

Specifies names for values of option arguments. These names are cosmetic only, used for help and usage strings only. The names are not used to access arguments. The values of the arguments are accessed in numeric order (i.e. if you specify two names one and two one will be the first matched value, two will be the second).

NOTE: This implicitly sets .number_of_values() so there is no need to set that, but be aware that the number of “names” you set for the values, will be the exact number of values required to satisfy this argument

NOTE: Does not require .multiple(true) to be set. Setting .multiple(true) would allow -f <file> <file> <file> -f <file> <file> <file> where as not setting .multiple(true) would only allow one occurrence of this argument.

§Example
let val_names = ["one", "two"];
// ...
.value_names(&val_names)

Trait Implementations§

source§

impl<'n, 'l, 'h, 'g, 'p, 'r, 'z> From<&'z Arg<'n, 'l, 'h, 'g, 'p, 'r>> for Arg<'n, 'l, 'h, 'g, 'p, 'r>

source§

fn from(a: &'z Arg<'n, 'l, 'h, 'g, 'p, 'r>) -> Arg<'n, 'l, 'h, 'g, 'p, 'r>

Converts to this type from the input type.

Auto Trait Implementations§

§

impl<'n, 'l, 'h, 'g, 'p, 'r> Freeze for Arg<'n, 'l, 'h, 'g, 'p, 'r>

§

impl<'n, 'l, 'h, 'g, 'p, 'r> RefUnwindSafe for Arg<'n, 'l, 'h, 'g, 'p, 'r>

§

impl<'n, 'l, 'h, 'g, 'p, 'r> Send for Arg<'n, 'l, 'h, 'g, 'p, 'r>

§

impl<'n, 'l, 'h, 'g, 'p, 'r> Sync for Arg<'n, 'l, 'h, 'g, 'p, 'r>

§

impl<'n, 'l, 'h, 'g, 'p, 'r> Unpin for Arg<'n, 'l, 'h, 'g, 'p, 'r>

§

impl<'n, 'l, 'h, 'g, 'p, 'r> UnwindSafe for Arg<'n, 'l, 'h, 'g, 'p, 'r>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.