Allows custom ordering of subcommands within the help message. Subcommands with a lower
value will be displayed first in the help message. This is helpful when one would like to
emphasise frequently used subcommands, or prioritize those towards the top of the list.
Duplicate values **are** allowed. Subcommands with duplicate display orders will be
displayed in alphabetical order.
**NOTE:** The default is 999 for all subcommands.
```rust
use clap::{App, SubCommand};
let m = App::new("cust-ord")
.subcommand(SubCommand::with_name("alpha") // typically subcommands are grouped
// alphabetically by name. Subcommands
// without a display_order have a value of
// 999 and are displayed alphabetically with
// all other 999 subcommands
.about("Some help and text"))
.subcommand(SubCommand::with_name("beta")
.display_order(1) // In order to force this subcommand to appear *first*
// all we have to do is give it a value lower than 999.
// Any other subcommands with a value of 1 will be displayed
// alphabetically with this one...then 2 values, then 3, etc.
.about("I should be first!"))
.get_matches_from(vec![
"cust-ord", "--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
SUBCOMMANDS:
beta I should be first!
alpha Some help and text
```
Closes#442
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.
```rust
use clap::{App, Arg};
let m = App::new("cust-ord")
.arg(Arg::with_name("a") // typically args are grouped by alphabetically by name
// Args without a display_order have a value of 999 and are
// displayed alphabetically with all other 999 args
.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) // Let's force this arg to appear *first*
// all we have to do is give it a value lower than 999
// any other args with a value of 1 would be displayed
// alphabetically with other 1 args. Then 2, then 3, etc.
.help("I should be first!"))
.get_matches_from(vec![
"cust-ord", "--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
```
OsStr recently gained unstable inherent methods with the same name. This rename
makes sure we don't call the inherent methods but the methods provided by this
extension trait.
Adds a setting for both `AppSettings` and an `Arg` method which allows
placing the help text for a particular argument (or all arguments via
the `AppSettings`) on the line after the argument itself and indented
once.
This is useful for when a single argument may have a very long
invocation flag, or many value names which throws off the alignment of
al other arguments. On a small terminal this can be terrible. Placing
the text on the line below the argument solves this issue. This is also
how many of the GNU utilities display their help strings for individual
arguments.
The final caes where this can be hepful is if the argument has a very
long or detailed and complex help string that will span multiple lines.
It can be visually more appealing and easier to read when those lines
don't wrap as frequently since there is more space on the next line.
Closes#427
Issue 420
When value names are use, they will be displayed in help and error
messages instead of the argument name. For example, an argument named
`arg` but with the value name `FILE` will be displayed as `[FILE]`.
Likewise multiple value names will be displayed properly such as `[FILE1] [FILE2]`
Closes#420
When value names are use, they will be displayed in help and error
messages instead of the argument name. For example, an argument named
`arg` but with the value name `FILE` will be displayed as `[FILE]`.
Likewise multiple value names will be displayed properly such as `[FILE1] [FILE2]`
Closes#420
Grammatical pedantry
I originally set out to only change liftimes to lifetimes, but I got a little carried away.
Fear not, I decided to stop myself partially through and actually start using your library!
i.e. assume, option -O set to multiple, and number_of_values(1)
set. And assume a *required* positional argument is also set.
-O some -O other pos
Would fail with pos arg not supplied.
Relates to #415
fix: Stop lonely hyphens from causing panic
The method `starts_with` as implemented for the `OsStrExt2` trait on
`OsStr` assumed that the needle given is shorter than the haystack. When
this is not the case, the method panics due to an attempted
out-of-bounds access on the byte representation of `self`. Problematic
if, say, an end-user gives us `"-"` and the library tries to see if that
starts with `"--"`.
Fortunately, slices already implement a `starts_with` method, and we can
delegate to it.
This *does* create a semantics change: if both `self` and the needle
have length 0, this implementation will return `true`, but the old
implementation would return `false`. Based on the test suite still
passing, acknowledging the vacuous truth doesn't seem to cause any
problems.
Fixes#410
