diff --git a/README.md b/README.md index 122a3487..67c1a5f0 100644 --- a/README.md +++ b/README.md @@ -8,15 +8,10 @@ It is a simple to use, efficient, and full featured library for parsing command ## What's New -If you're already familiar with `clap` but just want to see some new highlights as of **1.1.3** +If you're already familiar with `clap` but just want to see some new highlights as of **1.2.0** -* **Works on Windows again!** - You can now use `clap` on Windows again! -* **Newlines properly aligned in help strings!** - Allows one to specify a newline in long help strings. **Note:** Specify the newlines in help strings via `{n}` and *not* `\n` due to how `clap` handles help parsing. -* **Unified Help Format** - This is cosmetic only, but allows a help message formated similiar to `docopt` or `getopts` where what `clap` calls "options" and "flags" are combined into a single group (and still properly aligned and formatted) -* **Can propogate versions through subcommands auto-matically** - This allows all subcommands to handle `--version` or `-V` with the same version as the parent application -* **Can specify that subcommands disable version** - Can now say `--version` and `-V` won't be valid flags for subcommands -* **Big performacne improvement when printing help messages** - While printing help messages wasn't slow before, it's now super fast ;) -* **PSA: Deprecated Functions Removed as of 1.0** - In an effort to start a 1.x all deprecated functions have been removed, see the deprecations sections below to update your code (very minimal) +* Custom validations are now supported! You can define a function to validate argument values, or fail parsing with a custom error message. Meaning your application logic can focus soley on *using* values. +* Improved ergonomics - Some `App` methods have been deprecated (won't be removed until 2.x) to support a more ergonomic `.setting()` method which takes an `AppSettings` enum value. This makes it easier to find `App` settings (just view all variants of the enum). For full details see the [changelog](https://github.com/kbknapp/clap-rs/blob/master/CHANGELOG.md) @@ -68,6 +63,7 @@ Below are a few of the features which `clap` supports, full descriptions and usa * **Suggestions**: Suggests corrections when the user enter's a typo. For example, if you defined a `--myoption ` argument, and the user mistakenly typed `--moyption value` (notice `y` and `o` switched), they would receive a `Did you mean '--myoption' ?` error and exit gracefully. This also works for subcommands and flags. (Thanks to [Byron](https://github.com/Byron) for the implementation) (This feature can optionally be disabled, see 'Optional Dependencies / Features') * **Colorized (Red) Errors (Non Windows OS only)**: Error message are printed in red text (this feature can optionally be disabled, see 'Optional Dependencies / Features'). * **Global Arguments**: Arguments can optionally be defined once, and be available to all child subcommands. +* **Custom Validations**: You can define a function to use as a validator of argument values. Imagine defining a function to validate IP addresses, or fail parsing upon error. This means your application logic can be soley focused on *using* values. ## Quick Example diff --git a/src/app.rs b/src/app.rs index c2c5dc60..b5a53841 100644 --- a/src/app.rs +++ b/src/app.rs @@ -394,6 +394,9 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ /// if you had a subcommand or even top level application which had a required arguments that /// are only required as long as there is no subcommand present. /// + /// **Deprecated:** Use `App::setting()` with `AppSettings::SubcommandsNegateReqs` instead. This + /// method will be removed at 2.x + /// /// **NOTE:** This defaults to false (using subcommand does *not* negate requirements) /// /// # Example @@ -411,6 +414,9 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ /// Allows specifying that if no subcommand is present at runtime, error and exit gracefully /// + /// **Deprecated:** Use `App::setting()` with `AppSettings::SubcommandRequired` instead. This + /// method will be removed at 2.x + /// /// **NOTE:** This defaults to false (subcommands do *not* need to be present) /// /// # Example @@ -556,6 +562,9 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ /// Specifies that the help text sould be displayed (and then exit gracefully), if no /// arguments are present at runtime (i.e. an empty run such as, `$ myprog`. /// + /// **Deprecated:** Use `App::setting()` with `AppSettings::ArgRequiredElseHelp` instead. This + /// method will be removed at 2.x + /// /// **NOTE:** Subcommands count as arguments /// /// # Example @@ -574,6 +583,9 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ /// Uses version of the current command for all subcommands. (Defaults to false; subcommands /// have independant version strings) /// + /// **Deprecated:** Use `App::setting()` with `AppSettings::GlobalVersion` instead. This + /// method will be removed at 2.x + /// /// **NOTE:** The version for the current command and this setting must be set **prior** to /// adding any subcommands /// @@ -597,6 +609,9 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ /// Disables `-V` and `--version` for all subcommands (Defaults to false; subcommands have /// version flags) /// + /// **Deprecated:** Use `App::setting()` with `AppSettings::VersionlessSubcommands` instead. This + /// method will be removed at 2.x + /// /// **NOTE:** This setting must be set **prior** adding any subcommands /// /// **NOTE:** Do not set this value to false, it will have undesired results! @@ -621,6 +636,9 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ /// separately. This setting disable that and groups flags and options together presenting a /// more unified help message (a la getopts or docopt style). /// + /// **Deprecated:** Use `App::setting()` with `AppSettings::UnifiedHelpMessage` instead. This + /// method will be removed at 2.x + /// /// **NOTE:** This setting is cosmetic only and does not affect any functionality. /// /// # Example @@ -645,6 +663,9 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ /// command line (i.e. set `.arg_required_else_help(true)` and `.wait_on_error(true)` to /// display the help in such a case). /// + /// **Deprecated:** Use `App::setting()` with `AppSettings::WaitOnError` instead. This + /// method will be removed at 2.x + /// /// **NOTE:** This setting is **not** recursive with subcommands, meaning if you wish this /// behavior for all subcommands, you must set this on each command (needing this is extremely /// rare) @@ -665,6 +686,9 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ /// Specifies that the help text sould be displayed (and then exit gracefully), if no /// subcommands are present at runtime (i.e. an empty run such as, `$ myprog`. /// + /// **Deprecated:** Use `App::setting()` with `AppSettings::SubcommandRequiredElseHelp` instead. This + /// method will be removed at 2.x + /// /// **NOTE:** This should *not* be used with `.subcommand_required()` as they do the same /// thing, except one prints the help text, and one prints an error. /// @@ -701,6 +725,7 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ self } + // actually adds the settings fn add_setting(&mut self, s: &AppSettings) { match *s { AppSettings::SubcommandsNegateReqs => self.subcmds_neg_reqs = true, @@ -764,6 +789,7 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ self } + // actually adds the arguments fn add_arg(&mut self, a: Arg<'ar, 'ar, 'ar, 'ar, 'ar, 'ar>) { if self.flags.contains_key(a.name) || self.opts.contains_key(a.name) || @@ -781,11 +807,6 @@ impl<'a, 'v, 'ab, 'u, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>{ // from the group, or the argument.", a.name, grp)); } if let Some(s) = a.short { - // if s == 'V' { - // self.version_short = None; - // } else if s == 'h' { - // self.help_short = None; - // } if self.short_list.contains(&s) { panic!("Argument short must be unique\n\n\t-{} is already in use", s); } else {