Ported all the commits from structopt (#23)

* Automatic naming of fields and subcommands (#143) * Introduce smarter parsing of doc comments. (#146) * Fix invalid structopt syntax error message (#154) There was a typo preventing the probematic attr to be shown to the user. * Fix spelling: occurences -> occurrences, (#158) was found in comments and code, but required no user-facing API change. * Remove line-ending periods from short help. (#161) * Fix #168 * Support Option<Option<T>> field types (#190) * Support Option<Vec<T>> field type (#191) * Fix use of deprecated function * Fix some clippy lints * Update deprecated function and provide more info about the parsing error (#193) * Improve ChangeLog as suggested by @ErichDonGubler (#194) * [Casing] Change default from verbatim to kebab. (#204) .. fixes TeXitoi/structopt#202 * Use trybuild for testing expected proc macro errors (#205) * Custom attributes parser (#198) * update README.md for 0.3 fix #208 * Small fixes: clippy and typos (#215) * Add example for environment variables (#160) (#216) * Support skipping struct fields (#213) * Now error messages highlight the error location (#225) * Minor fixes * Change behavior of `about/author/version` and ad `no_version` * Emit error about `raw` removal * Update changelog * Update keyvalue example (#234) * Update documentation and changelog (#236) * Update dependencies (#227) * Bump minimum rustc version to 1.36 * Fix issues * Fix structopt-derive permissions (#239) * Fix #245 (#246) * Emit dummy impls on error (#248) * Fix changelog example (#250) * Do not call .verison() when CARGO_PKG_VERSION is not set * Update and improve docs * Propagate span info from origin code to generated code Most of `quote!` invocations are replaced with `quote_spanned!` ones. Now everywhere - sometimes it's pointless, sometimes we don't have any meaningless location to toke a span from, sometimes I just can't workaround the current implementation - too much changes. * Fix nightly tests * Do not mangle `author` string inside `<...>` * Support `skip = value` syntax * Fix code formatting * Fix nightly tests * Run ui tests only on stable * Add from_flag parser (#271) * Clarify docs and error messages (#277) * Fix parse for OptionVec (#279) ref pull #191 * Fix #269 and #265 (#278) * Pass the try_from_str functions a &str instead of a &String. (#282) In most cases this doesn't matter, as &String is coerced to a &str, but this fails for generic functions like CString::new. * Add an example of a negative flag (i.e. --no-verbose) Question from TeXitoi/structopt#280 * Fix #283 (#284) Fix #283 * Add `examples/README.md` and do some cleanup * Handle special types correctly * cargo clippy * Handle inter-expansion top-level args properly * Cleanup tests * Update proc-macro-error to v0.4 * Offer helpful suggestion on `raw(...)` error * Add `after_help` example * Prohibit positional `bool` args * Add tests/utils.rs * fixed typo, removed misleading doc * Remove CHANGELOG additions * Rust 2018 * Addressed review Co-authored-by: rnd <[email protected]> Co-authored-by: Robin Lambertz <[email protected]> Co-authored-by: florianjacob <[email protected]> Co-authored-by: Ted Driggs <[email protected]> Co-authored-by: Guillaume P. <[email protected]> Co-authored-by: Ivan Veselov <[email protected]> Co-authored-by: Owen Walpole <[email protected]> Co-authored-by: Robin Stocker <[email protected]> Co-authored-by: CreepySkeleton <[email protected]> Co-authored-by: Ophir LOJKINE <[email protected]> Co-authored-by: kpcyrd <[email protected]> Co-authored-by: Luiz F. A. de Prá <[email protected]> Co-authored-by: Andy Weiss <[email protected]> Co-authored-by: xiaoniu-578fa6bff964d005 <[email protected]> Co-authored-by: Mara Bos <[email protected]> Co-authored-by: Renê Couto e Silva <[email protected]>
clap-rs · Jan 7, 2020 · 0352bb3 · 0352bb3
1 parent 2622165
commit 0352bb3
Show file tree

Hide file tree

Showing 120 changed files with 4,046 additions and 897 deletions.
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,7 @@
 [package]
 name = "clap_derive"
 version = "0.3.0"
+edition = "2018"
 authors = [
     "Guillaume Pinot <[email protected]>",
     "Kevin K. <[email protected]>",
@@ -22,17 +23,20 @@ travis-ci = { repository = "clap-rs/clap_derive" }
 appveyor = { repository = "https://github.com/clap-rs/clap_derive", service = "github" }
 
 [dependencies]
-syn = "0.15.39"
-quote = "0.6"
-proc-macro2 = "0.4"
-clippy = {version = "0.0.174", optional = true }
+syn = { version = "1", features = ["full"] }
+quote = "1"
+proc-macro2 = "1"
+heck = "0.3.0"
+proc-macro-error = "0.4.3"
 
 [dev-dependencies]
 clap = { git = "https://github.com/clap-rs/clap", branch = "master"} # ONLY FOR INITIAL DEVELOPMENT...change to real crates.io ver for rlease!
+trybuild = "1.0.5"
+rustversion = "0.1"
 
 [features]
 default = []
 nightly = []
-lints = ["clippy"]
+lints = []
 debug = []
 doc = []
diff --git a/README.md b/README.md
@@ -34,30 +34,33 @@ use clap::Clap;
 #[clap(name = "basic")]
 struct Opt {
     // A flag, true if used in the command line. Note doc comment will
-    // be used for the help message of the flag.
+    // be used for the help message of the flag. The name of the
+    // argument will be, by default, based on the name of the field.
     /// Activate debug mode
-    #[clap(short = "d", long = "debug")]
+    #[clap(short, long)]
     debug: bool,
 
-    // The number of occurences of the `v/verbose` flag
+    // The number of occurrences of the `v/verbose` flag
     /// Verbose mode (-v, -vv, -vvv, etc.)
-    #[clap(short = "v", long = "verbose", parse(from_occurrences))]
+    #[clap(short, long, parse(from_occurrences))]
     verbose: u8,
 
     /// Set speed
-    #[clap(short = "s", long = "speed", default_value = "42")]
+    #[clap(short, long, default_value = "42")]
     speed: f64,
 
     /// Output file
-    #[clap(short = "o", long = "output", parse(from_os_str))]
+    #[clap(short, long, parse(from_os_str))]
     output: PathBuf,
 
+    // the long option will be translated by default to kebab case,
+    // i.e. `--nb-cars`.
     /// Number of cars
-    #[clap(short = "c", long = "nb-cars")]
+    #[clap(short = "c", long)]
     nb_cars: Option<i32>,
 
     /// admin_level to consider
-    #[clap(short = "l", long = "level")]
+    #[clap(short, long)]
     level: Vec<String>,
 
     /// Files to process
@@ -67,7 +70,7 @@ struct Opt {
 
 fn main() {
     let opt = Opt::parse();
-    println!("{:?}", opt);
+    println!("{:#?}", opt);
 }
 ```
 
@@ -82,12 +85,12 @@ USAGE:
 
 For more information try --help
 $ ./basic --help
-basic 0.2.0
-Guillaume Pinot <[email protected]>
+basic 0.3.0
+Guillaume Pinot <[email protected]>, others
 A basic example
 
 USAGE:
-    basic [FLAGS] [OPTIONS] --output <output> [--] [FILE]...
+    basic [FLAGS] [OPTIONS] --output <output> [--] [file]...
 
 ARGS:
     <FILE>...    Files to process
@@ -96,17 +99,44 @@ FLAGS:
     -d, --debug      Activate debug mode
     -h, --help       Prints help information
     -V, --version    Prints version information
-    -v, --verbose    Verbose mode
+    -v, --verbose    Verbose mode (-v, -vv, -vvv, etc.)
 
 OPTIONS:
-    -c, --nb-cars <nb_cars>   Number of cars
-    -l, --level <level>...    admin_level to consider
-    -o, --output <output>     Output file
-    -s, --speed <speed>       Set speed [default: 42]
+    -l, --level <level>...     admin_level to consider
+    -c, --nb-cars <nb-cars>    Number of cars
+    -o, --output <output>      Output file
+    -s, --speed <speed>        Set speed [default: 42]
+
+ARGS:
+    <file>...    Files to process
 $ ./basic -o foo.txt
-Opt { debug: false, verbose: 0, speed: 42, output: "foo.txt", car: None, level: [], files: [] }
+Opt {
+    debug: false,
+    verbose: 0,
+    speed: 42.0,
+    output: "foo.txt",
+    nb_cars: None,
+    level: [],
+    files: [],
+}
 $ ./basic -o foo.txt -dvvvs 1337 -l alice -l bob --nb-cars 4 bar.txt baz.txt
-Opt { debug: true, verbose: 3, speed: 1337, output: "foo.txt", nb_cars: Some(4), level: ["alice", "bob"], files: ["bar.txt", "baz.txt"] }
+Opt {
+    debug: true,
+    verbose: 3,
+    speed: 1337.0,
+    output: "foo.txt",
+    nb_cars: Some(
+        4,
+    ),
+    level: [
+        "alice",
+        "bob",
+    ],
+    files: [
+        "bar.txt",
+        "baz.txt",
+    ],
+}
 ```
 
 ## clap_derive rustc version policy

diff --git a/examples/README.md b/examples/README.md
@@ -0,0 +1,78 @@
+# Collection of examples "how to use `clap_derive`"
+
+### [Help on the bottom](after_help.rs)
+
+How to append a postscript to the help message generated.
+
+### [At least N](at_least_two.rs)
+
+How to require presence of at least N values, like `val1 val2 ... valN ... valM`.
+
+### [Basic](basic.rs)
+
+A basic example how to use `clap_derive`.
+
+### [Deny missing docs](deny_missing_docs.rs)
+
+**This is not an example but a test**, it should be moved to `tests` folder
+as soon as [this](https://github.com/rust-lang/rust/issues/24584) is fixed (if ever).
+
+### [Doc comments](doc_comments.rs)
+
+How to use doc comments in place of `help/long_help`.
+
+### [Enums as arguments](enum_in_args.rs)
+
+How to use `arg_enum!` with `clap_derive`.
+
+### [Arguments of subcommands in separate `struct`](enum_tuple.rs)
+
+How to extract subcommands' args into external structs.
+
+### [Environment variables](env.rs)
+
+How to use environment variable fallback an how it interacts with `default_value`.
+
+### [Advanced](example.rs)
+
+Somewhat complex example of usage of `clap_derive`.
+
+### [Flatten](flatten.rs)
+
+How to use `#[clap(flatten)]`
+
+### [Git](git.rs)
+
+Pseudo-`git` example, shows how to use subcommands and how to document them.
+
+### [Groups](group.rs)
+
+Using `clap::Arg::group` with `clap`.
+
+### [`key=value` pairs](keyvalue.rs)
+
+How to parse `key=value` pairs.
+
+### [`--no-*` flags](negative_flag.rs)
+
+How to add `no-thing` flag which is `true` by default and `false` if passed.
+
+### [No version](no_version.rs)
+
+How to completely remove version.
+
+### [Rename all](rename_all.rs)
+
+How `#[clap(rename_all)]` works.
+
+### [Skip](skip.rs)
+
+How to use `#[clap(skip)]`.
+
+### [Aliases](subcommand_aliases.rs)
+
+How to use aliases
+
+### [`true` or `false`](true_or_false.rs)
+
+How to express "`"true"` or `"false"` argument.
diff --git a/examples/after_help.rs b/examples/after_help.rs
@@ -0,0 +1,19 @@
+//! How to append a postscript to the help message generated.
+
+use clap::Clap;
+
+/// I am a program and I do things.
+///
+/// Sometimes they even work.
+#[derive(Clap, Debug)]
+#[clap(after_help = "Beware `-d`, dragons be here")]
+struct Opt {
+    /// Release the dragon.
+    #[clap(short)]
+    dragon: bool,
+}
+
+fn main() {
+    let opt = Opt::parse();
+    println!("{:?}", opt);
+}
diff --git a/examples/at_least_two.rs b/examples/at_least_two.rs
@@ -1,11 +1,11 @@
-#[macro_use]
-extern crate clap;
+//! How to require presence of at least N values,
+//! like `val1 val2 ... valN ... valM`.
 
 use clap::Clap;
 
 #[derive(Clap, Debug)]
 struct Opt {
-    #[clap(raw(required = "true", min_values = "2"))]
+    #[clap(required = true, min_values = 2)]
     foos: Vec<String>,
 }
 

diff --git a/examples/basic.rs b/examples/basic.rs
@@ -1,19 +1,4 @@
-// Copyright 2018 Guillaume Pinot (@TeXitoi) <[email protected]>,
-// Kevin Knapp (@kbknapp) <[email protected]>, and
-// Andrew Hobden (@hoverbear) <[email protected]>
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
-//
-// This work was derived from Structopt (https://github.com/TeXitoi/structopt)
-// commit#ea76fa1b1b273e65e3b0b1046643715b49bec51f which is licensed under the
-// MIT/Apache 2.0 license.
-
-#[macro_use]
-extern crate clap;
+//! A somewhat comprehensive example of a typical `StructOpt` usage.use
 
 use clap::Clap;
 use std::path::PathBuf;
@@ -23,30 +8,33 @@ use std::path::PathBuf;
 #[clap(name = "basic")]
 struct Opt {
     // A flag, true if used in the command line. Note doc comment will
-    // be used for the help message of the flag.
+    // be used for the help message of the flag. The name of the
+    // argument will be, by default, based on the name of the field.
     /// Activate debug mode
-    #[clap(short = "d", long = "debug")]
+    #[clap(short, long)]
     debug: bool,
 
-    // The number of occurences of the `v/verbose` flag
+    // The number of occurrences of the `v/verbose` flag
     /// Verbose mode (-v, -vv, -vvv, etc.)
-    #[clap(short = "v", long = "verbose", parse(from_occurrences))]
+    #[clap(short, long, parse(from_occurrences))]
     verbose: u8,
 
     /// Set speed
-    #[clap(short = "s", long = "speed", default_value = "42")]
+    #[clap(short, long, default_value = "42")]
     speed: f64,
 
     /// Output file
-    #[clap(short = "o", long = "output", parse(from_os_str))]
+    #[clap(short, long, parse(from_os_str))]
     output: PathBuf,
 
+    // the long option will be translated by default to kebab case,
+    // i.e. `--nb-cars`.
     /// Number of cars
-    #[clap(short = "c", long = "nb-cars")]
+    #[clap(short = "c", long)]
     nb_cars: Option<i32>,
 
     /// admin_level to consider
-    #[clap(short = "l", long = "level")]
+    #[clap(short, long)]
     level: Vec<String>,
 
     /// Files to process
@@ -56,5 +44,5 @@ struct Opt {
 
 fn main() {
     let opt = Opt::parse();
-    println!("{:?}", opt);
+    println!("{:#?}", opt);
 }
diff --git a/examples/deny_missing_docs.rs b/examples/deny_missing_docs.rs
@@ -16,15 +16,12 @@
 
 #![deny(missing_docs)]
 
-#[macro_use]
-extern crate clap;
-
 use clap::Clap;
 
 /// The options
 #[derive(Clap, Debug, PartialEq)]
 pub struct Opt {
-    #[clap(short = "v")]
+    #[clap(short)]
     verbose: bool,
     #[clap(subcommand)]
     cmd: Option<Cmd>,
@@ -38,7 +35,7 @@ pub enum Cmd {
     /// command B
     B {
         /// Alice?
-        #[clap(short = "a")]
+        #[clap(short)]
         alice: bool,
     },
     /// command C
@@ -48,7 +45,7 @@ pub enum Cmd {
 /// The options for C
 #[derive(Clap, Debug, PartialEq)]
 pub struct COpt {
-    #[clap(short = "b")]
+    #[clap(short)]
     bob: bool,
 }