This commit primarily changes to a lazy handling of POSIX overrides by
relying on github.com/bluss/ordermap instead of the old HashMap impl.
The ordermap allows us to keep track of which arguments arrived first,
and therefore determine which ones should be removed when an override
conflict is found.
This has the added benefit of we no longer have to do the bookkeeping to
keep track and override args as they come in, we can do it once at the
end.
Finally, ordermap allows fast Vec like iteration of the keys, which we
end up doing several times. Benching is still TBD once the v3 prep is
done, but this change should have a meaningful impact.
Contains a *MINOR* breaking change. App::write_help now requires `&mut self` instead of `&self`.
This fixes a major bug where the help message is entirely incorrect.
More can be found at https://github.com/kbknapp/clap-rs/issues/808
I've decided to make this change because it was preventing further progress.
Anyone's code who breaks the fix is trivial:
```rust
// OLD BROKEN
let app = App::new("broken");
let mut out = io::stdout();
app.write_help(&mut out).expect("failed to write to stdout");
// NEW FIX
let mut app = App::new("broken"); // <-- let mut
let mut out = io::stdout();
app.write_help(&mut out).expect("failed to write to stdout");
```
Closes#808
Optional positionals mixed with subcommands will still break this, since
I can't see how to tell which element of $line is the command than.
Mixing optional positionals with subcommands is a bit weird and awkward
though...
This changes the way we complete positionals to complete them using
_arguments, as should be done, instead of completing their uppercase name
as a string.
Currently I made it offer _files completion for all positional arguments.
This can be improved to complete actual possible values of the arguments
and only complete files if the argument truly takes them. But this will
require further changes in clap to actually have the required
functionality to get this information.
This commit removes heavy use of macros in certain functions which
drastically increased code size. Some of the macros could be turned
into functions, while others could be removed entirely.
Examples were removing arg_post_processing! which did things like
checked overrides, requirements, groups, etc. This would happen
after every argument was parsed. This macro also had several other
macros inside it, and would expand to several tens or hundreds of
lines of code.
Then add that due to borrowck and branch issues, this macro may be
included in multiple parts of a function. Unlike traditional functions
each of these uses expanded into TONS of code (just like agressive
inlining).
This commit primarily removes those arg_post_processing! calls and
breaks up the functionality into two types. The first must happen at
ever new argument (not new value, but new argument). This is pretty
cheap. The next type was moved to the end of parsing validation section
which is more expensive, but only happens once.
i.e. clap was validating each argument/value as it saw them, now it's
lazy and validates them all at once at the end. This MUCH more
efficient!
Long options take their argument either in the next word or after an
equals sign, but the Zsh completion specified that they take it either
in the same word with no separator or in the next word. See the
documentation of the Zsh _arguments function for more information.
Small correction to add a link to the source in the documentation, previously
it was a placeholder.
`rustdoc` does not appear to package assets with the docs, therefore
relative links looking for static files do not work. The links are
consistent enough on github that the static files can be directly linked
to on the master branch.
When used with `Arg::possible_values` it allows the argument value to pass validation even if
the case differs from that of the specified `possible_value`.
```rust
let m = App::new("pv")
.arg(Arg::with_name("option")
.long("--option")
.takes_value(true)
.possible_value("test123")
.case_insensitive(true))
.get_matches_from(vec![
"pv", "--option", "TeSt123",
]);
assert!(m.value_of("option").unwrap().eq_ignore_ascii_case("test123"));
```
This setting also works when multiple values can be defined:
```rust
let m = App::new("pv")
.arg(Arg::with_name("option")
.short("-o")
.long("--option")
.takes_value(true)
.possible_value("test123")
.possible_value("test321")
.multiple(true)
.case_insensitive(true))
.get_matches_from(vec![
"pv", "--option", "TeSt123", "teST123", "tESt321"
]);
let matched_vals = m.values_of("option").unwrap().collect::<Vec<_>>();
assert_eq!(&*matched_vals, &["TeSt123", "teST123", "tESt321"]);
```
Closes#1118
Currently to use these traits clap must be built with the `unstable` feature. This does not
require a nightly compiler. These traits and APIs may change without warning (hence the `unstable`
feature flag). Once they have been stablelized and the `clap-derive` crate is released the
`unstable` feature flag will no longer be required.
* bash-completions have code to use only `foo`, `foo.bash` and `_foo`
files for completion
* /usr is proper place for system-wide stuff rather than /etc
Signed-off-by: Igor Gnatenko <i.gnatenko.brain@gmail.com>
Since options have `empty_values(true)` by default, so long as another valid flag
or option came after the option in question, clap would parse it as an empty value
incorrectly. This commit forces the user to explicitly add an empty value.
`--option "" --flag` is allowed
`--option --flag` is no longer allowed unless the user has *also* set `min_values(0)`
This commit also fixes an issue where `-o=` would be parsed as a value of `Some("=")`
instead of `Some("")`.
Closes#1105
If one is using a nightly Rust compiler they should compile clap
with the `nightly` feature.
```toml
[dependencies]
clap = { version = "2.27", features = ["nightly"] }
```
This isn't required for compilation to succeed, only to take
advantage of any nightly features used by clap.
If one is compiling with `#[deny(warnings)]` this commit will cause
compilation to fail if one *does not* compile with the `nightly`
since `std::ascii::AsciiExt` is no longer required in in multiple
files as of the latest Rust nightly (Nov 6th, 2017).
Closes#1095
Prior to this commit, using `AppSettings::AllowHyphenValues` would allow
ANY argument to pass, even if there was no way it could be valid.
Imagine a CLI with only a single flag (i.e. *no value*) `--flag`, but this setting
is set. The following was valid:
```
$ prog hello
```
This commit fixes that by creating an UnknownArgument error unless the
unknown argument/value in question could legally be parsed as a value
to a valid argument.
Closes#1066
**This commit contains a breaking change in order to fix a bug.**
The only users affected are those relying on the "bug." The bug is only in code that uses
subcommands, and parent commands with arguments accepting multiple values (positionals or options)
unrestrained *and* where a value may coincide with a subcommand's name.
Imagine a CLI with a positional argument `files` that accepts multiple values but no other conditions
or parameters (just `Arg::multiple(true)`), and a subcommand `log`
Prior to this commit, the following was valid:
```
$ prog file1 file2 file3 log
```
which would be parsed as:
* files = file1, file2, file3
* subcommand = log
However, if there was a file named `log` the subcommand isn't callable.
The CLI should be designed in a way that either limits number of values so that clap knows
when `files` is done and can then look for subcommands, or other AppSettings which change
the behavior.
Possible fixes are `Arg::number_of_values`, `Arg::max_values`,
`AppSettings::ArgsNegateSubcommands`, `Arg::require_equals`,
`AppSettings::SubcommandsNegateArgs`, and more.
This *does not* affect CLIs which contain other arguments between the unrestrained multiple
value args, and the any subcommands. Such as if our example above also had a flag `-f`
The following would be parsed the same before and after this commit.
```
$ prog file1 file2 file3 -f log
```
This is because upon reaching the flag `-f`, clap stops parsing `files`.
No other breaking changes were made.
---
When using args with `multiple(true)` on options or positionals (i.e. those args that
accept values) and subcommands, one needs to consider the posibility of an argument value
being the same as a valid subcommand. By default `clap` will parse the argument in question
as a value *only if* a value is possible at that moment. Otherwise it will be parsed as a
subcommand. In effect, this means using `multiple(true)` with no additional parameters and
a possible value that coincides with a subcommand name, the subcommand cannot be called
unless another argument is passed first.
As an example, consider a CLI with an option `--ui-paths=<paths>...` and subcommand `signer`
The following would be parsed as values to `--ui-paths`.
```
$ program --ui-paths path1 path2 signer
```
This is because `--ui-paths` accepts multiple values. `clap` will continue parsing values
until another argument is reached and it knows `--ui-paths` is done.
By adding additional parameters to `--ui-paths` we can solve this issue. Consider adding
`Arg::number_of_values(1)` as discussed above. The following are all valid, and `signer`
is parsed as both a subcommand and a value in the second case.
```
$ program --ui-paths path1 signer
$ program --ui-paths path1 --ui-paths signer signer
```
Closes#1031
