Makes the validator functions more flexible by changing the return
type from Result<(), String> to Result<O, E> where O is anything
and E is anything convertible to a String.
This allows, for example, using the same function for validating
and parsing your argument.
Breaking change (albeit tiny) due to function signature change.
Args can now be added to custom help sections. This breaks up the builder pattern a little by adding help section declarations inline, but it's the most intuitive method and doesn't require strange nesting that feels awkward.
```rust
app::new("foo")
.arg(Arg::with_name("arg1")) // under normal headers
.help_heading("SPECIAL")
.arg(Arg::with_name("arg2")) // under SPECIAL: heading
```
Closes#805
Add logic to filter based on hidden long/short.
There is still an issue with the logic in parser.rs use_long_help. This
causes invalid evaluation of whether to show/hide based on long or short help
Complete check for use_long_help, add tests
Once can now mutate an Arg instance after it's already been added to an App struct.
This is helpful when you wish to add all the args in an non-verbose way, such as
via the usage strings, but wish for a handful to have settings which arne't posible
in the usage string definitions.
Adds the abiltiy to query the matches struct for the indices of values or flags. The index
is similar to that of an argv index, but not exactly a 1:1.
For flags (i.e. those arguments which don't have an associated value), indices refer
to occurrence of the switch, such as `-f`, or `--flag`. However, for options the indices
refer to the *values* `-o val` would therefore not represent two distinct indices, only the
index for `val` would be recorded. This is by design.
Besides the flag/option descrepancy, the primary difference between an argv index and clap
index, is that clap continues counting once all arguments have properly seperated, whereas
an argv index does not.
The examples should clear this up.
*NOTE:* If an argument is allowed multiple times, this method will only give the *first*
index.
The argv indices are listed in the comments below. See how they correspond to the clap
indices. Note that if it's not listed in a clap index, this is becuase it's not saved in
in an `ArgMatches` struct for querying.
```rust
let m = App::new("myapp")
.arg(Arg::with_name("flag")
.short("f"))
.arg(Arg::with_name("option")
.short("o")
.takes_value(true))
.get_matches_from(vec!["myapp", "-f", "-o", "val"]);
// ARGV idices: ^0 ^1 ^2 ^3
// clap idices: ^1 ^3
assert_eq!(m.index_of("flag"), Some(1));
assert_eq!(m.index_of("option"), Some(3));
```
Now notice, if we use one of the other styles of options:
```rust
let m = App::new("myapp")
.arg(Arg::with_name("flag")
.short("f"))
.arg(Arg::with_name("option")
.short("o")
.takes_value(true))
.get_matches_from(vec!["myapp", "-f", "-o=val"]);
// ARGV idices: ^0 ^1 ^2
// clap idices: ^1 ^3
assert_eq!(m.index_of("flag"), Some(1));
assert_eq!(m.index_of("option"), Some(3));
```
Things become much more complicated, or clear if we look at a more complex combination of
flags. Let's also throw in the final option style for good measure.
```rust
let m = App::new("myapp")
.arg(Arg::with_name("flag")
.short("f"))
.arg(Arg::with_name("flag2")
.short("F"))
.arg(Arg::with_name("flag3")
.short("z"))
.arg(Arg::with_name("option")
.short("o")
.takes_value(true))
.get_matches_from(vec!["myapp", "-fzF", "-oval"]);
// ARGV idices: ^0 ^1 ^2
// clap idices: ^1,2,3 ^5
//
// clap sees the above as 'myapp -f -z -F -o val'
// ^0 ^1 ^2 ^3 ^4 ^5
assert_eq!(m.index_of("flag"), Some(1));
assert_eq!(m.index_of("flag2"), Some(3));
assert_eq!(m.index_of("flag3"), Some(2));
assert_eq!(m.index_of("option"), Some(5));
```
One final combination of flags/options to see how they combine:
```rust
let m = App::new("myapp")
.arg(Arg::with_name("flag")
.short("f"))
.arg(Arg::with_name("flag2")
.short("F"))
.arg(Arg::with_name("flag3")
.short("z"))
.arg(Arg::with_name("option")
.short("o")
.takes_value(true)
.multiple(true))
.get_matches_from(vec!["myapp", "-fzFoval"]);
// ARGV idices: ^0 ^1
// clap idices: ^1,2,3^5
//
// clap sees the above as 'myapp -f -z -F -o val'
// ^0 ^1 ^2 ^3 ^4 ^5
assert_eq!(m.index_of("flag"), Some(1));
assert_eq!(m.index_of("flag2"), Some(3));
assert_eq!(m.index_of("flag3"), Some(2));
assert_eq!(m.index_of("option"), Some(5));
```
The last part to mention is when values are sent in multiple groups with a [delimiter].
```rust
let m = App::new("myapp")
.arg(Arg::with_name("option")
.short("o")
.takes_value(true)
.multiple(true))
.get_matches_from(vec!["myapp", "-o=val1,val2,val3"]);
// ARGV idices: ^0 ^1
// clap idices: ^2 ^3 ^4
//
// clap sees the above as 'myapp -o val1 val2 val3'
// ^0 ^1 ^2 ^3 ^4
assert_eq!(m.index_of("option"), Some(2));
```
For version 3, we want the args section to immediately follow
the usage section in the default help message.
One change that I am unhappy with is needing to make "write_arg"
in app/help.rs accept an extra param that makes it suppress the
extra line. This is to prevent an extra blank line from appearing
between args and options in the default help, and seems necessary,
but there might be a better way.
