mirror of
https://github.com/clap-rs/clap
synced 2024-12-14 06:42:33 +00:00
commit
f6635b0baa
2 changed files with 124 additions and 0 deletions
90
CHANGELOG.md
90
CHANGELOG.md
|
@ -14,6 +14,95 @@ whether in changes or their motivation.
|
||||||
TBD:
|
TBD:
|
||||||
- `AppSettings::ColoredHelp`: we are now relying solely on the `color` feature flag and `App::color` method
|
- `AppSettings::ColoredHelp`: we are now relying solely on the `color` feature flag and `App::color` method
|
||||||
|
|
||||||
|
### Highlights
|
||||||
|
|
||||||
|
**[StructOpt](https://docs.rs/structopt/) Integration**
|
||||||
|
|
||||||
|
[StructOpt](https://docs.rs/structopt/) provides a serde-like declarative
|
||||||
|
approach to defining your parser. The main benefits we've seen so far from integrating are:
|
||||||
|
- Tighter feedback between the design of clap and the derives
|
||||||
|
- More universal traits. Crates exist for common CLI patterns
|
||||||
|
([example](https://github.com/rust-cli/clap-verbosity-flag))
|
||||||
|
and we've re-designed the `StructOpt` traits so crates built on clap3 can be
|
||||||
|
reused not just with other derives but also people using the builder API.
|
||||||
|
People can even hand implement these so people using the builder API won't
|
||||||
|
have the pay the cost for derives.
|
||||||
|
|
||||||
|
**Custom Help Headings**
|
||||||
|
|
||||||
|
Previously, clap automatically grouped arguments in the help as either
|
||||||
|
`ARGS`, `FLAGS`, `OPTIONS`, and `SUBCOMMANDS`.
|
||||||
|
|
||||||
|
You can now override the default group with `Arg::help_heading` and
|
||||||
|
`App::subcommand_help_heading`. To apply a heading to a series of arguments,
|
||||||
|
you can set `App::help_heading`.
|
||||||
|
|
||||||
|
### Migrating
|
||||||
|
|
||||||
|
**From clap v2**
|
||||||
|
|
||||||
|
1. Update your dependency
|
||||||
|
1. *If you use `no-default-features`:* add the `std` feature
|
||||||
|
2. Resolve compiler errors
|
||||||
|
3. Resolve behavior changes
|
||||||
|
1. Refactor your `App` creation to a function and add a test similar to the one below, resolving any of its assertions
|
||||||
|
2. Look over the "subtle changes" under BREAKING CHANGES
|
||||||
|
3. *If using builder:* test your application under various circumstances to see if `ArgMatches` asserts regarding `AllowInvalidUtf8`.
|
||||||
|
4. *At your leisure:* resolve deprecation notices
|
||||||
|
|
||||||
|
Example test:
|
||||||
|
```rust
|
||||||
|
fn app() -> clap::App {
|
||||||
|
...
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn verify_app() {
|
||||||
|
app.debug_assert();
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**From structopt 0.3.25**
|
||||||
|
|
||||||
|
1. Update your dependency, adding the `derive` feature flag
|
||||||
|
1. *If you use `no-default-features`:* add the `std` feature
|
||||||
|
2. Resolve compiler errors, including
|
||||||
|
1. Update your `use` statements from `structopt` and `structopt::clap` to `clap`
|
||||||
|
3. Resolve behavior changes
|
||||||
|
1. Add a test similar to the one below, resolving any of its assertions
|
||||||
|
2. Look over the "subtle changes" under BREAKING CHANGES
|
||||||
|
4. *At your leisure:* resolve deprecation notices
|
||||||
|
|
||||||
|
Example test:
|
||||||
|
```rust
|
||||||
|
#[derive(clap::StructOpt)]
|
||||||
|
struct Args {
|
||||||
|
...
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn verify_app() {
|
||||||
|
use clap::IntoApp;
|
||||||
|
Args::into_app().debug_assert()
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**From clap v3.0.0-beta.5**
|
||||||
|
|
||||||
|
1. Update your dependency
|
||||||
|
1. Add in `derive`, `env`, `cargo`, or `unicode` feature flags as needed
|
||||||
|
2. Resolve compiler errors
|
||||||
|
2. *If you use `yaml`, `clap_app!`, or usage parser:* revert any changes you made for clap3
|
||||||
|
2. Change `Arg::about` `Arg::long_about` back to `help` and `long_help` and change `PossibleValue::about` to `help` ([clap-rs/clap#2937](https://github.com/clap-rs/clap/discussions/2937))
|
||||||
|
3. Change `AppSettings::HelpRequired` to `AppSettings::HelpExpected`
|
||||||
|
4. Change `PossibleValue::hidden` to `PossibleValue::hide`
|
||||||
|
5. Change `App::subcommand_placeholder` to `App::subcommand_value_name` / `App::subcommand_help_heading`
|
||||||
|
3. Resolve behavior changes
|
||||||
|
2. Add the above listed test appropriate for your application and resolve any problems it reports
|
||||||
|
1. *If using `derive`:* see the structopt breaking changes section for `Vec` changes
|
||||||
|
3. *If using builder:* test your application under various circumstances to see if `ArgMatches` asserts regarding `AllowInvalidUtf8`.
|
||||||
|
4. *At your leisure:* resolve deprecation notices
|
||||||
|
|
||||||
### BREAKING CHANGES
|
### BREAKING CHANGES
|
||||||
|
|
||||||
**From clap 2**
|
**From clap 2**
|
||||||
|
@ -129,6 +218,7 @@ While a lot of deprecations have been added to clean up the API (overloaded mean
|
||||||
- `Arg::default_missing_value` for cases like `--color[=<WHEN>]` ([clap-rs/clap#1587](https://github.com/clap-rs/clap/pull/1587))
|
- `Arg::default_missing_value` for cases like `--color[=<WHEN>]` ([clap-rs/clap#1587](https://github.com/clap-rs/clap/pull/1587))
|
||||||
- `clap::App::color` / `clap::ColorChoice` to specify color setting for the app
|
- `clap::App::color` / `clap::ColorChoice` to specify color setting for the app
|
||||||
- Custom error reporting with `App::error`
|
- Custom error reporting with `App::error`
|
||||||
|
- `App::debug_assert` test helper
|
||||||
- Replace `Arg::multiple(bool)` with `Arg::multiple_values` / `Arg::multiple_occurrences`
|
- Replace `Arg::multiple(bool)` with `Arg::multiple_values` / `Arg::multiple_occurrences`
|
||||||
- Positionals can be either
|
- Positionals can be either
|
||||||
- Added support for flag subcommands like pacman ([clap-rs/clap#1361](https://github.com/clap-rs/clap/issues/1361))
|
- Added support for flag subcommands like pacman ([clap-rs/clap#1361](https://github.com/clap-rs/clap/issues/1361))
|
||||||
|
|
|
@ -1889,6 +1889,40 @@ impl<'help> App<'help> {
|
||||||
self
|
self
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Catch problems earlier in the development cycle.
|
||||||
|
///
|
||||||
|
/// Most error states are handled as asserts under the assumption they are programming mistake
|
||||||
|
/// and not something to handle at runtime. Rather than relying on tests (manual or automated)
|
||||||
|
/// that exhaustively test your CLI to ensure the asserts are evaluated, this will run those
|
||||||
|
/// asserts in a way convenient for running as a test.
|
||||||
|
///
|
||||||
|
/// **Note::** This will not help with asserts in [`ArgMatches`], those will need exhaustive
|
||||||
|
/// testing of your CLI.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```rust
|
||||||
|
/// # use clap::{App, Arg};
|
||||||
|
/// fn app() -> App<'static> {
|
||||||
|
/// App::new("foo")
|
||||||
|
/// .arg(Arg::new("bar").short('b')
|
||||||
|
/// )
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// #[test]
|
||||||
|
/// fn verify_app() {
|
||||||
|
/// app().debug_assert();
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// fn main() {
|
||||||
|
/// let m = app().get_matches_from(vec!["foo", "-b"]);
|
||||||
|
/// println!("{}", m.is_present("bar"));
|
||||||
|
/// }
|
||||||
|
/// ```
|
||||||
|
pub fn debug_assert(mut self) {
|
||||||
|
self._build_all();
|
||||||
|
}
|
||||||
|
|
||||||
/// Custom error message for post-parsing validation
|
/// Custom error message for post-parsing validation
|
||||||
///
|
///
|
||||||
/// # Examples
|
/// # Examples
|
||||||
|
|
Loading…
Reference in a new issue