Commit graph

263 commits

Author SHA1 Message Date
Barret Rennie
0ceba231c6 feat(Settings): Add unset_setting and unset_settings fns to App (#598)
Closes #590.
2016-07-24 00:08:24 -04:00
Roman A. Taycher
3398b64b5a Merge branch 'master' into authors 2016-07-23 16:39:29 -07:00
Roman A. Taycher
05edc4338e removed unstable gate from crate_authors 2016-07-23 15:56:42 -07:00
Kevin K
1fc3b55bd6 fix: fixes bug where only first arg in list of required_unless_one is recognized
Closes #575
2016-07-23 17:21:47 -04:00
Kevin K
fc72cdf591 fix(Settings): fixes typo subcommandsrequired->subcommandrequired
Closes #593
2016-07-23 16:25:17 -04:00
David Szotten
9f62cf7378 feat(Completions): adds the ability to generate completions to io::Write object 2016-07-14 09:38:13 +01:00
Mike Boutin
b3cdc3b5c2 Fix get_matches typo 2016-07-04 10:19:36 -04:00
Kevin K
cecfe981ea fix(Completions): fixes bug where --help and --version short weren't added to the completion list
Closes #563
2016-07-03 10:55:40 -04:00
Sébastien Watteau
722f2607be docs(Completions): fixes the formatting of the Cargo.toml excerpt in the completions example 2016-07-02 09:31:09 +02:00
Kevin K
57484b2dae imp(Completions): allows multiple completions to be built by namespacing with bin name
Completions are now written `<bin>_<shell>.<ext>` vice the old, `<shell>.<ext>`
2016-07-01 22:15:23 -04:00
Kevin K
96c24c9a8f fix(AllowLeadingHyphen): fixes an issue where isn't ignored like it should be with this setting
Prior to this fix, using `AppSettings::AllowLeadingHyphen` wouldn't properly ignore `--`

Closes #558
2016-07-01 13:47:41 -04:00
Kevin K
9b359bf062 docs(Completions): fixes some errors in the completion docs 2016-07-01 12:26:20 -04:00
Kevin K
7daee9ded0 chore: increase version 2016-07-01 00:34:08 -04:00
Kevin K
c6c519e40e docs(Completions): adds documentation for completion scripts 2016-07-01 00:18:52 -04:00
Kevin K
e75b6c7b75 feat(Completions): one can now generate a bash completions script at compile time
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
2016-06-30 23:50:49 -04:00
Kevin K
ceddee9157 refactor(term.rs): moved term.rs into it's own crate so others can pull in just that portion
The functionality can now be found in https://crates.io/crates/term_size

Closes #549
2016-06-29 23:19:08 -04:00
Kevin K
920b5595ed feat(Arg): adds new setting Arg::require_delimiter which requires val delimiter to parse multiple values
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"]);
```
2016-06-29 22:57:28 -04:00
Kevin K
cdc500bdde fix(Options): values using delimiters no longer parse additional values after a trailing space
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
2016-06-29 13:21:30 -04:00
Kevin K
290f61d071 fix(Options): using options with an = no longer parse args after the trailing space as values
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
2016-06-29 13:16:31 -04:00
Homu
18237f403a Auto merge of #542 - brianp:issue-426, r=kbknapp
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
2016-06-25 03:26:48 +09:00
Brian Pearce
902e182f7a 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
2016-06-24 08:57:11 -07:00
Roger Andersen
43b3d40b8c docs: fix typos 2016-06-24 12:23:08 +02:00
Kevin K
e84cc01836 fix(App): using App::print_help now prints the same as would have been printed by --help or the like
Using `App::print_help` before wasn't building the default `--help` and `--version` flags properly.
This has now been fixed.

Closes #536
2016-06-24 00:32:53 -04:00
Kevin K
9b2e45b170 imp(Usage Strings): [FLAGS] and [ARGS] are no longer blindly added to usage strings
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
2016-06-24 00:15:48 -04:00
Kevin K
e3d2893f37 fix(Help): prevents invoking <cmd> help help and displaying incorrect help message
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
2016-06-23 23:45:32 -04:00
Kevin K
08ad1cff4f fix(Help): subcommand help messages requested via <cmd> help <sub> now correctly match <cmd> <sub> --help
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
2016-06-23 21:47:30 -04:00
Kevin K
33689acc68 feat(Groups): one can now specify groups which require AT LEAST one of the args
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
2016-06-23 12:40:08 -04:00
Kevin K
1f4da7676e fix(Help): App::before_help and App::after_help now correctly wrap
`before_help` and `after_help` weren't wrapping at the either the specified terminal width, or auto
determined one. That is now fixed.

Closes #516
2016-06-13 22:03:27 -04:00
Kevin K
1761dc0d27 feat(Help): allows wrapping at specified term width (Even on Windows!)
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
2016-06-13 21:51:58 -04:00
Kevin K
e468faf3f0 fix(YAML): adds missing YAML methods for App and Arg
Closes #528
2016-06-12 22:10:25 -04:00
Kevin K
ca511de71f imp(Aliases): improves readability of asliases in help messages
Aliases are now displayed after the help text inside a `[aliases: als1, als2, als3]` style box.

Closes #526
Closes #529
2016-06-12 21:50:31 -04:00
Kevin K
7b10e7f893 feat(Subcommands): adds support for visible aliases
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
2016-06-09 21:55:35 -04:00
Kevin K
5354d14b51 fix(Subcommands): subcommands with aliases now display help of the aliased subcommand
Imagine subcommand `foo` had alias `bar`, running `myprog help bar` now correctly displays the help
for `foo`

Closes #521
2016-06-09 20:39:53 -04:00
Kevin K
1bfae42eaf refactor: clippy run 2016-06-08 00:10:56 -04:00
Kevin K
fc3e0f5afd feat(Settings): adds new setting to stop delimiting values with -- or TrailingVarArg
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
2016-06-07 23:49:05 -04:00
Kevin K
7db45f78d8 chore: removes extra debug statements 2016-06-07 23:49:05 -04:00
Kevin K
706a7c11b0 fix(Settings): fixes bug where new color settings couldn't be converted from strs 2016-06-07 23:49:05 -04:00
Kevin K
ec86f2dada imp(Usage Strings): improves the default usage string when only a single positional arg is present
Instead of blindly printing `[ARGS]` when only a single positional arg is present, it will now
print `[NAME]` (or `[NAME]...` for multiple values allowed)

Closes #518
2016-06-04 11:55:47 -04:00
Kevin K
e23418351a feat(Settings): one can now set an AppSetting which is propogated down through child subcommands
Closes #519
2016-06-04 11:55:47 -04:00
Kevin K
cd44080650 fix: fixes bug where args are printed out of order with templates 2016-06-04 11:55:47 -04:00
Kevin K
8f630c6a07 fix: fixes bug where one can't override version or help flags
Closes #514
2016-06-04 11:55:47 -04:00
Kevin K
330e5edf04 fix: fixes issue where before_help wasn't printed 2016-06-04 11:55:47 -04:00
Kevin K
054f8cb433 imp: removes extra newline from help output 2016-06-04 11:55:47 -04:00
Kevin K
c5b24c0eb0 tests: removes extra newline from version output tests 2016-06-04 11:28:24 -04:00
Kevin K
a7401dc6a1 imp: allows printing version to any io::Write object 2016-06-04 11:28:24 -04:00
Kevin K
cda27469cd imp: removes extra newline when printing version 2016-06-04 11:28:24 -04:00
Kevin K
65c2350aa3 feat: colors dont get sent to pipes by default
Color are now only used when outputting to a termainal/TTY. There are three new settings as well
which can be used to control color output, they are:

 * `AppSettings::ColorAuto`: The default, and will only output color when outputting to a terminal or TTY
 * `AppSettings::ColorAlways`: Outputs color no matter where the output is going
 * `AppSettings::ColorNever`: Never colors output

This now allows one to use things like command line options, or environmental variables to turn
colored output on/off.

Closes #512
2016-06-04 11:28:03 -04:00
Kevin K
3312893dda docs: inter-links all types and pages
All doc pages should now be inter-linked between other doc pages and
Rust documentation.

Closes #505
2016-05-15 14:23:37 -04:00
Hendrik Sollich
ac42f6cf0d Fix: SubCommand::aliases lifetime errors 2016-05-11 21:08:25 +02:00
Hendrik Sollich
6ba910e89b test: adds failing doc test 2016-05-11 20:16:56 +02:00
Kevin K
41a482cf5d imp(SubCommand Aliases): adds feature to yaml configs too 2016-05-10 17:15:06 -04:00
Kevin K
66b4dea65c feat(SubCommands): adds support for subcommand aliases
Allows adding a subcommand alias, which function as "hidden" subcommands that automatically
dispatch as if this subcommand was used. This is more efficient, and easier than creating
multiple hidden subcommands as one only needs to check for the existing of this command,
and not all vairants.

Example:

```
let m = App::new("myprog")
            .subcommand(SubCommand::with_name("test")
                .alias("do-stuff"))
            .get_matches_from(vec!["myprog", "do-stuff"]);
assert_eq!(m.subcommand_name(), Some("test"));
```

Example using multiple aliases:

```
let m = App::new("myprog")
            .subcommand(SubCommand::with_name("test")
                .aliases(&["do-stuff", "do-tests", "tests"]))
            .get_matches_from(vec!["myprog", "do-tests"]);
assert_eq!(m.subcommand_name(), Some("test"));
```

Closes #469
2016-05-10 15:21:19 -04:00
Kevin K
3ca0947c16 fix(Usage Strings): now properly dedups args that are also in groups
For example, if an arg is part of a required group, it will only appear
in the group usage string, and not in both the group as well as the arg
by itself.

Imagine a group containing two args, `arg1` and `--arg2`

OLD:
    `myprog <arg1> <arg1|--arg2>`

NEW:
    `myprog <arg1|--arg2>`

Closes #498
2016-05-09 19:14:11 -04:00
Kevin K
f574fb8a7c fix(Usage Strings): removes duplicate groups from usage strings 2016-05-09 19:14:11 -04:00
Kevin K
852e58156c tests: removes old python tests and replaces with rust tests
Closes #166
2016-05-09 19:14:11 -04:00
Kevin K
fef11154fb imp(Groups): formats positional args in groups in a better way 2016-05-08 21:33:27 -04:00
Kevin K
2efd81ebbc chore: clippy update and run 2016-05-06 17:59:52 -04:00
Kevin K
ffde90f2ba style: rustfmt run 2016-05-06 17:52:23 -04:00
Kevin K
5b7fe8e416 imp(Help): default help subcommand string has been shortened
Closes #494
2016-05-05 21:49:51 -04:00
Kevin K
5b0120088a fix(Required Args): fixes issue where missing required args are sometimes duplicatd in error messages
Closes #492
2016-05-03 16:31:55 -04:00
Kevin K
d8e4dbc961 feat(Help): adds support for displaying info before help message
Can now use the `App::before_help` method to add additional information
that will be displayed prior to the help message. Common uses are
copyright, or license information.
2016-05-03 16:31:55 -04:00
Kevin K
6987f37e71 feat(Required): adds allowing args that are required unless certain args are present
Adds three new methods of `Arg` which allow for specifying three new
types of rules.

* `Arg::required_unless`

Allows saying a particular arg is only required if a specific other arg
*isn't* present.

* `Arg::required_unless_all`

Allows saying a particular arg is only required so long as *all* the
following args aren't present

* `Arg::required_unless_one`

Allows saying a particular arg is required unless at least one of the
following args is present.
2016-05-03 16:31:54 -04:00
Kevin K
4fe133d9ce chore: removes unused imports 2016-05-02 18:04:10 -04:00
Kevin K
770397bcb2 feat(HELP): implements optional colored help messages
To enable, ensure `clap` is compiled with `color` cargo feature.

Then in code use `AppSettings::ColoredHelp`

Closes #483
2016-04-18 00:05:43 -07:00
Homu
fdbd12e830 Auto merge of #478 - hgrecco:template, r=kbknapp
A new Help Engine with templating capabilities

This set of commits brings a new Help System to CLAP.

Major changes are:
- The help format is (almost) completely defined in `help.rs` instead of being scattered across multiple files.
- The HELP object contains a writer and its methods accept AnyArgs, not the other way around.
- A template option allows the user to change completely the organization of the autogenerated help.
2016-04-18 08:12:39 +09:00
Hernan Grecco
627ae38dc0 refactor(HELP): Removed code for old help system and tests that helped with the transitions 2016-04-13 07:21:21 -03:00
Hernan Grecco
8d23806bd6 fix(HELP): Adjust Help to semantic changes introduced in 6933b84 2016-04-13 07:06:23 -03:00
Hernan Grecco
81e121edd6 feat(HELP): Add a Templated Help system.
The strategy is to copy the template from the the reader to wrapped stream
until a tag is found. Depending on its value, the appropriate content is copied
to the wrapped stream.
The copy from template is then resumed, repeating this sequence until reading
the complete template.

Tags arg given inside curly brackets:
Valid tags are:
    * `{bin}`         - Binary name.
    * `{version}`     - Version number.
    * `{author}`      - Author information.
    * `{usage}`       - Automatically generated or given usage string.
    * `{all-args}`    - Help for all arguments (options, flags, positionals arguments,
                        and subcommands) including titles.
    * `{unified}`     - Unified help for options and flags.
    * `{flags}`       - Help for flags.
    * `{options}`     - Help for options.
    * `{positionals}` - Help for positionals arguments.
    * `{subcommands}` - Help for subcommands.
    * `{after-help}`  - Help for flags.
2016-04-13 07:06:23 -03:00
Hernan Grecco
04b5b074d1 refactor(HELP): A new Help Engine
The largest organizational change is that methods used to generate the help are
implemented by the Help object and not the App, FlagBuilder, Parser, etc.

The new code is based heavily on the old one with a few minor modifications
aimed to reduce code duplication and coupling between the Help and the rest
of the code.

The new code turn things around: instead of having a HelpWriter that holds an
AnyArg object and a method that is called with a writer as argument,
there is a Help Object that holds a writer and a method that is called with a
writer as an argument.

There are still things to do such as moving `create_usage` outside the Parser.

The peformance has been affected, probably by the use of Trait Objects. This
was done as a way to reduce code duplication (i.e. in the unified help code).
This performance hit should not affect the usability as generating and printing
the help is dominated by user interaction and IO.

The old code to generate the help is still functional and is the active one.
The new code has been tested against the old one by generating help strings
for most of the examples in the repo.
2016-04-13 07:06:23 -03:00
Hernan Grecco
a91d378ba0 imp(parser.rs): Provide a way to create a usage string without the USAGE: title 2016-04-13 07:06:22 -03:00
Hernan Grecco
65b3f66753 imp(srs/args): Added longest_filter to AnyArg trait
This function allows providing an extra filter to remove elements when finding
the longest element.
2016-04-13 07:06:22 -03:00
Hernan Grecco
d51945f8b8 imp(parser.rs): Make Parser's create_usage public allowing to have function outside the parser to generate the help 2016-04-13 07:06:22 -03:00
Hernan Grecco
9b23e7ee40 imp(parser.rs): Expose Parser's flags, opts and positionals argument as iterators
Writing the help requires read only access to Parser's flags, opts
and positionals. This commit provides 3 functions returning iterators
over those collections (`iter_*`) allowing to have function outside
the parser to generate the help.
2016-04-13 07:06:22 -03:00
Roman A. Taycher
38fb59abf4 feat(Authors Macro): adds a crate_authors macro
Adds a crate_authors! macro that fetches
crate authors from a (recently added)
cargo enviromental variable populated
from the Cargo file. Like the
crate_version macro.

Closes #447
2016-04-11 16:17:44 -07:00
panicbit
3019a685ee Fix off-by-one-error in ArgGroup printing 2016-04-10 02:46:51 +02:00
Kevin K
885d166f04 fix(Empty Values): fixes bug where empty values weren't stored
Passing empty values, such as `--feature ""` now stores the empty string
correctly as a value (assuming empty values are allowed as per the arg
configuration)

Closes #470
2016-03-29 22:25:13 -04:00
Kevin K
205b07bf2e fix(Help Subcommand): fixes issue where help and version flags weren't properly displayed
Closes #466
2016-03-28 11:26:56 -04:00
Kevin K
6933b8491c fix(Usage Strings): fixes small bug where -- would appear needlessly in usage strings
Closes #461
2016-03-27 14:22:51 -04:00
Kevin K
144e7e29d6 chore: clippy run 2016-03-22 21:16:53 -04:00
Kevin K
813d75d06f feat(Help Message): wraps and aligns the help message of subcommands
Subcommand's help strings are now automatically wrapped and aligned just
like other arguments.

Closes #452
2016-03-16 10:17:00 -04:00
Kevin K
2c12757bbd feat(Help Subcommand): adds support passing additional subcommands to help subcommand
The `help` subcommand can now accept other subcommands as arguments to
display their help message. This is similar to how many other CLIs
already perform. For example:

```
$ myprog help mysubcmd
```

Would print the help message for `mysubcmd`. But even more, the `help`
subcommand accepts nested subcommands as well, i.e. a grandchild
subcommand such as

```
$ myprog help child grandchild
```

Would print the help message of `grandchild` where `grandchild` is a
subcommand of `child` and `child` is a subcommand of `myprog`.

Closes #416
2016-03-14 22:41:47 -04:00
Kevin K
675c39f8ba tests: moves app settings tests to the proper place 2016-03-13 22:07:28 -04:00
Kevin K
e428bb6d84 tests: moves some \t tabs to four spaces for consistency 2016-03-13 22:07:28 -04:00
Kevin K
e36af02666 feat(Help Message): can auto wrap and aligning help text to term width
By default `clap` now automatically wraps and aligns help strings to the
term width. i.e.

```
    -o, --option <opt>    some really long help
text that should be auto aligned but isn't righ
t now
```

Now looks like this:

```
    -o, --option <opt>    some really long help
                          text that should be
                          auto aligned but isn't
                          right now
```

The wrapping also respects words, and wraps at spaces so as to not cut
words in the middle.

This requires the `libc` dep which is enabled (by default) with the
`wrap_help` cargo feature flag.

Closes #428
2016-03-13 22:07:28 -04:00
Kevin K
c5c58c86b9 fix(From Usage): fixes a bug where adding empty lines werent ignored 2016-03-10 16:36:23 -05:00
Kevin K
22000a08f7 chore: changes some assertions to debug assertions 2016-03-10 16:33:39 -05:00
Kevin K
ad86e43334 feat(Settings): adds support for automatically deriving custom display order of args
Args and subcommands can now have their display order automatically
derived by using the setting `AppSettings::DeriveDisplayOrder` which
will display the args and subcommands in the order that they were
declared in, instead of alphabetical order which is the default.

Closes #444
2016-03-10 16:32:02 -05:00
Kevin K
927d1da1c7 chore: ignore failing clippy build 2016-03-09 19:54:42 -05:00
Kevin K
06c729f52f chore: fixes failing nightly lint 2016-03-09 18:40:31 -05:00
Kevin K
e41a2f1bea test: fixes failing doc tests 2016-03-09 20:14:35 -05:00
Kevin K
7d2a2ed413 feat(Subcommands): adds support for custom ordering in help messages
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
2016-03-09 19:43:53 -05:00
Kevin K
9803b51e79 feat(Opts and Flags): adds support for custom ordering in help messages
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
```
2016-03-09 19:41:43 -05:00
Alexander Bulaev
150784ae20 Update VecMap to 0.6 2016-03-08 19:50:20 -05:00
Kevin K
deace34ad2 chore: clippy run 2016-03-08 10:39:43 -05:00
Jorge Aparicio
56d14cbbb6 fix clippy warnings 2016-02-22 18:36:57 -05:00
Jorge Aparicio
9a94ad8ad6 sprinkle #[allow(missing_debug_implementations)] 2016-02-21 11:44:45 -05:00
Jorge Aparicio
d752c17029 rename OsStrExt2::{is_empty,len} to {is_empty_,len_}
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.
2016-02-21 11:18:26 -05:00
Kevin K
3c8db0e9be docs(AppSettings): clarifies that AppSettings do not propagate
Closes #429
2016-02-19 01:47:37 -05:00
Kevin K
e2ec5f09eb chore: clippy run 2016-02-19 01:47:37 -05:00
Kevin K
066df7486e imp(Help): adds setting for next line help by arg
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
2016-02-17 23:47:27 -05:00