Creates a new instance of Arg using a unique string name. The name will be used to get
+information about whether or not the argument was used at runtime, get values, set
+relationships with other args, etc..
+
NOTE: In the case of arguments that take values (i.e. Arg::takes_value(true))
+and positional arguments (i.e. those without a preceding - or --) the name will also
+be displayed when the user prints the usage/help information of the program.
+
+
+Arg::with_name("config")
+
Creates a new instance of Arg from a .yml (YAML) file.
+
+
+let yml = load_yaml!("arg.yml");
+let arg = Arg::from_yaml(yml);
+
Creates a new instance of Arg from a usage string. Allows creation of basic settings
+for the Arg. The syntax is flexible, but there are some rules to follow.
+
NOTE: Not all settings may be set using the usage string method. Some properties are
+only available via the builder pattern.
+
NOTE: Only ASCII values are officially supported in Arg::from_usage strings. Some
+UTF-8 codepoints may work just fine, but this is not guaranteed.
+
+
Usage strings typically following the form:
+
[explicit name] [short] [long] [value names] [help string]
+
+
This is not a hard rule as the attributes can appear in other orders. There are also
+several additional sigils which denote additional settings. Below are the details of each
+portion of the string.
+
+
This is an optional field, if it's omitted the argument will use one of the additional
+fields as the name using the following priority order:
+
+- Explicit Name (This always takes precedence when present)
+- Long
+- Short
+- Value Name
+
+
clap determines explicit names as the first string of characters between either [] or
+<> where [] has the dual notation of meaning the argument is optional, and <> meaning
+the argument is required.
+
Explicit names may be followed by:
+
+- The multiple denotation
...
+
+
Example explicit names as follows (ename for an optional argument, and rname for a
+required argument):
+
[ename] -s, --long 'some flag'
+<rname> -r, --longer 'some other flag'
+
+
+
This is set by placing a single character after a leading -.
+
Shorts may be followed by
+
+- The multiple denotation
...
+- An optional comma
, which is cosmetic only
+- Value notation
+
+
Example shorts are as follows (-s, and -r):
+
-s, --long 'some flag'
+<rname> -r [val], --longer 'some option'
+
+
+
This is set by placing a word (no spaces) after a leading --.
+
Shorts may be followed by
+
+- The multiple denotation
...
+- Value notation
+
+
Example longs are as follows (--some, and --rapid):
+
-s, --some 'some flag'
+--rapid=[FILE] 'some option'
+
+
+
This is set by placing a word(s) between [] or <> optionally after = (although this
+is cosmetic only and does not affect functionality). If an explicit name has not been
+set, using <> will denote a required argument, and [] will denote an optional argument
+
Values may be followed by
+
+- The multiple denotation
...
+- More Value notation
+
+
More than one value will also implicitly set the arguments number of values, i.e. having
+two values, --option [val1] [val2] specifies that in order for option to be satisified it
+must receive exactly two values
+
Example values are as follows (FILE, and SPEED):
+
-s, --some [FILE] 'some option'
+--rapid=<SPEED>... 'some required multiple option'
+
+
+
The help string is denoted between a pair of single quotes '' and may contain any
+characters.
+
Example help strings are as follows:
+
-s, --some [FILE] 'some option'
+--rapid=<SPEED>... 'some required multiple option'
+
+
+
Multiple notation ... (three consecutive dots/periods) specifies that this argument may
+be used multiple times. Do not confuse multiple occurrences (...) with multiple values.
+--option val1 val2 is a single occurrence with multiple values. --flag --flag is
+multiple occurrences (and then you can obviously have instances of both as well)
+
+
+App::new("prog")
+ .args(&[
+ Arg::from_usage("--config <FILE> 'a required file for the configuration and no short'"),
+ Arg::from_usage("-d, --debug... 'turns on debugging information and allows multiples'"),
+ Arg::from_usage("[input] 'an optional input file to use'")
+])
+
Sets the short version of the argument without the preceding -.
+
By default clap automatically assigns V and h to the auto-generated version and
+help arguments respectively. You may use the uppercase V or lowercase h for your own
+arguments, in which case clap simply will not assign those to the auto-generated
+version or help arguments.
+
NOTE: Any leading - characters will be stripped, and only the first
+non - character will be used as the short version
+
+
To set short use a single valid UTF-8 code point. If you supply a leading - such as
+-c, the - will be stripped.
+
+
+Arg::with_name("config")
+ .short("c")
+
Setting short allows using the argument via a single hyphen (-) such as -c
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("config")
+ .short("c"))
+ .get_matches_from(vec![
+ "prog", "-c"
+ ]);
+
+assert!(m.is_present("config"));
+
pub fn long(self, l: &'b str) -> Self[src]
Sets the long version of the argument without the preceding --.
+
By default clap automatically assigns version and help to the auto-generated
+version and help arguments respectively. You may use the word version or help for
+the long form of your own arguments, in which case clap simply will not assign those to
+the auto-generated version or help arguments.
+
NOTE: Any leading - characters will be stripped
+
+
To set long use a word containing valid UTF-8 codepoints. If you supply a double leading
+-- such as --config they will be stripped. Hyphens in the middle of the word, however,
+will not be stripped (i.e. config-file is allowed)
+
+
+Arg::with_name("cfg")
+ .long("config")
+
Setting long allows using the argument via a double hyphen (--) such as --config
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .long("config"))
+ .get_matches_from(vec![
+ "prog", "--config"
+ ]);
+
+assert!(m.is_present("cfg"));
+
pub fn alias<S: Into<&'b str>>(self, name: S) -> Self[src]
Allows adding a Arg alias, which function as "hidden" arguments that
+automatically dispatch as if this argument was used. This is more efficient, and easier
+than creating multiple hidden arguments as one only needs to check for the existence of
+this command, and not all variants.
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("test")
+ .long("test")
+ .alias("alias")
+ .takes_value(true))
+ .get_matches_from(vec![
+ "prog", "--alias", "cool"
+ ]);
+assert!(m.is_present("test"));
+assert_eq!(m.value_of("test"), Some("cool"));
+
Allows adding Arg aliases, which function as "hidden" arguments that
+automatically dispatch as if this argument was used. This is more efficient, and easier
+than creating multiple hidden subcommands as one only needs to check for the existence of
+this command, and not all variants.
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("test")
+ .long("test")
+ .aliases(&["do-stuff", "do-tests", "tests"])
+ .help("the file to add")
+ .required(false))
+ .get_matches_from(vec![
+ "prog", "--do-tests"
+ ]);
+assert!(m.is_present("test"));
+
Allows adding a Arg alias that functions exactly like those defined with
+[Arg::alias], except that they are visible inside the help message.
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("test")
+ .visible_alias("something-awesome")
+ .long("test")
+ .takes_value(true))
+ .get_matches_from(vec![
+ "prog", "--something-awesome", "coffee"
+ ]);
+assert!(m.is_present("test"));
+assert_eq!(m.value_of("test"), Some("coffee"));
+
Allows adding multiple Arg aliases that functions exactly like those defined
+with [Arg::aliases], except that they are visible inside the help message.
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("test")
+ .long("test")
+ .visible_aliases(&["something", "awesome", "cool"]))
+ .get_matches_from(vec![
+ "prog", "--awesome"
+ ]);
+assert!(m.is_present("test"));
+
pub fn help(self, h: &'b str) -> Self[src]
Sets the short help text of the argument that will be displayed to the user when they print
+the help information with -h. Typically, this is a short (one line) description of the
+arg.
+
NOTE: If only Arg::help is provided, and not Arg::long_help but the user requests
+--help clap will still display the contents of help appropriately
+
NOTE: Only Arg::help is used in completion script generation in order to be concise
+
+
Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to
+include a newline in the help text and have the following text be properly aligned with all
+the other help text.
+
+
+Arg::with_name("config")
+ .help("The config file used by the myprog")
+
Setting help displays a short message to the side of the argument when the user passes
+-h or --help (by default).
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .long("config")
+ .help("Some help text describing the --config arg"))
+ .get_matches_from(vec![
+ "prog", "--help"
+ ]);
+
The above example displays
+
helptest
+
+USAGE:
+ helptest [FLAGS]
+
+FLAGS:
+ --config Some help text describing the --config arg
+-h, --help Prints help information
+-V, --version Prints version information
+
+
Sets the long help text of the argument that will be displayed to the user when they print
+the help information with --help. Typically this a more detailed (multi-line) message
+that describes the arg.
+
NOTE: If only long_help is provided, and not Arg::help but the user requests -h
+clap will still display the contents of long_help appropriately
+
NOTE: Only Arg::help is used in completion script generation in order to be concise
+
+
Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to
+include a newline in the help text and have the following text be properly aligned with all
+the other help text.
+
+
+Arg::with_name("config")
+ .long_help(
+"The config file used by the myprog must be in JSON format
+with only valid keys and may not contain other nonsense
+that cannot be read by this program. Obviously I'm going on
+and on, so I'll stop now.")
+
Setting help displays a short message to the side of the argument when the user passes
+-h or --help (by default).
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .long("config")
+ .long_help(
+"The config file used by the myprog must be in JSON format
+with only valid keys and may not contain other nonsense
+that cannot be read by this program. Obviously I'm going on
+and on, so I'll stop now."))
+ .get_matches_from(vec![
+ "prog", "--help"
+ ]);
+
The above example displays
+
helptest
+
+USAGE:
+ helptest [FLAGS]
+
+FLAGS:
+ --config
+ The config file used by the myprog must be in JSON format
+ with only valid keys and may not contain other nonsense
+ that cannot be read by this program. Obviously I'm going on
+ and on, so I'll stop now.
+
+-h, --help
+ Prints help information
+
+-V, --version
+ Prints version information
+
+
Specifies that this arg is the last, or final, positional argument (i.e. has the highest
+index) and is only able to be accessed via the -- syntax (i.e. $ prog args -- last_arg). Even, if no other arguments are left to parse, if the user omits the -- syntax
+they will receive an UnknownArgument error. Setting an argument to .last(true) also
+allows one to access this arg early using the -- syntax. Accessing an arg early, even with
+the -- syntax is otherwise not possible.
+
NOTE: This will change the usage string to look like $ prog [FLAGS] [-- <ARG>] if
+ARG is marked as .last(true).
+
NOTE: This setting will imply AppSettings::DontCollapseArgsInUsage because failing
+to set this can make the usage string very confusing.
+
NOTE: This setting only applies to positional arguments, and has no affect on FLAGS /
+OPTIONS
+
CAUTION: Setting an argument to .last(true) and having child subcommands is not
+recommended with the exception of also using AppSettings::ArgsNegateSubcommands
+(or AppSettings::SubcommandsNegateReqs if the argument marked .last(true) is also
+marked .required(true))
+
+
+Arg::with_name("args")
+ .last(true)
+
Setting Arg::last(true) ensures the arg has the highest index of all positional args
+and requires that the -- syntax be used to access it early.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("first"))
+ .arg(Arg::with_name("second"))
+ .arg(Arg::with_name("third").last(true))
+ .get_matches_from_safe(vec![
+ "prog", "one", "--", "three"
+ ]);
+
+assert!(res.is_ok());
+let m = res.unwrap();
+assert_eq!(m.value_of("third"), Some("three"));
+assert!(m.value_of("second").is_none());
+
Even if the positional argument marked .last(true) is the only argument left to parse,
+failing to use the -- syntax results in an error.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("first"))
+ .arg(Arg::with_name("second"))
+ .arg(Arg::with_name("third").last(true))
+ .get_matches_from_safe(vec![
+ "prog", "one", "two", "three"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
+
Sets whether or not the argument is required by default. Required by default means it is
+required, when no other conflicting rules have been evaluated. Conflicting rules take
+precedence over being required. Default: false
+
NOTE: Flags (i.e. not positional, or arguments that take values) cannot be required by
+default. This is simply because if a flag should be required, it should simply be implied
+as no additional information is required from user. Flags by their very nature are simply
+yes/no, or true/false.
+
+
+Arg::with_name("config")
+ .required(true)
+
Setting Arg::required(true) requires that the argument be used at runtime.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .required(true)
+ .takes_value(true)
+ .long("config"))
+ .get_matches_from_safe(vec![
+ "prog", "--config", "file.conf"
+ ]);
+
+assert!(res.is_ok());
+
Setting Arg::required(true) and not supplying that argument is an error.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .required(true)
+ .takes_value(true)
+ .long("config"))
+ .get_matches_from_safe(vec![
+ "prog"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
+
Requires that options use the --option=val syntax (i.e. an equals between the option and
+associated value) Default: false
+
NOTE: This setting also removes the default of allowing empty values and implies
+Arg::empty_values(false).
+
+
+Arg::with_name("config")
+ .long("config")
+ .takes_value(true)
+ .require_equals(true)
+
Setting Arg::require_equals(true) requires that the option have an equals sign between
+it and the associated value.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .require_equals(true)
+ .takes_value(true)
+ .long("config"))
+ .get_matches_from_safe(vec![
+ "prog", "--config=file.conf"
+ ]);
+
+assert!(res.is_ok());
+
Setting Arg::require_equals(true) and not supplying the equals will cause an error
+unless Arg::empty_values(true) is set.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .require_equals(true)
+ .takes_value(true)
+ .long("config"))
+ .get_matches_from_safe(vec![
+ "prog", "--config", "file.conf"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::EmptyValue);
+
Allows values which start with a leading hyphen (-)
+
WARNING: Take caution when using this setting combined with Arg::multiple(true), as
+this becomes ambiguous $ prog --arg -- -- val. All three --, --, val will be values
+when the user may have thought the second -- would constitute the normal, "Only
+positional args follow" idiom. To fix this, consider using Arg::number_of_values(1)
+
WARNING: When building your CLIs, consider the effects of allowing leading hyphens and
+the user passing in a value that matches a valid short. For example prog -opt -F where
+-F is supposed to be a value, yet -F is also a valid short for another arg. Care should
+should be taken when designing these args. This is compounded by the ability to "stack"
+short args. I.e. if -val is supposed to be a value, but -v, -a, and -l are all valid
+shorts.
+
+
+Arg::with_name("pattern")
+ .allow_hyphen_values(true)
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("pat")
+ .allow_hyphen_values(true)
+ .takes_value(true)
+ .long("pattern"))
+ .get_matches_from(vec![
+ "prog", "--pattern", "-file"
+ ]);
+
+assert_eq!(m.value_of("pat"), Some("-file"));
+
Not setting Arg::allow_hyphen_values(true) and supplying a value which starts with a
+hyphen is an error.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("pat")
+ .takes_value(true)
+ .long("pattern"))
+ .get_matches_from_safe(vec![
+ "prog", "--pattern", "-file"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
+
Sets an arg that override this arg's required setting. (i.e. this arg will be required
+unless this other argument is present).
+
Pro Tip: Using Arg::required_unless implies Arg::required and is therefore not
+mandatory to also set.
+
+
+Arg::with_name("config")
+ .required_unless("debug")
+
Setting Arg::required_unless(name) requires that the argument be used at runtime
+unless name is present. In the following example, the required argument is not
+provided, but it's not an error because the unless arg has been supplied.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .required_unless("dbg")
+ .takes_value(true)
+ .long("config"))
+ .arg(Arg::with_name("dbg")
+ .long("debug"))
+ .get_matches_from_safe(vec![
+ "prog", "--debug"
+ ]);
+
+assert!(res.is_ok());
+
Setting Arg::required_unless(name) and not supplying name or this arg is an error.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .required_unless("dbg")
+ .takes_value(true)
+ .long("config"))
+ .arg(Arg::with_name("dbg")
+ .long("debug"))
+ .get_matches_from_safe(vec![
+ "prog"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
+
Sets args that override this arg's required setting. (i.e. this arg will be required unless
+all these other arguments are present).
+
NOTE: If you wish for this argument to only be required if one of these args are
+present see Arg::required_unless_one
+
+
+Arg::with_name("config")
+ .required_unless_all(&["cfg", "dbg"])
+
Setting Arg::required_unless_all(names) requires that the argument be used at runtime
+unless all the args in names are present. In the following example, the required
+argument is not provided, but it's not an error because all the unless args have been
+supplied.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .required_unless_all(&["dbg", "infile"])
+ .takes_value(true)
+ .long("config"))
+ .arg(Arg::with_name("dbg")
+ .long("debug"))
+ .arg(Arg::with_name("infile")
+ .short("i")
+ .takes_value(true))
+ .get_matches_from_safe(vec![
+ "prog", "--debug", "-i", "file"
+ ]);
+
+assert!(res.is_ok());
+
Setting Arg::required_unless_all(names) and not supplying all of names or this
+arg is an error.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .required_unless_all(&["dbg", "infile"])
+ .takes_value(true)
+ .long("config"))
+ .arg(Arg::with_name("dbg")
+ .long("debug"))
+ .arg(Arg::with_name("infile")
+ .short("i")
+ .takes_value(true))
+ .get_matches_from_safe(vec![
+ "prog"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
+
Sets args that override this arg's required setting. (i.e. this arg will be required
+unless at least one of these other arguments are present).
+
NOTE: If you wish for this argument to only be required if all of these args are
+present see Arg::required_unless_all
+
+
+Arg::with_name("config")
+ .required_unless_all(&["cfg", "dbg"])
+
Setting Arg::required_unless_one(names) requires that the argument be used at runtime
+unless at least one of the args in names are present. In the following example, the
+required argument is not provided, but it's not an error because one the unless args
+have been supplied.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .required_unless_one(&["dbg", "infile"])
+ .takes_value(true)
+ .long("config"))
+ .arg(Arg::with_name("dbg")
+ .long("debug"))
+ .arg(Arg::with_name("infile")
+ .short("i")
+ .takes_value(true))
+ .get_matches_from_safe(vec![
+ "prog", "--debug"
+ ]);
+
+assert!(res.is_ok());
+
Setting Arg::required_unless_one(names) and not supplying at least one of names
+or this arg is an error.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .required_unless_one(&["dbg", "infile"])
+ .takes_value(true)
+ .long("config"))
+ .arg(Arg::with_name("dbg")
+ .long("debug"))
+ .arg(Arg::with_name("infile")
+ .short("i")
+ .takes_value(true))
+ .get_matches_from_safe(vec![
+ "prog"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
+
Sets a conflicting argument by name. I.e. when using this argument,
+the following argument can't be present and vice versa.
+
NOTE: Conflicting rules take precedence over being required by default. Conflict rules
+only need to be set for one of the two arguments, they do not need to be set for each.
+
NOTE: Defining a conflict is two-way, but does not need to defined for both arguments
+(i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not need
+need to also do B.conflicts_with(A))
+
+
+Arg::with_name("config")
+ .conflicts_with("debug")
+
Setting conflicting argument, and having both arguments present at runtime is an error.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .takes_value(true)
+ .conflicts_with("debug")
+ .long("config"))
+ .arg(Arg::with_name("debug")
+ .long("debug"))
+ .get_matches_from_safe(vec![
+ "prog", "--debug", "--config", "file.conf"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::ArgumentConflict);
+
The same as Arg::conflicts_with but allows specifying multiple two-way conlicts per
+argument.
+
NOTE: Conflicting rules take precedence over being required by default. Conflict rules
+only need to be set for one of the two arguments, they do not need to be set for each.
+
NOTE: Defining a conflict is two-way, but does not need to defined for both arguments
+(i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not need
+need to also do B.conflicts_with(A))
+
+
+Arg::with_name("config")
+ .conflicts_with_all(&["debug", "input"])
+
Setting conflicting argument, and having any of the arguments present at runtime with a
+conflicting argument is an error.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .takes_value(true)
+ .conflicts_with_all(&["debug", "input"])
+ .long("config"))
+ .arg(Arg::with_name("debug")
+ .long("debug"))
+ .arg(Arg::with_name("input")
+ .index(1))
+ .get_matches_from_safe(vec![
+ "prog", "--config", "file.conf", "file.txt"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::ArgumentConflict);
+
Sets a overridable argument by name. I.e. this argument and the following argument
+will override each other in POSIX style (whichever argument was specified at runtime
+last "wins")
+
NOTE: When an argument is overridden it is essentially as if it never was used, any
+conflicts, requirements, etc. are evaluated after all "overrides" have been removed
+
WARNING: Positional arguments cannot override themselves (or we would never be able
+to advance to the next positional). If a positional agument lists itself as an override,
+it is simply ignored.
+
+
+let m = App::new("prog")
+ .arg(Arg::from_usage("-f, --flag 'some flag'")
+ .conflicts_with("debug"))
+ .arg(Arg::from_usage("-d, --debug 'other flag'"))
+ .arg(Arg::from_usage("-c, --color 'third flag'")
+ .overrides_with("flag"))
+ .get_matches_from(vec![
+ "prog", "-f", "-d", "-c"]);
+
+
+assert!(m.is_present("color"));
+assert!(m.is_present("debug"));
+
+assert!(!m.is_present("flag"));
+
Care must be taken when using this setting, and having an arg override with itself. This
+is common practice when supporting things like shell aliases, config files, etc.
+However, when combined with multiple values, it can get dicy.
+Here is how clap handles such situations:
+
When a flag overrides itself, it's as if the flag was only ever used once (essentially
+preventing a "Unexpected multiple usage" error):
+
+
+let m = App::new("posix")
+ .arg(Arg::from_usage("--flag 'some flag'").overrides_with("flag"))
+ .get_matches_from(vec!["posix", "--flag", "--flag"]);
+assert!(m.is_present("flag"));
+assert_eq!(m.occurrences_of("flag"), 1);
+
Making a arg multiple(true) and override itself is essentially meaningless. Therefore
+clap ignores an override of self if it's a flag and it already accepts multiple occurrences.
+
+
+let m = App::new("posix")
+ .arg(Arg::from_usage("--flag... 'some flag'").overrides_with("flag"))
+ .get_matches_from(vec!["", "--flag", "--flag", "--flag", "--flag"]);
+assert!(m.is_present("flag"));
+assert_eq!(m.occurrences_of("flag"), 4);
+
Now notice with options (which do not set multiple(true)), it's as if only the last
+occurrence happened.
+
+
+let m = App::new("posix")
+ .arg(Arg::from_usage("--opt [val] 'some option'").overrides_with("opt"))
+ .get_matches_from(vec!["", "--opt=some", "--opt=other"]);
+assert!(m.is_present("opt"));
+assert_eq!(m.occurrences_of("opt"), 1);
+assert_eq!(m.value_of("opt"), Some("other"));
+
Just like flags, options with multiple(true) set, will ignore the "override self" setting.
+
+
+let m = App::new("posix")
+ .arg(Arg::from_usage("--opt [val]... 'some option'")
+ .overrides_with("opt"))
+ .get_matches_from(vec!["", "--opt", "first", "over", "--opt", "other", "val"]);
+assert!(m.is_present("opt"));
+assert_eq!(m.occurrences_of("opt"), 2);
+assert_eq!(m.values_of("opt").unwrap().collect::<Vec<_>>(), &["first", "over", "other", "val"]);
+
A safe thing to do if you'd like to support an option which supports multiple values, but
+also is "overridable" by itself, is to use use_delimiter(false) and not use
+multiple(true) while telling users to seperate values with a comma (i.e. val1,val2)
+
+
+let m = App::new("posix")
+ .arg(Arg::from_usage("--opt [val] 'some option'")
+ .overrides_with("opt")
+ .use_delimiter(false))
+ .get_matches_from(vec!["", "--opt=some,other", "--opt=one,two"]);
+assert!(m.is_present("opt"));
+assert_eq!(m.occurrences_of("opt"), 1);
+assert_eq!(m.values_of("opt").unwrap().collect::<Vec<_>>(), &["one,two"]);
+
Sets multiple mutually overridable arguments by name. I.e. this argument and the following
+argument will override each other in POSIX style (whichever argument was specified at
+runtime last "wins")
+
NOTE: When an argument is overridden it is essentially as if it never was used, any
+conflicts, requirements, etc. are evaluated after all "overrides" have been removed
+
+
+let m = App::new("prog")
+ .arg(Arg::from_usage("-f, --flag 'some flag'")
+ .conflicts_with("color"))
+ .arg(Arg::from_usage("-d, --debug 'other flag'"))
+ .arg(Arg::from_usage("-c, --color 'third flag'")
+ .overrides_with_all(&["flag", "debug"]))
+ .get_matches_from(vec![
+ "prog", "-f", "-d", "-c"]);
+
+
+assert!(m.is_present("color"));
+
+
+assert!(!m.is_present("debug"));
+assert!(!m.is_present("flag"));
+
pub fn requires(self, name: &'a str) -> Self[src]
Sets an argument by name that is required when this one is present I.e. when
+using this argument, the following argument must be present.
+
NOTE: Conflicting rules and override rules take precedence over being required
+
+
+Arg::with_name("config")
+ .requires("input")
+
Setting Arg::requires(name) requires that the argument be used at runtime if the
+defining argument is used. If the defining argument isn't used, the other argument isn't
+required
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .takes_value(true)
+ .requires("input")
+ .long("config"))
+ .arg(Arg::with_name("input")
+ .index(1))
+ .get_matches_from_safe(vec![
+ "prog"
+ ]);
+
+assert!(res.is_ok());
+
Setting Arg::requires(name) and not supplying that argument is an error.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .takes_value(true)
+ .requires("input")
+ .long("config"))
+ .arg(Arg::with_name("input")
+ .index(1))
+ .get_matches_from_safe(vec![
+ "prog", "--config", "file.conf"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
+
Allows a conditional requirement. The requirement will only become valid if this arg's value
+equals val.
+
NOTE: If using YAML the values should be laid out as follows
+
requires_if:
+ - [val, arg]
+
+
+
+Arg::with_name("config")
+ .requires_if("val", "arg")
+
Setting [Arg::requires_if(val, arg)] requires that the arg be used at runtime if the
+defining argument's value is equal to val. If the defining argument is anything other than
+val, the other argument isn't required.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .takes_value(true)
+ .requires_if("my.cfg", "other")
+ .long("config"))
+ .arg(Arg::with_name("other"))
+ .get_matches_from_safe(vec![
+ "prog", "--config", "some.cfg"
+ ]);
+
+assert!(res.is_ok());
+
Setting [Arg::requires_if(val, arg)] and setting the value to val but not supplying
+arg is an error.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .takes_value(true)
+ .requires_if("my.cfg", "input")
+ .long("config"))
+ .arg(Arg::with_name("input"))
+ .get_matches_from_safe(vec![
+ "prog", "--config", "my.cfg"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
+
Allows multiple conditional requirements. The requirement will only become valid if this arg's value
+equals val.
+
NOTE: If using YAML the values should be laid out as follows
+
requires_if:
+ - [val, arg]
+ - [val2, arg2]
+
+
+
+Arg::with_name("config")
+ .requires_ifs(&[
+ ("val", "arg"),
+ ("other_val", "arg2"),
+ ])
+
Setting [Arg::requires_ifs(&["val", "arg"])] requires that the arg be used at runtime if the
+defining argument's value is equal to val. If the defining argument's value is anything other
+than val, arg isn't required.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .takes_value(true)
+ .requires_ifs(&[
+ ("special.conf", "opt"),
+ ("other.conf", "other"),
+ ])
+ .long("config"))
+ .arg(Arg::with_name("opt")
+ .long("option")
+ .takes_value(true))
+ .arg(Arg::with_name("other"))
+ .get_matches_from_safe(vec![
+ "prog", "--config", "special.conf"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
+
Allows specifying that an argument is required conditionally. The requirement will only
+become valid if the specified arg's value equals val.
+
NOTE: If using YAML the values should be laid out as follows
+
required_if:
+ - [arg, val]
+
+
+
+Arg::with_name("config")
+ .required_if("other_arg", "value")
+
Setting [Arg::required_if(arg, val)] makes this arg required if the arg is used at
+runtime and it's value is equal to val. If the arg's value is anything other than val,
+this argument isn't required.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .takes_value(true)
+ .required_if("other", "special")
+ .long("config"))
+ .arg(Arg::with_name("other")
+ .long("other")
+ .takes_value(true))
+ .get_matches_from_safe(vec![
+ "prog", "--other", "not-special"
+ ]);
+
+assert!(res.is_ok());
+
Setting [Arg::required_if(arg, val)] and having arg used with a value of val but not
+using this arg is an error.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .takes_value(true)
+ .required_if("other", "special")
+ .long("config"))
+ .arg(Arg::with_name("other")
+ .long("other")
+ .takes_value(true))
+ .get_matches_from_safe(vec![
+ "prog", "--other", "special"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
+
Allows specifying that an argument is required based on multiple conditions. The
+conditions are set up in a (arg, val) style tuple. The requirement will only become valid
+if one of the specified arg's value equals it's corresponding val.
+
NOTE: If using YAML the values should be laid out as follows
+
required_if:
+ - [arg, val]
+ - [arg2, val2]
+
+
+
+Arg::with_name("config")
+ .required_ifs(&[
+ ("extra", "val"),
+ ("option", "spec")
+ ])
+
Setting [Arg::required_ifs(&[(arg, val)])] makes this arg required if any of the args
+are used at runtime and it's corresponding value is equal to val. If the arg's value is
+anything other than val, this argument isn't required.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .required_ifs(&[
+ ("extra", "val"),
+ ("option", "spec")
+ ])
+ .takes_value(true)
+ .long("config"))
+ .arg(Arg::with_name("extra")
+ .takes_value(true)
+ .long("extra"))
+ .arg(Arg::with_name("option")
+ .takes_value(true)
+ .long("option"))
+ .get_matches_from_safe(vec![
+ "prog", "--option", "other"
+ ]);
+
+assert!(res.is_ok());
+
Setting [Arg::required_ifs(&[(arg, val)])] and having any of the args used with it's
+value of val but not using this arg is an error.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .required_ifs(&[
+ ("extra", "val"),
+ ("option", "spec")
+ ])
+ .takes_value(true)
+ .long("config"))
+ .arg(Arg::with_name("extra")
+ .takes_value(true)
+ .long("extra"))
+ .arg(Arg::with_name("option")
+ .takes_value(true)
+ .long("option"))
+ .get_matches_from_safe(vec![
+ "prog", "--option", "spec"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
+
Sets multiple arguments by names that are required when this one is present I.e. when
+using this argument, the following arguments must be present.
+
NOTE: Conflicting rules and override rules take precedence over being required
+by default.
+
+
+Arg::with_name("config")
+ .requires_all(&["input", "output"])
+
Setting [Arg::requires_all(&[arg, arg2])] requires that all the arguments be used at
+runtime if the defining argument is used. If the defining argument isn't used, the other
+argument isn't required
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .takes_value(true)
+ .requires("input")
+ .long("config"))
+ .arg(Arg::with_name("input")
+ .index(1))
+ .arg(Arg::with_name("output")
+ .index(2))
+ .get_matches_from_safe(vec![
+ "prog"
+ ]);
+
+assert!(res.is_ok());
+
Setting [Arg::requires_all(&[arg, arg2])] and not supplying all the arguments is an
+error.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .takes_value(true)
+ .requires_all(&["input", "output"])
+ .long("config"))
+ .arg(Arg::with_name("input")
+ .index(1))
+ .arg(Arg::with_name("output")
+ .index(2))
+ .get_matches_from_safe(vec![
+ "prog", "--config", "file.conf", "in.txt"
+ ]);
+
+assert!(res.is_err());
+
+assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
+
[Arg::requires_all(&[arg, arg2])]: ./struct.Arg.html#method.requires_all
+
Specifies that the argument takes a value at run time.
+
NOTE: values for arguments may be specified in any of the following methods
+
+- Using a space such as
-o value or --option value
+- Using an equals and no space such as
-o=value or --option=value
+- Use a short and no space such as
-ovalue
+
+
NOTE: By default, args which allow multiple values are delimited by commas, meaning
+--option=val1,val2,val3 is three values for the --option argument. If you wish to
+change the delimiter to another character you can use Arg::value_delimiter(char),
+alternatively you can turn delimiting values OFF by using Arg::use_delimiter(false)
+
+
+Arg::with_name("config")
+ .takes_value(true)
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("mode")
+ .long("mode")
+ .takes_value(true))
+ .get_matches_from(vec![
+ "prog", "--mode", "fast"
+ ]);
+
+assert!(m.is_present("mode"));
+assert_eq!(m.value_of("mode"), Some("fast"));
+
Specifies if the possible values of an argument should be displayed in the help text or
+not. Defaults to false (i.e. show possible values)
+
This is useful for args with many values, or ones which are explained elsewhere in the
+help text.
+
+
+Arg::with_name("config")
+ .hide_possible_values(true)
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("mode")
+ .long("mode")
+ .possible_values(&["fast", "slow"])
+ .takes_value(true)
+ .hide_possible_values(true));
+
+
If we were to run the above program with --help the [values: fast, slow] portion of
+the help text would be omitted.
+
Specifies if the default value of an argument should be displayed in the help text or
+not. Defaults to false (i.e. show default value)
+
This is useful when default behavior of an arg is explained elsewhere in the help text.
+
+
+Arg::with_name("config")
+ .hide_default_value(true)
+
+
+let m = App::new("connect")
+ .arg(Arg::with_name("host")
+ .long("host")
+ .default_value("localhost")
+ .hide_default_value(true));
+
+
If we were to run the above program with --help the [default: localhost] portion of
+the help text would be omitted.
+
pub fn index(self, idx: u64) -> Self[src]
Specifies the index of a positional argument starting at 1.
+
NOTE: The index refers to position according to other positional argument. It does
+not define position in the argument list as a whole.
+
NOTE: If no Arg::short, or Arg::long have been defined, you can optionally
+leave off the index method, and the index will be assigned in order of evaluation.
+Utilizing the index method allows for setting indexes out of order
+
NOTE: When utilized with Arg::multiple(true), only the last positional argument
+may be defined as multiple (i.e. with the highest index)
+
+
Although not in this method directly, App will panic! if indexes are skipped (such
+as defining index(1) and index(3) but not index(2), or a positional argument is
+defined as multiple and is not the highest index
+
+
+Arg::with_name("config")
+ .index(1)
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("mode")
+ .index(1))
+ .arg(Arg::with_name("debug")
+ .long("debug"))
+ .get_matches_from(vec![
+ "prog", "--debug", "fast"
+ ]);
+
+assert!(m.is_present("mode"));
+assert_eq!(m.value_of("mode"), Some("fast"));
+
+
Specifies that the argument may appear more than once. For flags, this results
+in the number of occurrences of the flag being recorded. For example -ddd or -d -d -d
+would count as three occurrences. For options there is a distinct difference in multiple
+occurrences vs multiple values.
+
For example, --opt val1 val2 is one occurrence, but two values. Whereas
+--opt val1 --opt val2 is two occurrences.
+
WARNING:
+
Setting multiple(true) for an option with no other details, allows multiple values
+and multiple occurrences because it isn't possible to have more occurrences than values
+for options. Because multiple values are allowed, --option val1 val2 val3 is perfectly
+valid, be careful when designing a CLI where positional arguments are expected after a
+option which accepts multiple values, as clap will continue parsing values until it
+reaches the max or specific number of values defined, or another flag or option.
+
Pro Tip:
+
It's possible to define an option which allows multiple occurrences, but only one value per
+occurrence. To do this use Arg::number_of_values(1) in coordination with
+Arg::multiple(true).
+
WARNING:
+
When using args with multiple(true) on options or positionals (i.e. those args that
+accept values) and subcommands, one needs to consider the possibility of an argument value
+being the same as a valid subcommand. By default clap will parse the argument in question
+as a value only if a value is possible at that moment. Otherwise it will be parsed as a
+subcommand. In effect, this means using multiple(true) with no additional parameters and
+a possible value that coincides with a subcommand name, the subcommand cannot be called
+unless another argument is passed first.
+
As an example, consider a CLI with an option --ui-paths=<paths>... and subcommand signer
+
The following would be parsed as values to --ui-paths.
+
$ program --ui-paths path1 path2 signer
+
+
This is because --ui-paths accepts multiple values. clap will continue parsing values
+until another argument is reached and it knows --ui-paths is done.
+
By adding additional parameters to --ui-paths we can solve this issue. Consider adding
+Arg::number_of_values(1) as discussed above. The following are all valid, and signer
+is parsed as both a subcommand and a value in the second case.
+
$ program --ui-paths path1 signer
+$ program --ui-paths path1 --ui-paths signer signer
+
+
+
+Arg::with_name("debug")
+ .short("d")
+ .multiple(true)
+
An example with flags
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("verbose")
+ .multiple(true)
+ .short("v"))
+ .get_matches_from(vec![
+ "prog", "-v", "-v", "-v"
+ ]);
+
+assert!(m.is_present("verbose"));
+assert_eq!(m.occurrences_of("verbose"), 3);
+
An example with options
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("file")
+ .multiple(true)
+ .takes_value(true)
+ .short("F"))
+ .get_matches_from(vec![
+ "prog", "-F", "file1", "file2", "file3"
+ ]);
+
+assert!(m.is_present("file"));
+assert_eq!(m.occurrences_of("file"), 1);
+let files: Vec<_> = m.values_of("file").unwrap().collect();
+assert_eq!(files, ["file1", "file2", "file3"]);
+
This is functionally equivalent to the example above
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("file")
+ .multiple(true)
+ .takes_value(true)
+ .short("F"))
+ .get_matches_from(vec![
+ "prog", "-F", "file1", "-F", "file2", "-F", "file3"
+ ]);
+let files: Vec<_> = m.values_of("file").unwrap().collect();
+assert_eq!(files, ["file1", "file2", "file3"]);
+
+assert!(m.is_present("file"));
+assert_eq!(m.occurrences_of("file"), 3);
+let files: Vec<_> = m.values_of("file").unwrap().collect();
+assert_eq!(files, ["file1", "file2", "file3"]);
+
A common mistake is to define an option which allows multiples, and a positional argument
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("file")
+ .multiple(true)
+ .takes_value(true)
+ .short("F"))
+ .arg(Arg::with_name("word")
+ .index(1))
+ .get_matches_from(vec![
+ "prog", "-F", "file1", "file2", "file3", "word"
+ ]);
+
+assert!(m.is_present("file"));
+let files: Vec<_> = m.values_of("file").unwrap().collect();
+assert_eq!(files, ["file1", "file2", "file3", "word"]);
+assert!(!m.is_present("word"));
+
The problem is clap doesn't know when to stop parsing values for "files". This is further
+compounded by if we'd said word -F file1 file2 it would have worked fine, so it would
+appear to only fail sometimes...not good!
+
A solution for the example above is to specify that -F only accepts one value, but is
+allowed to appear multiple times
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("file")
+ .multiple(true)
+ .takes_value(true)
+ .number_of_values(1)
+ .short("F"))
+ .arg(Arg::with_name("word")
+ .index(1))
+ .get_matches_from(vec![
+ "prog", "-F", "file1", "-F", "file2", "-F", "file3", "word"
+ ]);
+
+assert!(m.is_present("file"));
+let files: Vec<_> = m.values_of("file").unwrap().collect();
+assert_eq!(files, ["file1", "file2", "file3"]);
+assert!(m.is_present("word"));
+assert_eq!(m.value_of("word"), Some("word"));
+
As a final example, notice if we define Arg::number_of_values(1) and try to run the
+problem example above, it would have been a runtime error with a pretty message to the
+user :)
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("file")
+ .multiple(true)
+ .takes_value(true)
+ .number_of_values(1)
+ .short("F"))
+ .arg(Arg::with_name("word")
+ .index(1))
+ .get_matches_from_safe(vec![
+ "prog", "-F", "file1", "file2", "file3", "word"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);
+
Specifies a value that stops parsing multiple values of a give argument. By default when
+one sets multiple(true) on an argument, clap will continue parsing values for that
+argument until it reaches another valid argument, or one of the other more specific settings
+for multiple values is used (such as min_values, max_values or
+number_of_values).
+
NOTE: This setting only applies to options and positional arguments
+
NOTE: When the terminator is passed in on the command line, it is not stored as one
+of the values
+
+
+Arg::with_name("vals")
+ .takes_value(true)
+ .multiple(true)
+ .value_terminator(";")
+
The following example uses two arguments, a sequence of commands, and the location in which
+to perform them
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("cmds")
+ .multiple(true)
+ .allow_hyphen_values(true)
+ .value_terminator(";"))
+ .arg(Arg::with_name("location"))
+ .get_matches_from(vec![
+ "prog", "find", "-type", "f", "-name", "special", ";", "/home/clap"
+ ]);
+let cmds: Vec<_> = m.values_of("cmds").unwrap().collect();
+assert_eq!(&cmds, &["find", "-type", "f", "-name", "special"]);
+assert_eq!(m.value_of("location"), Some("/home/clap"));
+
Specifies that an argument can be matched to all child SubCommands.
+
NOTE: Global arguments only propagate down, not up (to parent commands), however
+their values once a user uses them will be propagated back up to parents. In effect, this
+means one should define all global arguments at the top level, however it doesn't matter
+where the user uses the global argument.
+
+
+Arg::with_name("debug")
+ .short("d")
+ .global(true)
+
For example, assume an application with two subcommands, and you'd like to define a
+--verbose flag that can be called on any of the subcommands and parent, but you don't
+want to clutter the source with three duplicate Arg definitions.
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("verb")
+ .long("verbose")
+ .short("v")
+ .global(true))
+ .subcommand(SubCommand::with_name("test"))
+ .subcommand(SubCommand::with_name("do-stuff"))
+ .get_matches_from(vec![
+ "prog", "do-stuff", "--verbose"
+ ]);
+
+assert_eq!(m.subcommand_name(), Some("do-stuff"));
+let sub_m = m.subcommand_matches("do-stuff").unwrap();
+assert!(sub_m.is_present("verb"));
+
Allows an argument to accept explicitly empty values. An empty value must be specified at
+the command line with an explicit "", or ''
+
NOTE: Defaults to true (Explicitly empty values are allowed)
+
NOTE: Implicitly sets Arg::takes_value(true) when set to false
+
+
+Arg::with_name("file")
+ .long("file")
+ .empty_values(false)
+
The default is to allow empty values, such as --option "" would be an empty value. But
+we can change to make empty values become an error.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .long("config")
+ .short("v")
+ .empty_values(false))
+ .get_matches_from_safe(vec![
+ "prog", "--config="
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::EmptyValue);
+
Hides an argument from help message output.
+
NOTE: Implicitly sets Arg::hidden_short_help(true) and Arg::hidden_long_help(true)
+when set to true
+
NOTE: This does not hide the argument from usage strings on error
+
+
+Arg::with_name("debug")
+ .hidden(true)
+
Setting hidden(true) will hide the argument when displaying help text
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .long("config")
+ .hidden(true)
+ .help("Some help text describing the --config arg"))
+ .get_matches_from(vec![
+ "prog", "--help"
+ ]);
+
The above example displays
+
helptest
+
+USAGE:
+ helptest [FLAGS]
+
+FLAGS:
+-h, --help Prints help information
+-V, --version Prints version information
+
+
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 an error message.
+
NOTE: This setting only applies to options and positional arguments
+
+
+Arg::with_name("mode")
+ .takes_value(true)
+ .possible_values(&["fast", "slow", "medium"])
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("mode")
+ .long("mode")
+ .takes_value(true)
+ .possible_values(&["fast", "slow", "medium"]))
+ .get_matches_from(vec![
+ "prog", "--mode", "fast"
+ ]);
+assert!(m.is_present("mode"));
+assert_eq!(m.value_of("mode"), Some("fast"));
+
The next example shows a failed parse from using a value which wasn't defined as one of the
+possible values.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("mode")
+ .long("mode")
+ .takes_value(true)
+ .possible_values(&["fast", "slow", "medium"]))
+ .get_matches_from_safe(vec![
+ "prog", "--mode", "wrong"
+ ]);
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::InvalidValue);
+
Specifies a possible value for this argument, one at a time. At runtime, clap verifies
+that only one of the specified values was used, or fails with error message.
+
NOTE: This setting only applies to options and positional arguments
+
+
+Arg::with_name("mode")
+ .takes_value(true)
+ .possible_value("fast")
+ .possible_value("slow")
+ .possible_value("medium")
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("mode")
+ .long("mode")
+ .takes_value(true)
+ .possible_value("fast")
+ .possible_value("slow")
+ .possible_value("medium"))
+ .get_matches_from(vec![
+ "prog", "--mode", "fast"
+ ]);
+assert!(m.is_present("mode"));
+assert_eq!(m.value_of("mode"), Some("fast"));
+
The next example shows a failed parse from using a value which wasn't defined as one of the
+possible values.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("mode")
+ .long("mode")
+ .takes_value(true)
+ .possible_value("fast")
+ .possible_value("slow")
+ .possible_value("medium"))
+ .get_matches_from_safe(vec![
+ "prog", "--mode", "wrong"
+ ]);
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::InvalidValue);
+
When used with [Arg::possible_values] it allows the argument value to pass validation even if
+the case differs from that of the specified possible_value.
+
Pro Tip: Use this setting with arg_enum!
+
+
+let m = App::new("pv")
+ .arg(Arg::with_name("option")
+ .long("--option")
+ .takes_value(true)
+ .possible_value("test123")
+ .case_insensitive(true))
+ .get_matches_from(vec![
+ "pv", "--option", "TeSt123",
+ ]);
+
+assert!(m.value_of("option").unwrap().eq_ignore_ascii_case("test123"));
+
This setting also works when multiple values can be defined:
+
+
+let m = App::new("pv")
+ .arg(Arg::with_name("option")
+ .short("-o")
+ .long("--option")
+ .takes_value(true)
+ .possible_value("test123")
+ .possible_value("test321")
+ .multiple(true)
+ .case_insensitive(true))
+ .get_matches_from(vec![
+ "pv", "--option", "TeSt123", "teST123", "tESt321"
+ ]);
+
+let matched_vals = m.values_of("option").unwrap().collect::<Vec<_>>();
+assert_eq!(&*matched_vals, &["TeSt123", "teST123", "tESt321"]);
+
pub fn group(self, name: &'a str) -> Self[src]
Specifies the name of the ArgGroup the argument belongs to.
+
+
+Arg::with_name("debug")
+ .long("debug")
+ .group("mode")
+
Multiple arguments can be a member of a single group and then the group checked as if it
+was one of said arguments.
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("debug")
+ .long("debug")
+ .group("mode"))
+ .arg(Arg::with_name("verbose")
+ .long("verbose")
+ .group("mode"))
+ .get_matches_from(vec![
+ "prog", "--debug"
+ ]);
+assert!(m.is_present("mode"));
+
Specifies the names of multiple ArgGroup's the argument belongs to.
+
+
+Arg::with_name("debug")
+ .long("debug")
+ .groups(&["mode", "verbosity"])
+
Arguments can be members of multiple groups and then the group checked as if it
+was one of said arguments.
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("debug")
+ .long("debug")
+ .groups(&["mode", "verbosity"]))
+ .arg(Arg::with_name("verbose")
+ .long("verbose")
+ .groups(&["mode", "verbosity"]))
+ .get_matches_from(vec![
+ "prog", "--debug"
+ ]);
+assert!(m.is_present("mode"));
+assert!(m.is_present("verbosity"));
+
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: Does not require Arg::multiple(true) to be set. Setting
+Arg::multiple(true) would allow -f <file> <file> <file> -f <file> <file> <file> where
+as not setting Arg::multiple(true) would only allow one occurrence of this argument.
+
+
+Arg::with_name("file")
+ .short("f")
+ .number_of_values(3)
+
Not supplying the correct number of values is an error
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("file")
+ .takes_value(true)
+ .number_of_values(2)
+ .short("F"))
+ .get_matches_from_safe(vec![
+ "prog", "-F", "file1"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::WrongNumberOfValues);
+
Allows one to perform a custom validation on the argument value. You provide a closure
+which accepts a String value, and return a Result where the Err(String) is a
+message displayed to the user.
+
NOTE: The error message does not need to contain the error: portion, only the
+message as all errors will appear as
+error: Invalid value for '<arg>': <YOUR MESSAGE> where <arg> is replaced by the actual
+arg, and <YOUR MESSAGE> is the String you return as the error.
+
NOTE: There is a small performance hit for using validators, as they are implemented
+with Rc pointers. And the value to be checked will be allocated an extra time in order
+to to be passed to the closure. This performance hit is extremely minimal in the grand
+scheme of things.
+
+
+fn has_at(v: String) -> Result<(), String> {
+ if v.contains("@") { return Ok(()); }
+ Err(String::from("The value did not contain the required @ sigil"))
+}
+let res = App::new("prog")
+ .arg(Arg::with_name("file")
+ .index(1)
+ .validator(has_at))
+ .get_matches_from_safe(vec![
+ "prog", "some@file"
+ ]);
+assert!(res.is_ok());
+assert_eq!(res.unwrap().value_of("file"), Some("some@file"));
+
Works identically to Validator but is intended to be used with values that could
+contain non UTF-8 formatted strings.
+
+
+fn has_ampersand(v: &OsStr) -> Result<(), OsString> {
+ if v.as_bytes().iter().any(|b| *b == b'&') { return Ok(()); }
+ Err(OsString::from("The value did not contain the required & sigil"))
+}
+let res = App::new("prog")
+ .arg(Arg::with_name("file")
+ .index(1)
+ .validator_os(has_ampersand))
+ .get_matches_from_safe(vec![
+ "prog", "Fish & chips"
+ ]);
+assert!(res.is_ok());
+assert_eq!(res.unwrap().value_of("file"), Some("Fish & chips"));
+
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: This does not implicitly set Arg::multiple(true). This is because
+-o val -o val is multiple occurrences but a single value and -o val1 val2 is a single
+occurrence with multiple values. For positional arguments this does set
+Arg::multiple(true) because there is no way to determine the difference between multiple
+occurrences and multiple values.
+
+
+Arg::with_name("file")
+ .short("f")
+ .max_values(3)
+
Supplying less than the maximum number of values is allowed
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("file")
+ .takes_value(true)
+ .max_values(3)
+ .short("F"))
+ .get_matches_from_safe(vec![
+ "prog", "-F", "file1", "file2"
+ ]);
+
+assert!(res.is_ok());
+let m = res.unwrap();
+let files: Vec<_> = m.values_of("file").unwrap().collect();
+assert_eq!(files, ["file1", "file2"]);
+
Supplying more than the maximum number of values is an error
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("file")
+ .takes_value(true)
+ .max_values(2)
+ .short("F"))
+ .get_matches_from_safe(vec![
+ "prog", "-F", "file1", "file2", "file3"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::TooManyValues);
+
Specifies the minimum number of values 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 does not implicitly set Arg::multiple(true). This is because
+-o val -o val is multiple occurrences but a single value and -o val1 val2 is a single
+occurrence with multiple values. For positional arguments this does set
+Arg::multiple(true) because there is no way to determine the difference between multiple
+occurrences and multiple values.
+
+
+Arg::with_name("file")
+ .short("f")
+ .min_values(3)
+
Supplying more than the minimum number of values is allowed
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("file")
+ .takes_value(true)
+ .min_values(2)
+ .short("F"))
+ .get_matches_from_safe(vec![
+ "prog", "-F", "file1", "file2", "file3"
+ ]);
+
+assert!(res.is_ok());
+let m = res.unwrap();
+let files: Vec<_> = m.values_of("file").unwrap().collect();
+assert_eq!(files, ["file1", "file2", "file3"]);
+
Supplying less than the minimum number of values is an error
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("file")
+ .takes_value(true)
+ .min_values(2)
+ .short("F"))
+ .get_matches_from_safe(vec![
+ "prog", "-F", "file1"
+ ]);
+
+assert!(res.is_err());
+assert_eq!(res.unwrap_err().kind, ErrorKind::TooFewValues);
+
Specifies whether or not an argument should allow grouping of multiple values via a
+delimiter. I.e. should --option=val1,val2,val3 be parsed as three values (val1, val2,
+and val3) or as a single value (val1,val2,val3). Defaults to using , (comma) as the
+value delimiter for all arguments that accept values (options and positional arguments)
+
NOTE: The default is false. When set to true the default Arg::value_delimiter
+is the comma ,.
+
+
The following example shows the default behavior.
+
+
+let delims = App::new("prog")
+ .arg(Arg::with_name("option")
+ .long("option")
+ .use_delimiter(true)
+ .takes_value(true))
+ .get_matches_from(vec![
+ "prog", "--option=val1,val2,val3",
+ ]);
+
+assert!(delims.is_present("option"));
+assert_eq!(delims.occurrences_of("option"), 1);
+assert_eq!(delims.values_of("option").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]);
+
The next example shows the difference when turning delimiters off. This is the default
+behavior
+
+
+let nodelims = App::new("prog")
+ .arg(Arg::with_name("option")
+ .long("option")
+ .use_delimiter(false)
+ .takes_value(true))
+ .get_matches_from(vec![
+ "prog", "--option=val1,val2,val3",
+ ]);
+
+assert!(nodelims.is_present("option"));
+assert_eq!(nodelims.occurrences_of("option"), 1);
+assert_eq!(nodelims.value_of("option").unwrap(), "val1,val2,val3");
+
Specifies that multiple values may only be set using the delimiter. This means if an
+if an option is encountered, and no delimiter is found, it automatically assumed that no
+additional values for that option follow. This is unlike the default, where it is generally
+assumed that more values will follow regardless of whether or not a delimiter is used.
+
NOTE: The default is false.
+
NOTE: Setting this to true implies Arg::use_delimiter(true)
+
NOTE: It's a good idea to inform the user that use of a delimiter is required, either
+through help text or other means.
+
+
These examples demonstrate what happens when require_delimiter(true) is used. Notice
+everything works in this first example, as we use a delimiter, as expected.
+
+
+let delims = App::new("prog")
+ .arg(Arg::with_name("opt")
+ .short("o")
+ .takes_value(true)
+ .multiple(true)
+ .require_delimiter(true))
+ .get_matches_from(vec![
+ "prog", "-o", "val1,val2,val3",
+ ]);
+
+assert!(delims.is_present("opt"));
+assert_eq!(delims.values_of("opt").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]);
+
In this next example, we will not use a delimiter. Notice it's now an error.
+
+
+let res = App::new("prog")
+ .arg(Arg::with_name("opt")
+ .short("o")
+ .takes_value(true)
+ .multiple(true)
+ .require_delimiter(true))
+ .get_matches_from_safe(vec![
+ "prog", "-o", "val1", "val2", "val3",
+ ]);
+
+assert!(res.is_err());
+let err = res.unwrap_err();
+assert_eq!(err.kind, ErrorKind::UnknownArgument);
+
What's happening is -o is getting val1, and because delimiters are required yet none
+were present, it stops parsing -o. At this point it reaches val2 and because no
+positional arguments have been defined, it's an error of an unexpected argument.
+
In this final example, we contrast the above with clap's default behavior where the above
+is not an error.
+
+
+let delims = App::new("prog")
+ .arg(Arg::with_name("opt")
+ .short("o")
+ .takes_value(true)
+ .multiple(true))
+ .get_matches_from(vec![
+ "prog", "-o", "val1", "val2", "val3",
+ ]);
+
+assert!(delims.is_present("opt"));
+assert_eq!(delims.values_of("opt").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]);
+
Specifies the separator to use when values are clumped together, defaults to , (comma).
+
NOTE: implicitly sets Arg::use_delimiter(true)
+
NOTE: implicitly sets Arg::takes_value(true)
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("config")
+ .short("c")
+ .long("config")
+ .value_delimiter(";"))
+ .get_matches_from(vec![
+ "prog", "--config=val1;val2;val3"
+ ]);
+
+assert_eq!(m.values_of("config").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"])
+
Specify multiple 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).
+
This setting can be very helpful when describing the type of input the user should be
+using, such as FILE, INTERFACE, etc. Although not required, it's somewhat convention to
+use all capital letters for the value name.
+
Pro Tip: It may help to use Arg::next_line_help(true) if there are long, or
+multiple value names in order to not throw off the help text alignment of all options.
+
NOTE: This implicitly sets Arg::number_of_values if the number of value names is
+greater than one. I.e. 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: implicitly sets Arg::takes_value(true)
+
NOTE: Does not require or imply Arg::multiple(true).
+
+
+Arg::with_name("speed")
+ .short("s")
+ .value_names(&["fast", "slow"])
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("io")
+ .long("io-files")
+ .value_names(&["INFILE", "OUTFILE"]))
+ .get_matches_from(vec![
+ "prog", "--help"
+ ]);
+
Running the above program produces the following output
+
valnames
+
+USAGE:
+ valnames [FLAGS] [OPTIONS]
+
+FLAGS:
+ -h, --help Prints help information
+ -V, --version Prints version information
+
+OPTIONS:
+ --io-files <INFILE> <OUTFILE> Some help text
+
+
Specifies the name for value of option or positional arguments inside of help
+documentation. This name is cosmetic only, the name is not used to access arguments.
+This setting can be very helpful when describing the type of input the user should be
+using, such as FILE, INTERFACE, etc. Although not required, it's somewhat convention to
+use all capital letters for the value name.
+
NOTE: implicitly sets Arg::takes_value(true)
+
+
+Arg::with_name("cfg")
+ .long("config")
+ .value_name("FILE")
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("config")
+ .long("config")
+ .value_name("FILE"))
+ .get_matches_from(vec![
+ "prog", "--help"
+ ]);
+
Running the above program produces the following output
+
valnames
+
+USAGE:
+ valnames [FLAGS] [OPTIONS]
+
+FLAGS:
+ -h, --help Prints help information
+ -V, --version Prints version information
+
+OPTIONS:
+ --config <FILE> Some help text
+
+
Specifies the value of the argument when not specified at runtime.
+
NOTE: If the user does not use this argument at runtime, ArgMatches::occurrences_of
+will return 0 even though the ArgMatches::value_of will return the default specified.
+
NOTE: If the user does not use this argument at runtime ArgMatches::is_present will
+still return true. If you wish to determine whether the argument was used at runtime or
+not, consider ArgMatches::occurrences_of which will return 0 if the argument was not
+used at runtime.
+
NOTE: This setting is perfectly compatible with Arg::default_value_if but slightly
+different. Arg::default_value only takes affect when the user has not provided this arg
+at runtime. Arg::default_value_if however only takes affect when the user has not provided
+a value at runtime and these other conditions are met as well. If you have set
+Arg::default_value and Arg::default_value_if, and the user did not provide a this
+arg at runtime, nor did were the conditions met for Arg::default_value_if, the
+Arg::default_value will be applied.
+
NOTE: This implicitly sets Arg::takes_value(true).
+
NOTE: This setting effectively disables AppSettings::ArgRequiredElseHelp if used in
+conjunction as it ensures that some argument will always be present.
+
+
First we use the default value without providing any value at runtime.
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("opt")
+ .long("myopt")
+ .default_value("myval"))
+ .get_matches_from(vec![
+ "prog"
+ ]);
+
+assert_eq!(m.value_of("opt"), Some("myval"));
+assert!(m.is_present("opt"));
+assert_eq!(m.occurrences_of("opt"), 0);
+
Next we provide a value at runtime to override the default.
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("opt")
+ .long("myopt")
+ .default_value("myval"))
+ .get_matches_from(vec![
+ "prog", "--myopt=non_default"
+ ]);
+
+assert_eq!(m.value_of("opt"), Some("non_default"));
+assert!(m.is_present("opt"));
+assert_eq!(m.occurrences_of("opt"), 1);
+
Provides a default value in the exact same manner as [Arg::default_value]
+only using [OsStr]s instead.
+[Arg::default_value]: ./struct.Arg.html#method.default_value
+[OsStr]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html
+
Specifies the value of the argument if arg has been used at runtime. If val is set to
+None, arg only needs to be present. If val is set to "some-val" then arg must be
+present at runtime and have the value val.
+
NOTE: This setting is perfectly compatible with Arg::default_value but slightly
+different. Arg::default_value only takes affect when the user has not provided this arg
+at runtime. This setting however only takes affect when the user has not provided a value at
+runtime and these other conditions are met as well. If you have set Arg::default_value
+and Arg::default_value_if, and the user did not provide a this arg at runtime, nor did
+were the conditions met for Arg::default_value_if, the Arg::default_value will be
+applied.
+
NOTE: This implicitly sets Arg::takes_value(true).
+
NOTE: If using YAML the values should be laid out as follows (None can be represented
+as null in YAML)
+
default_value_if:
+ - [arg, val, default]
+
+
+
First we use the default value only if another arg is present at runtime.
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("flag")
+ .long("flag"))
+ .arg(Arg::with_name("other")
+ .long("other")
+ .default_value_if("flag", None, "default"))
+ .get_matches_from(vec![
+ "prog", "--flag"
+ ]);
+
+assert_eq!(m.value_of("other"), Some("default"));
+
Next we run the same test, but without providing --flag.
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("flag")
+ .long("flag"))
+ .arg(Arg::with_name("other")
+ .long("other")
+ .default_value_if("flag", None, "default"))
+ .get_matches_from(vec![
+ "prog"
+ ]);
+
+assert_eq!(m.value_of("other"), None);
+
Now lets only use the default value if --opt contains the value special.
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("opt")
+ .takes_value(true)
+ .long("opt"))
+ .arg(Arg::with_name("other")
+ .long("other")
+ .default_value_if("opt", Some("special"), "default"))
+ .get_matches_from(vec![
+ "prog", "--opt", "special"
+ ]);
+
+assert_eq!(m.value_of("other"), Some("default"));
+
We can run the same test and provide any value other than special and we won't get a
+default value.
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("opt")
+ .takes_value(true)
+ .long("opt"))
+ .arg(Arg::with_name("other")
+ .long("other")
+ .default_value_if("opt", Some("special"), "default"))
+ .get_matches_from(vec![
+ "prog", "--opt", "hahaha"
+ ]);
+
+assert_eq!(m.value_of("other"), None);
+
Provides a conditional default value in the exact same manner as [Arg::default_value_if]
+only using [OsStr]s instead.
+[Arg::default_value_if]: ./struct.Arg.html#method.default_value_if
+[OsStr]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html
+
Specifies multiple values and conditions in the same manner as [Arg::default_value_if].
+The method takes a slice of tuples in the (arg, Option<val>, default) format.
+
NOTE: The conditions are stored in order and evaluated in the same order. I.e. the first
+if multiple conditions are true, the first one found will be applied and the ultimate value.
+
NOTE: If using YAML the values should be laid out as follows
+
default_value_if:
+ - [arg, val, default]
+ - [arg2, null, default2]
+
+
+
First we use the default value only if another arg is present at runtime.
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("flag")
+ .long("flag"))
+ .arg(Arg::with_name("opt")
+ .long("opt")
+ .takes_value(true))
+ .arg(Arg::with_name("other")
+ .long("other")
+ .default_value_ifs(&[
+ ("flag", None, "default"),
+ ("opt", Some("channal"), "chan"),
+ ]))
+ .get_matches_from(vec![
+ "prog", "--opt", "channal"
+ ]);
+
+assert_eq!(m.value_of("other"), Some("chan"));
+
Next we run the same test, but without providing --flag.
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("flag")
+ .long("flag"))
+ .arg(Arg::with_name("other")
+ .long("other")
+ .default_value_ifs(&[
+ ("flag", None, "default"),
+ ("opt", Some("channal"), "chan"),
+ ]))
+ .get_matches_from(vec![
+ "prog"
+ ]);
+
+assert_eq!(m.value_of("other"), None);
+
We can also see that these values are applied in order, and if more than one condition is
+true, only the first evaluated "wins"
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("flag")
+ .long("flag"))
+ .arg(Arg::with_name("opt")
+ .long("opt")
+ .takes_value(true))
+ .arg(Arg::with_name("other")
+ .long("other")
+ .default_value_ifs(&[
+ ("flag", None, "default"),
+ ("opt", Some("channal"), "chan"),
+ ]))
+ .get_matches_from(vec![
+ "prog", "--opt", "channal", "--flag"
+ ]);
+
+assert_eq!(m.value_of("other"), Some("default"));
+
Provides multiple conditional default values in the exact same manner as
+[Arg::default_value_ifs] only using [OsStr]s instead.
+[Arg::default_value_ifs]: ./struct.Arg.html#method.default_value_ifs
+[OsStr]: https://doc.rust-lang.org/std/ffi/struct.OsStr.html
+
pub fn env(self, name: &'a str) -> Self[src]
Specifies that if the value is not passed in as an argument, that it should be retrieved
+from the environment, if available. If it is not present in the environment, then default
+rules will apply.
+
NOTE: If the user does not use this argument at runtime, ArgMatches::occurrences_of
+will return 0 even though the ArgMatches::value_of will return the default specified.
+
NOTE: If the user does not use this argument at runtime ArgMatches::is_present will
+return true if the variable is present in the environment . If you wish to determine whether
+the argument was used at runtime or not, consider ArgMatches::occurrences_of which will
+return 0 if the argument was not used at runtime.
+
NOTE: This implicitly sets Arg::takes_value(true).
+
NOTE: If Arg::multiple(true) is set then Arg::use_delimiter(true) should also be
+set. Otherwise, only a single argument will be returned from the environment variable. The
+default delimiter is , and follows all the other delimiter rules.
+
+
In this example, we show the variable coming from the environment:
+
+
+
+env::set_var("MY_FLAG", "env");
+
+let m = App::new("prog")
+ .arg(Arg::with_name("flag")
+ .long("flag")
+ .env("MY_FLAG"))
+ .get_matches_from(vec![
+ "prog"
+ ]);
+
+assert_eq!(m.value_of("flag"), Some("env"));
+
In this example, we show the variable coming from an option on the CLI:
+
+
+
+env::set_var("MY_FLAG", "env");
+
+let m = App::new("prog")
+ .arg(Arg::with_name("flag")
+ .long("flag")
+ .env("MY_FLAG"))
+ .get_matches_from(vec![
+ "prog", "--flag", "opt"
+ ]);
+
+assert_eq!(m.value_of("flag"), Some("opt"));
+
In this example, we show the variable coming from the environment even with the
+presence of a default:
+
+
+
+env::set_var("MY_FLAG", "env");
+
+let m = App::new("prog")
+ .arg(Arg::with_name("flag")
+ .long("flag")
+ .env("MY_FLAG")
+ .default_value("default"))
+ .get_matches_from(vec![
+ "prog"
+ ]);
+
+assert_eq!(m.value_of("flag"), Some("env"));
+
In this example, we show the use of multiple values in a single environment variable:
+
+
+
+env::set_var("MY_FLAG_MULTI", "env1,env2");
+
+let m = App::new("prog")
+ .arg(Arg::with_name("flag")
+ .long("flag")
+ .env("MY_FLAG_MULTI")
+ .multiple(true)
+ .use_delimiter(true))
+ .get_matches_from(vec![
+ "prog"
+ ]);
+
+assert_eq!(m.values_of("flag").unwrap().collect::<Vec<_>>(), vec!["env1", "env2"]);
+
pub fn env_os(self, name: &'a OsStr) -> Self[src]
Specifies that if the value is not passed in as an argument, that it should be retrieved
+from the environment if available in the exact same manner as [Arg::env] only using
+[OsStr]s instead.
+
@TODO @p2 @docs @release: write docs
+
When set to true the help string will be displayed on the line after the argument and
+indented once. This can be helpful for arguments with very long or complex help messages.
+This can also be helpful for arguments with very long flag names, or many/long value names.
+
NOTE: To apply this setting to all arguments consider using
+AppSettings::NextLineHelp
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("opt")
+ .long("long-option-flag")
+ .short("o")
+ .takes_value(true)
+ .value_names(&["value1", "value2"])
+ .help("Some really long help and complex\n\
+ help that makes more sense to be\n\
+ on a line after the option")
+ .next_line_help(true))
+ .get_matches_from(vec![
+ "prog", "--help"
+ ]);
+
The above example displays the following help message
+
nlh
+
+USAGE:
+ nlh [FLAGS] [OPTIONS]
+
+FLAGS:
+ -h, --help Prints help information
+ -V, --version Prints version information
+
+OPTIONS:
+ -o, --long-option-flag <value1> <value2>
+ Some really long help and complex
+ help that makes more sense to be
+ on a line after the option
+
+
Allows custom ordering of args within the help message. Args with a lower value will be
+displayed first in the help message. This is helpful when one would like to emphasise
+frequently used args, or prioritize those towards the top of the list. Duplicate values
+are allowed. Args with duplicate display orders will be displayed in alphabetical
+order.
+
NOTE: The default is 999 for all arguments.
+
NOTE: This setting is ignored for positional arguments which are always displayed in
+index order.
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("a")
+
+
+ .long("long-option")
+ .short("o")
+ .takes_value(true)
+ .help("Some help and text"))
+ .arg(Arg::with_name("b")
+ .long("other-option")
+ .short("O")
+ .takes_value(true)
+ .display_order(1)
+
+
+
+ .help("I should be first!"))
+ .get_matches_from(vec![
+ "prog", "--help"
+ ]);
+
The above example displays the following help message
+
cust-ord
+
+USAGE:
+ cust-ord [FLAGS] [OPTIONS]
+
+FLAGS:
+ -h, --help Prints help information
+ -V, --version Prints version information
+
+OPTIONS:
+ -O, --other-option <b> I should be first!
+ -o, --long-option <a> Some help and text
+
+
pub fn raw(self, raw: bool) -> Self[src]
Indicates that all parameters passed after this should not be parsed
+individually, but rather passed in their entirety. It is worth noting
+that setting this requires all values to come after a -- to indicate they
+should all be captured. For example:
+
--foo something -- -v -v -v -b -b -b --baz -q -u -x
+
+
Will result in everything after -- to be considered one raw argument. This behavior
+may not be exactly what you are expecting and using AppSettings::TrailingVarArg
+may be more appropriate.
+
NOTE: Implicitly sets Arg::multiple(true), Arg::allow_hyphen_values(true), and
+Arg::last(true) when set to true
+
Hides an argument from short help message output.
+
NOTE: This does not hide the argument from usage strings on error
+
NOTE: Setting this option will cause next-line-help output style to be used
+when long help (--help) is called.
+
+
+Arg::with_name("debug")
+ .hidden_short_help(true)
+
Setting hidden_short_help(true) will hide the argument when displaying short help text
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .long("config")
+ .hidden_short_help(true)
+ .help("Some help text describing the --config arg"))
+ .get_matches_from(vec![
+ "prog", "-h"
+ ]);
+
The above example displays
+
helptest
+
+USAGE:
+ helptest [FLAGS]
+
+FLAGS:
+-h, --help Prints help information
+-V, --version Prints version information
+
+
However, when --help is called
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .long("config")
+ .hidden_short_help(true)
+ .help("Some help text describing the --config arg"))
+ .get_matches_from(vec![
+ "prog", "--help"
+ ]);
+
Then the following would be displayed
+
helptest
+
+USAGE:
+ helptest [FLAGS]
+
+FLAGS:
+ --config Some help text describing the --config arg
+-h, --help Prints help information
+-V, --version Prints version information
+
+
Hides an argument from long help message output.
+
NOTE: This does not hide the argument from usage strings on error
+
NOTE: Setting this option will cause next-line-help output style to be used
+when long help (--help) is called.
+
+
+Arg::with_name("debug")
+ .hidden_long_help(true)
+
Setting hidden_long_help(true) will hide the argument when displaying long help text
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .long("config")
+ .hidden_long_help(true)
+ .help("Some help text describing the --config arg"))
+ .get_matches_from(vec![
+ "prog", "--help"
+ ]);
+
The above example displays
+
helptest
+
+USAGE:
+ helptest [FLAGS]
+
+FLAGS:
+-h, --help Prints help information
+-V, --version Prints version information
+
+
However, when -h is called
+
+
+let m = App::new("prog")
+ .arg(Arg::with_name("cfg")
+ .long("config")
+ .hidden_long_help(true)
+ .help("Some help text describing the --config arg"))
+ .get_matches_from(vec![
+ "prog", "-h"
+ ]);
+
Then the following would be displayed
+
helptest
+
+USAGE:
+ helptest [FLAGS]
+
+FLAGS:
+ --config Some help text describing the --config arg
+-h, --help Prints help information
+-V, --version Prints version information
+
+
Checks if one of the ArgSettings settings is set for the argument.
+
Sets one of the ArgSettings settings for the argument.
+
Unsets one of the ArgSettings settings for the argument.
+
