Merge pull request #250 from epage/tweaks

Tweaks

Cargo.toml

@@ -11,7 +11,6 @@ version = "3.0.0-beta.5"
 description = "A simple to use, efficient, and full-featured Command Line Argument Parser"
 repository = "https://github.com/clap-rs/clap"
 documentation = "https://docs.rs/clap/"
-homepage = "https://clap.rs/"
 categories = ["command-line-interface"]
 keywords = [
 	"argument",

README.md

@@ -95,11 +95,16 @@ OPTIONS:
 - Flexible enough to port your existing CLI interface
   - However, we won't necessarily streamline support for each use case
 - Reasonable parse performance
-- We will support the last two minor Rust releases (MSRV)
+- Resilient maintainership, including
+  - Willing to break compatibility rather than batching up breaking changes in large releases
+  - Leverage feature flags to keep to one active branch
+  - Being under [WG-CLI](https://github.com/rust-cli/team/) to increase the bus factor
 - We follow semver and will wait about 6 months between major breaking changes
+- We will support the last two minor Rust releases (MSRV)
 
 While these aspirations can be at odds with fast build times and low binary
-size, we will still strive to keep these reasonable.  Check out the
+size, we will still strive to keep these reasonable for the flexibility you
+get.  Check out the
 [argparse-benchmarks](https://github.com/rust-cli/argparse-benchmarks-rs) for
 CLI parsers optimized for other use cases.
 

clap_derive/Cargo.toml

@@ -11,7 +11,6 @@ include = [
 description = "Parse command line argument by defining a struct, derive crate."
 repository = "https://github.com/clap-rs/clap/tree/master/clap_derive"
 documentation = "https://docs.rs/clap_derive"
-homepage = "https://clap.rs/"
 keywords = [
 	"clap",
 	"cli",

clap_generate/Cargo.toml

@@ -11,7 +11,6 @@ include = [
 description = "A generator library used with clap for shell completion scripts, manpage, etc."
 repository = "https://github.com/clap-rs/clap/tree/master/clap_generate"
 documentation = "https://docs.rs/clap_generate"
-homepage = "https://clap.rs/"
 keywords = [
 	"clap",
 	"cli",

clap_generate/README.md

@@ -9,4 +9,3 @@ Generates completions (and other things) for [`clap`](https://github.com/clap-rs
 
 * [Documentation](https://docs.rs/clap_generate)
 * [Questions & Discussions](https://github.com/clap-rs/clap/discussions)
-* [Website](https://clap.rs/)

clap_generate_fig/Cargo.toml

@@ -11,7 +11,6 @@ include = [
 description = "A generator library used with clap for Fig completion scripts"
 repository = "https://github.com/clap-rs/clap/tree/master/clap_generate_fig"
 documentation = "https://docs.rs/clap_generate_fig"
-homepage = "https://clap.rs/"
 keywords = [
 	"clap",
 	"cli",

clap_generate_fig/README.md

@@ -4,6 +4,5 @@ Generates [Fig](https://github.com/withfig/autocomplete) completions for [`clap`
 
 <!-- * [Documentation][docs] -->
 * [Questions & Discussions](https://github.com/clap-rs/clap/discussions)
-* [Website](https://clap.rs/)
 
 <!-- [docs]: https://docs.rs/clap_generate_fig -->

docs/FAQ.md

@@ -12,31 +12,30 @@
 
 ### Comparisons
 
-First, let me say that these comparisons are highly subjective, and not meant in a critical or harsh manner. All the argument parsing libraries out there (to include `clap`) have their own strengths and weaknesses. Sometimes it just comes down to personal taste when all other factors are equal. When in doubt, try them all and pick one that you enjoy :) There's plenty of room in the Rust community for multiple implementations!
+First, let me say that these comparisons are highly subjective, and not meant
+in a critical or harsh manner. All the argument parsing libraries out there (to
+include `clap`) have their own strengths and weaknesses. Sometimes it just
+comes down to personal taste when all other factors are equal. When in doubt,
+try them all and pick one that you enjoy :) There's plenty of room in the Rust
+community for multiple implementations!
 
-#### How does `clap` compare to [structopt](https://github.com/TeXitoi/structopt)?
-
-Simple! `clap` *is* `structopt`. With the 3.0 release, `clap` imported the `structopt` code into its own codebase as the [`clap_derive`](https://github.com/clap-rs/clap/tree/master/clap_derive) crate. Since `structopt` already used `clap` under the hood, the transition was nearly painless, and is 100% feature compatible. `structopt` is soft deprecated and will only support clap 2.x.
-
-If you were using `structopt` before, you have to change the attributes from `#[structopt(...)]` to `#[clap(...)]`.
-
-Also the derive statements changed from `#[derive(Structopt)]` to `#[derive(Parser)]`. There is also some additional functionality and breaking changes that's been added to the `clap_derive` crate. See the documentation for that crate, for more details.
-
-#### How does `clap` compare to [getopts](https://github.com/rust-lang-nursery/getopts)?
-
-`getopts` is a very basic, fairly minimalist argument parsing library. This isn't a bad thing, sometimes you don't need tons of features, you just want to parse some simple arguments, and have some help text generated for you based on valid arguments you specify. The downside to this approach is that you must manually implement most of the common features (such as checking to display help messages, usage strings, etc.). If you want a highly custom argument parser, and don't mind writing the majority of the functionality yourself, `getopts` is an excellent base.
-
-`getopts` also doesn't allocate much, or at all. This gives it a very small performance boost. Although, as you start implementing additional features, that boost quickly disappears.
+For less detailed but more broad comparisons, see
+[argparse-benchmarks](https://github.com/rust-cli/argparse-benchmarks-rs).
 
-Personally, I find many, many uses of `getopts` are manually implementing features that `clap` provides by default. Using `clap` simplifies your codebase allowing you to focus on your application, and not argument parsing.
-
-#### How does `clap` compare to [docopt.rs](https://github.com/docopt/docopt.rs)?
+#### How does `clap` compare to [structopt](https://github.com/TeXitoi/structopt)?
 
-I first want to say I'm a big a fan of BurntSushi's work, the creator of `Docopt.rs`. I aspire to produce the quality of libraries that this man does! When it comes to comparing these two libraries they are very different. `docopt` tasks you with writing a help message, and then it parses that message for you to determine all valid arguments and their use. Some people LOVE this approach, others do not. If you're willing to write a detailed help message, it's nice that you can stick that in your program and have `docopt` do the rest. On the downside, it's far less flexible.
+Simple! `clap` *is* `structopt`.  `structopt` started as a derive API built on
+top of clap v2.  With clap v3, we've forked structopt and integrated it
+directly into clap.
 
-`docopt` is also excellent at translating arguments into Rust types automatically. There is even a syntax extension which will do all this for you, if you're willing to use a nightly compiler (use of a stable compiler requires you to somewhat manually translate from arguments to Rust types). To use BurntSushi's words, `docopt` is also a sort of black box. You get what you get, and it's hard to tweak implementation or customize the experience for your use case.
+The benefits of integrating `structopt` and `clap` are:
+- Easier cross-linking in documentation
+- [Documentation parity](../examples)
+- Tighter design feedback loop, ensuring all new features are designed with
+  derives in mind and easier to change `clap` in response to `structopt` bugs.
+- Clearer endorsement of `structopt`
 
-Because `docopt` is doing a ton of work to parse your help messages and determine what you were trying to communicate as valid arguments, it's also one of the more heavy weight parsers performance-wise. For most applications this isn't a concern and this isn't to say `docopt` is slow, in fact far from it. This is just something to keep in mind while comparing.
+For more details on what has changed and how to migrate, see the [CHANGELOG](../CHANGELOG.md)
 
 #### What are some reasons to use `clap`? (The Pitch)
 
@@ -53,32 +52,18 @@ Depending on the style in which you choose to define the valid arguments, `clap`
  * You have complex requirements/conflicts between your various valid args.
  * You want to use subcommands (although other libraries also support subcommands, they are not nearly as feature rich as those provided by `clap`)
  * You want some sort of custom validation built into the argument parsing process, instead of as part of your application (which allows for earlier failures, better error messages, more cohesive experience, etc.)
- * You need more performance than `docopt` provides
-
-#### Reasons to `docopt`
-
- * You want *automatic* serialization of your arguments into Rust types (Although `clap` can do this, docopt is better at it)
- * You are on nightly Rust and want the library to automatically generate an "arguments struct" from the matched args
- * You are porting an application which uses docopt and already have the usage string already defined
-
-#### Reasons to use `getopts`
-
- * You need absolutely as few allocations as possible and don't mind implementing nearly everything yourself
- * You want a portion of the arg parsing process to be very custom (again, implementing the details yourself)
-
 
-### How many methods are there to create an App/Arg?
+### How many approaches are there to create an App/Arg?
 
 To build an `App` there are three:
 
-* Derive Macros
-* Builder Pattern
+- Derive Macros
+- Builder Pattern
 
 To build an `Arg` there are four:
 
-* Derive Macros
-* Builder Pattern
-* Usage Strings
+- Derive Macros
+- Builder Pattern
 
 ### Why is there a default subcommand of help?
 

src/parse/validator.rs

@@ -520,8 +520,8 @@ impl<'help, 'app, 'parser> Validator<'help, 'app, 'parser> {
         } else {
             false
         };
-        // Issue 665 (https://github.com/kbknapp/clap-rs/issues/665)
-        // Issue 1105 (https://github.com/kbknapp/clap-rs/issues/1105)
+        // Issue 665 (https://github.com/clap-rs/clap/issues/665)
+        // Issue 1105 (https://github.com/clap-rs/clap/issues/1105)
         if a.is_set(ArgSettings::TakesValue) && !min_vals_zero && ma.is_vals_empty() {
             return Err(Error::empty_value(
                 self.p.app,

tests/builder/require.rs

@@ -341,7 +341,7 @@ fn required_unless_any_2() {
 
 #[test]
 fn required_unless_any_works_with_short() {
-    // GitHub issue: https://github.com/kbknapp/clap-rs/issues/1135
+    // GitHub issue: https://github.com/clap-rs/clap/issues/1135
     let res = App::new("unlessone")
         .arg(Arg::new("a").conflicts_with("b").short('a'))
         .arg(Arg::new("b").short('b'))