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
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
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
ArgGroups can now be built from standalone YAML documents. This is
labeled as a fix because it should have been the case prior. A
standalone YAML document for a group would look something like
```
name: test
args:
- arg1
- arg2
required: true
conflicts:
- arg3
requires:
- arg4
```
This commit also keeps support building groups as part of a larger
entire App YAML document where the name is specified as a key to the
yaml tree
