Prior to this commit if one wished to use source formatting and ignore
term width they could do `App::set_term_width(usize::MAX)` now one can
also use `App::set_term_width(0)` which does the same thing.
Closes#625
For example, doing `myprog help subcmd1 subcmd2` would have incorrectly
produced the usage string, `myprog subcmd2 [options]` but now correctly
prints `myprog subcmd1 subcmd2 [options]`
Closes#618
The following completion would happen (using example 17_yaml.rs):
```
$ prog <tab>
help subcmd
```
```
$ prog -<tab><tab>
--help -h (Prints help information)
--max-vals (you can only supply a max of 3 values for me!)
--min-vals (you must supply at least two values to satisfy me)
--mode (shows an option with specific values)
--mult-vals (demos an option which has two named values)
--option -o (example option argument from yaml)
--version -V (Prints version information)
-F (demo flag argument)
```
```
$ prog --<tab><tab>
--help -h (Prints help information)
--max-vals (you can only supply a max of 3 values for me!)
--min-vals (you must supply at least two values to satisfy me)
--mode (shows an option with specific values)
--mult-vals (demos an option which has two named values)
--option -o (example option argument from yaml)
--version -V (Prints version information)
```
```
$ prog --mode <tab>
emacs (shows an option with specific values) vi (shows an option with specific values)
```
```
$ prog subcmd -<tab>
--help -h (Prints help information) -B (example subcommand option)
--version -V (Prints version information)
```
```
$ prog subcmd --<tab>
--help (Prints help information) --version (Prints version information)
```
Close#578
By using a build.rs "build script" one can now generate a bash completions script which allows tab
completions for the entire program, to include, subcommands, options, everything!
See the documentation for full examples and details.
Closes#376
Using this setting requires a value delimiter be present in order to parse multiple values.
Otherwise it is assumed no values follow, and moves on to the next arg with a clean slate.
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.
```rust
let delims = App::new("reqdelims")
.arg(Arg::with_name("opt")
.short("o")
.takes_value(true)
.multiple(true)
.require_delimiter(true))
// Simulate "$ reqdelims -o val1,val2,val3"
.get_matches_from(vec![
"reqdelims", "-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.
```rust
let res = App::new("reqdelims")
.arg(Arg::with_name("opt")
.short("o")
.takes_value(true)
.multiple(true)
.require_delimiter(true))
// Simulate "$ reqdelims -o val1 val2 val3"
.get_matches_from_safe(vec![
"reqdelims", "-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.
```rust
let delims = App::new("reqdelims")
.arg(Arg::with_name("opt")
.short("o")
.takes_value(true)
.multiple(true))
// Simulate "$ reqdelims -o val1 val2 val3"
.get_matches_from(vec![
"reqdelims", "-o", "val1", "val2", "val3",
]);
assert!(delims.is_present("opt"));
assert_eq!(delims.values_of("opt").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]);
```
Imagine two args, an option `-o` which accepts mutliple values, and a positional arg `<file>`.
Prior to this change the following (incorrect) parses would have happened:
```
$ prog -o 1,2 some.txt
o = 1, 2, file
file =
```
Only when delimters are used, spaces stop parsing values for the option. The follow are now correct
```
$ prog -o 1,2 some.txt
o = 1, 2
file = some.txt
$ prog some.txt -o 1 2
o = 1, 2
file = some.txt
```
This still has the bi-product of:
```
$ prog -o 1 2 some.txt
o = 1, 2, some.txt
file =
```
This is simply a CLI design and documentation issue (i.e. don't allow options with unlimited
multiple values with positionaln args, or clearly document that positional args go first). This
will also be helped by the upcoming `Arg::require_delimiter`
Relates to #546
Imagine two args, an options `-o` and a positionanl arg `<file>` where the option allows multiple
values. Prior to this change the following (incorrect) parses were occurring:
```
$ prog -o=1 some.txt
o = 1, file
file =
```
This change stops parsing values at the space, only if the `=` was used.
```
$ prog -o=1 some.txt
o = 1
file = some.txt
```
Multiple values are still supported via value delimiters
```
$ prog -o=1,2 some.txt
o = 1, 2
file = some.txt
```
Relates to #546
imp(ArgGroup): Add multiple ArgGroups per Arg
Add the function `Arg.groups` that can take a `Vec<&'a str>` to add the `Arg` to multiple `ArgGroup`'s at once.
ex:
```rust
Arg::with_name("arg")
.groups(&["grp1", "grp2"])
```
Closes#426
Add the function `Arg.groups` that can take a `Vec<&'a str>` to add the `Arg` to multiple `ArgGroup`'s at once.
ex:
```rust
Arg::with_name("arg")
.groups(&["grp1", "grp2"])
```
Closes#426
In usage strings `[FLAGS]` and `[ARGS]` tags are now only added if there are relevant flags and
args to collapse. I.e. those that are
* Not required (`[ARGS]` only)
* Not belonging to some required group
* Excludes --help and --version (`[FLAGS]` only)
Closes#537
Previously, if one ran `<cmd> help help` an additional `help` subcommand was created and a help
message displayed for it. We *could* have just thrown an error `<cmd> help help` but I worry that
the message would be confusing, because something like, "Invalid Subcommand" isn't 100% correct as
the form `<cmd> help <subcmd>` is allowed, and there *is* a `help` subcmd.
This fix correct dispatches `<cmd> help help` to the `<cmd>` help message.
Closes#538
Prior to this fix, runnning `prog help subcmd` would produce:
```
subcmd
USGAE:
[...]
```
Notice lack of `prog-subcmd`. Whereas running `prog subcmd --help` produced:
```
prog-subcmd
USGAE:
[...]
```
These two forms now match the correct one (latter).
Closes#539
Unlike the previous ArgGroups, which made all args in the group mutually exclusive, one can now use
`ArgGroup::multiple(true)` which allows using more than one arg in the group (i.e. they're not all
mutually exclusive). When combined with `ArgGroup::required(true)` this effectively says, "At least
one of the args must be used, and using morethan one is also OK."
Closes#533
Now using `App::set_term_width` will set a wrapping width regardless of terminal size. This can
also be used when no terminal size can be determined (Such as on Windows). All help is now wrapped
at 120 if no terminal size has been specified, or can be determined.
Closes#451
This commit adds support for visible aliases, which function exactly like aliases except that they
also appear in the help message, using the help string of the aliased subcommand.
i.e.
```rust
App::new("myprog")
.subcommand(SubCommand::with_name("test")
.about("does testy things")
.alias("invisible")
.visible_alias("visible"));
```
When run with `myprog --help`, the output is:
```
myprog
USAGE:
myprog [FLAGS] [SUBCOMMAND]
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
SUBCOMMANDS:
help Prints this message or the help of the given subcommand(s)
test|visible does testy things
```
Closes#522
One can now use `AppSettings::DontDelimitTrailingValues` to stop clap's default behavior of
delimiting values, even when `--` or `TrailingVarArg` is used. This is useful when passing other
flags and commands through to another program.
Closes#511
