This makes a very big difference for CLIs that parse a large number of
values (think ripgrep over a large directory).
This commit improved the ripgrep parsing of ~2,000 values, simulating
giving ripgrep a bunch of files. Parsing when from ~1,200,000 ns to
~400,000 ns! This was conducted a i7-5600U 2.6GHz
One can now define default values that contain invalid UTF-8.
The underlying implementation has also been changed to use OsStrs in order to avoid duplication
of code and provide the new APIs basically for free.
Closes#849
Not only does this remove some unsafe code from clap itself, `atty` does the
right thing on Windows too. This isn't relevant now since we don't currently
support colorized output on Windows, but will come in handy if/when we
implement that feature (#836).
* tests: adds tests for default values triggering conditional requirements
* fix: fixes a bug where default values should have triggered a conditional requirement but didnt
Closes#831
* tests: adds tests for missing conditional requirements in usage string of errors
* fix: fixes a bug where conditionally required args werent appearing in errors
* tests: adds tests for completion generators
* tests: adds tests for completions with binaries names that have underscores
* fix: fixes a bug where ZSH completions would panic if the binary name had an underscore in it
Closes#581
* fix: fixes bash completions for commands that have an underscore in the name
Closes#581
* chore: fix the category for crates.io
* docs(Macros): adds a warning about changing values in Cargo.toml not triggering a rebuild automatically
Closes#838
* fix(Completions): fixes a bug where global args weren't included in the generated completion scripts
Closes#841
* fix: fixes a println->debugln typo
* chore: increase version
* fix: fixes a critical bug where subcommand settings were being propogated too far
Closes#832
* imp: adds ArgGroup::multiple to the supported YAML fields for building ArgGroups from YAML
Closes#840
* chore: increase version
Before, inserting a newline did not move the prev_space index forward.
This meant that the next word was measured incorrectly since the
length was measured back to the word before the newly inserted
linebreak.
Fixes#828.
Before, wrapping the help text at, say, 80 characters really meant
that every line could be at most 79 characters wide.
Lines can now be up to and including avail_chars columns wide.
If needed, a desired margin or padding can be subtracted from the
avail_chars argument at a later point.
This fixes#827. The problem was that the check `grp.args.contains(&grp.args[i])` was a) trivially fulfilled (of course `grp.args[i]` is contained in `grp.args`) and b) causing an out-of-bounds error, since the indices were taken from `.required.len()`.
With this change the argument in the group will be removed from the list of required arguments, as intended.
When calling the executable without arguments one expects a help message. However, if even one argument has a default value, the validation step of the parser will always see at least one argument, and therefore report success. This effectively disables the settings.
Specifies that use of a valid [argument] negates [subcomands] being used after. By default
`clap` allows arguments between subcommands such as
`<cmd> [cmd_args] <cmd2> [cmd2_args] <cmd3> [cmd3_args]`. This setting disables that
functionality and says that arguments can only follow the *final* subcommand. For instance
using this setting makes only the following invocations possible:
* `<cmd> <cmd2> <cmd3> [cmd3_args]`
* `<cmd> <cmd2> [cmd2_args]`
* `<cmd> [cmd_args]`
Closes#793
An arg can now be conditionally required (i.e. it's only required if arg
A is used with a value of V).
For example:
```rust
let res = App::new("ri")
.arg(Arg::with_name("cfg")
.required_if("extra", "val")
.takes_value(true)
.long("config"))
.arg(Arg::with_name("extra")
.takes_value(true)
.long("extra"))
.get_matches_from_safe(vec![
"ri", "--extra", "val"
]);
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
```
Relates to #764
An arg can now conditionally require additional arguments if it's value matches a specific value.
For example, arg A can state that it only requires arg B if the value X was used with arg A. If any
other value is used with A, arg B isn't required.
Relates to #764
One can now implement conditional default values. I.e. a default value that is only applied in
certain conditions, such as another arg being present, or another arg being present *and*
containing a specific value.
Now it's possible to say, "Only apply this default value if arg X is present" or "Only apply this
value if arg X is present, but also only if arg X's value is equal to Y"
This new method is fully compatible with the current `Arg::default_value`, which gets set only if
the arg wasn't used at runtime *and* none of the specified conditions were met.
Releates to #764
Instead of using Format::Error directly, we need to use a Colorizer to
make sure that the message only gets colorized when it is appropriate
to do so.
Fixes#775
The implementation is basically manually expanded lazy_static! macro
(with some hand-crafted simplifications and inlining), since you can't
use extern crates (and therefore import macros therefrom) in macros.
This ensures that you get this:
p:\Rust\http>target\debug\http -h
http 0.1.0
thecoshman <thecoshman@gmail.com>
nabijaczleweli <nabijaczleweli@gmail.com>
Host These Things Please - a basic HTTP server for hosting a folder fast and simply
Instead of this:
p:\Rust\http>target\debug\http -h
http 0.1.0
thecoshman <thecoshman@gmail.com>:nabijaczleweli <nabijaczleweli@gmail.com>
Host These Things Please - a basic HTTP server for hosting a folder fast and simply
Closes#779
Since ZSH completions use `[ and ]` for descriptions, but clap args use `[ and ]` for possible
values and other auxillary arg information, this was creating a conflict. clap now escapes any
square brackets before writing the help, i.e. `\\[ and \\]` which removes conflicts.
Alternatives would be to switch `[ and ]` for `( and )` but this would create a slight difference
in help messages and completions.
Closes#771
With these options, in case the completion function cannot provide
suggestions, Bash will perform its default completions, based on e.g.
files, directories, and variable names. This is particularly useful for
argument values.
Prior to this commit setting `number_of_values(1)` and `multiple(true)` would cause the help
message alignment to be off. This commit fixes that.
Closes#760
One can now use `Arg::allow_hyphen_values(true)` which will enable `--opt -val` style values only
for the specific arg and not command wide.
Closes#742
Flags, Opts, and Positionals now store their internals using compartmented Base, Valued, and
Switched structs to keep the code duplication down and make it easier to maintain.
Iniside the src/app/parser.rs there have been several changes to make reasoning about the code
easier. Primarily moving related sections out of the large get_matches_with into their own
functions.
Now one can build CLIs that support things like `mv <files>... <target>`
There are a few requirements and caveats;
* The final positional argument (and all positional arguments prior) *must* be required
* Only one positional argument may be `multiple(true)`
* Only the second to last, or last positional argument may be `multiple(true)`
Closes#725
Prior to this commit, conflicting error messages and the suggeseted usage would depend on whether
you defined the conflict on both arguments, or just one, and the order in which you specified the
conflicting arguments at runtime.
Now they are symetrical, meaning the suggestions from the error message are consistent, and it no
longer matters if you specify the conflict in one, or both arguments.
Closes#718
Don't attempt to change the display order of flags/options until any app
settings have been propagated down from a parent App in case DeriveDisplayOrder
and/or UnifiedHelpMessage are propagated.
Fixes#706
One can now use `AppSettings::AllowNegativeNumbers` which functions similar to `AllowLeadingHyphen`
with the exception that only unknown numbers are allowed have a preceding hyphen character.
See the documentation for details and examples.
Closes#696
* Clap has dependencies even with all features disabled.
* The "nightly" feature does nothing, so don't mention it.
* Explain the difference between "unstable" and "nightly" better.
* Split features into groups (default, opt-in, clap-development).
* For contributors: update what tests should be run, and remove make command.
* Removes a repeated word and splits up some long markdown lines.
Also groups features by category and dependencies by feature in Cargo.toml.
The new version of rustc 1.14.0-nightly (144af3e97 2016-10-02) has new
linting warnings/errors. This commit fixes them.
Signed-off-by: Salim Afiune <afiune@chef.io>
Added same alias funtionality for flags, now you can do:
```
Arg::with_name("flg")
.long("flag")
.short("f")
.alias("not_visible_flag")
.visible_alias("awesome_v_flag")
```
Signed-off-by: Salim Afiune <afiune@chef.io>
There are some cases where you need to have an argument to have an
alias, an example could be when you depricate one option in favor of
another one.
Now you are going to be able to alias arguments as follows:
```
Arg::with_name("opt")
.long("opt")
.short("o")
.takes_value(true)
.alias("invisible")
.visible_alias("visible")
```
Closes#669
This should also speeds up the parser (except maybe for short options).
Multi-codepoint characters still can't be used as short options, but people shouldn't non-ASCII options nyway.
Closes#664
Now if one wishes to use value delimiters, they must explicitly set `Arg::use_delimiter(true)` or
`Arg::require_delimiter(true)`. No other methods implicitly set this value.
Closes#666
Previously one could only hide the possible values of an argument application or command wide, and
not on a per argument basis. Now one can use the `Arg::hide_possible_values(bool)` method to hide
only that arguments possible values.
Closes#640
Prior to this change, values were always delimited by default. This was causing issues with code
where the arg had a single value, and contained valid commas and shouldn't be delimited. This
commit changes the rules slightly so that values are not delimited by default, *unless* one of the
methods which implies multiple values was used (max_values, value_names, etc.).
This means single value args should *not* be delimited by default. If one wishes to use the old
way, they can add `Arg::use_delimiter(true)` to such code.
Closes#655
Prior to this commit, clap would mangle help messages with hard newlines
(see #617). After this commit, clap will ignore hard newlines and treat
them like an inserted newline, properly wrapping and aligning text and
then restarting it's count until the next newline should be inserted.
This commit also removes the need for using `{n}` to insert a newline in
help text, now the traditional `\n` can be used. For backwards
compatibility, the `{n}` still works.
Closes#617
In some cases settings were only propogated down one level deep, this
commit ensures settings are propogated down through all subcommands
recursively.
Closes#638
This is useful if a more meaningful message can be displayed to the
user with `Error::exit`. For example, if a file is not found, the
converted `io::Error` will give a message like:
"error: entity not found"
With this, it is possible to replace this message with a more useful
one, like for instance:
"error: configuration file not found"
Coloring is respected. Some duplication in the `From::from` impls was
reduced.
* feat: adds App::with_defaults to automatically use crate_authors! and crate_version! macros
One can now use
```rust
let a = App::with_defaults("My Program");
// same as
let a2 = App::new("My Program")
.version(crate_version!())
.author(crate_authors!());
```
Closes#600
* imp(YAML Errors): vastly improves error messages when using YAML
When errors are made while developing, the panic error messages have
been improved instead of relying on the default panic message which is
extremely unhelpful.
Closes#574
* imp(Completions): uses standard conventions for bash completion files, namely '{bin}.bash-completion'
Closes#567
* imp(Help): automatically moves help text to the next line and wraps when term width is determined to be too small, or help text is too long
Now `clap` will check if it should automatically place long help
messages on the next line after the flag/option. This is determined by
checking to see if the space taken by flag/option plus spaces and values
doesn't leave enough room for the entirety of the help message, with the
single exception of of if the flag/option/spaces/values is less than 25%
of the width.
Closes#597
* tests: updates help tests to new forced new line rules
* fix(Groups): fixes some usage strings that contain both args in groups and ones that conflict with each other
Args that conflict *and* are in a group will now only display in the
group and not in the usage string itself.
Closes#616
* chore: updates dep graph
Closes#633
* chore: clippy run
* style: changes debug header to match other Rust projects
* chore: increase version
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
One can now use a list or single value for certain Arg YAML declarations
such as possible_values, etc.
Prior to this commit, if only a single value was desired one would have
to use the format:
```yaml
possible_values:
- value
```
But now once can use
```yaml
possible_values: value
```
Closes#614Closes#613
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
Aliases to subcommands can now be completed just like the original subcommand they alias.
Imagine a subcommand `update` with alias `install`, the `update` subcommand has an option `--pkg`
which accepts a package to update/install.
The following completion would happen:
```
$ prog <tab><tab>
-h --help -V --version install update
$ prog install <tab><tab>
-h --help -V --version --pkg
$ prog install --pkg <tab><tab>
$ prog install --pkg <PACKAGE>
$ prog update <tab><tab>
-h --help -V --version --pkg
$ prog update --pkg <tab><tab>
$ prog update --pkg <PACKAGE>
```
Closes#556
Prior to this change, completions only allowed one completion per command, this change allows as
many as required. The one downside to this change is the completion engine isn't smart enough to
determine which options are no longer legal after certain options have been applied.
Now when one completes an option with possible values, those values will be displayed. Imagine
a program with an `--editor` option, which accepts either `vi`, or `emacs`. The following would
be displayed for completions
```
$ prog --editor <tab><tab>
vi emacs
```
Closes#557
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
One can now use more than one meta item, and things like `#[repr(C)]`
Example:
```rust
arg_enum! {
#[repr(C)]
#[derive(Debug)]
pub enum MyEnum {
A=1,
B=2
}
}
```
Closes#543
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
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
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
Some types weren't viewable in the docs, such as `Values`, `OsValues`,
and `ArgSettings`. All these types should now be browsable in the
docs page.
Relates to #505
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
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
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.
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.
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.
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.
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.
`write_nspaces` has three differences with `write_spaces`
1. Accepts arguments with attribute access (such as self.writer)
2. The order of the arguments is swapped to make the writer the first
argument as in other write related macros.
3. Does not use the `write!` macro under the hood but rather calls
directly `write`
I have chosen to put the function under a new name to avoid backwards
compatibility problem but it might be better to migrate everything to
`write_nspaces` (and maybe rename it `write_spaces`)
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.
This commit introduces a new trait (`DispOrder`) with a single function
(`fn disp_order(&self) -> usize`). It is use to expose the display order
of an argument in a read-only manner.
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
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
Now if the terminal size is too small to properly wrap the help text
lines, it will default to just wrapping normalling as it should.
This is determined on a per help text basis, so because the terminal
size is too small for a single argument's help to wrap properly, all
other arguments will still wrap and align correctly. Only the one
affected argument will not align properly.
Closes#453
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
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
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
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
