docs: updates docs for new features

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!
+* 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.
-* **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.
+* 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).
-* **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)
 
 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 <value>` 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
 

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 {