From 0cd16c34fce03999e722725c8de5381cca446fe9 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 3 Dec 2021 14:12:03 -0600 Subject: [PATCH 1/3] feat: `App::debug_assert` test helper This will especially be important for users migrating from clap2 so they can catch problems earlier in the process. --- CHANGELOG.md | 1 + src/build/app/mod.rs | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index e27fed25..2df0b655 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -129,6 +129,7 @@ While a lot of deprecations have been added to clean up the API (overloaded mean - `Arg::default_missing_value` for cases like `--color[=]` ([clap-rs/clap#1587](https://github.com/clap-rs/clap/pull/1587)) - `clap::App::color` / `clap::ColorChoice` to specify color setting for the app - Custom error reporting with `App::error` +- `App::debug_assert` test helper - Replace `Arg::multiple(bool)` with `Arg::multiple_values` / `Arg::multiple_occurrences` - Positionals can be either - Added support for flag subcommands like pacman ([clap-rs/clap#1361](https://github.com/clap-rs/clap/issues/1361)) diff --git a/src/build/app/mod.rs b/src/build/app/mod.rs index af7f30a1..bba70452 100644 --- a/src/build/app/mod.rs +++ b/src/build/app/mod.rs @@ -1889,6 +1889,40 @@ impl<'help> App<'help> { 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 /// /// # Examples From d2af931c3d72004946cc0e20caf8dcc3f6ce8f33 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 3 Dec 2021 20:44:37 -0600 Subject: [PATCH 2/3] doc: Write up migration guide --- CHANGELOG.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2df0b655..12ea5704 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,72 @@ whether in changes or their motivation. TBD: - `AppSettings::ColoredHelp`: we are now relying solely on the `color` feature flag and `App::color` method +### 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 **From clap 2** From 951d1fc5c8416ba5d06446b2a1b5a8f00368fb84 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 3 Dec 2021 20:44:50 -0600 Subject: [PATCH 3/3] doc: Call out release highlights --- CHANGELOG.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 12ea5704..1eeba36a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,29 @@ whether in changes or their motivation. TBD: - `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**