Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-12-13 22:32:33 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs: updates docs for new features

Browse source
This commit is contained in:
Kevin K 2015-08-14 20:25:21 -04:00
parent 4a00e2510d
commit 0349654717
2 changed files with 30 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
README.md
View file

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

31
src/app.rs
View file

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