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
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.
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.
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
