Merge pull request #58 from epage/migrate

Help Users Migrate to clap3
This commit is contained in:
Ed Page 2021-12-04 07:38:48 -06:00 committed by GitHub
commit f6635b0baa
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 124 additions and 0 deletions

View file

@ -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))

View file

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