Merge pull request #58 from epage/migrate

Help Users Migrate to clap3

CHANGELOG.md

@@ -14,6 +14,95 @@ 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**
+
+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**
@@ -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))
 - `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))

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