Update and improve documentation

CHANGELOG.md

@@ -2,45 +2,159 @@
 
 ## Breaking changes
 
-* Bump minimum rust version to 1.34 by [@TeXitoi](https://github.com/TeXitoi)
+### Bump minimum rustc version to 1.34 by [@TeXitoi](https://github.com/TeXitoi)
+Now `rustc` 1.34 is the minimum compiler version supported by `structopt`,
+it likely won't work with older compilers.
 
-* Support optional vectors of arguments for distinguishing between `-o 1 2`, `-o` and no option provided at all
- by [@sphynx](https://github.com/sphynx)
- ([#180](https://github.com/TeXitoi/structopt/issues/188)). This is a breaking change
- as `Option<Vec<T>>` is handled differently. If you need to have a `Option<Vec<T>>`
- handled the old was, you can `type Something = Vec<T>;` and then use `Option<Something>`
- as your structopt field.
+### Remove "nightly" feature
+Once upon a time this feature had been used to enable some of improvements
+in `proc-macro2` crate that were available only on nightly. Nowadays this feature doesn't
+mean anything so it's now removed.
 
-* Change default case from 'Verbatim' into 'Kebab' by [@0ndorio](https://github.com/0ndorio)
- ([#202](https://github.com/TeXitoi/structopt/issues/202)). This is a breaking change.
- If you rely on the old behavior you need to add `#[structopt(rename_all = "verbatim")]`
- as an attribute to each data structure deriving the `StructOpt` trait.
+### Support optional vectors of arguments for distinguishing between `-o 1 2`, `-o` and no option provided at all by [@sphynx](https://github.com/sphynx) ([#180](https://github.com/TeXitoi/structopt/issues/188)).
 
-* Change `version`, `author` and `about` attributes behavior. `version/author/about = ""` is no longer a
- valid syntax. `author` and `about` are no longer derived from `Cargo.toml` by default, i.e when no
- attributes mentioned. `version` is still to be derived from `Cargo.toml` by default.
- Introduced explicit `author` and `about` attributes (with no arguments, i.e `#[structopt(author)]`)
- for explicit requests to deduce author/about fields from `Cargo.toml`.
- `version/author/about = "version/author/about"` is still valid syntax.
- Introduced `no_version` attribute (no args) which prevents version auto deducing by default.
- Proposed by [@TeXitoi](https://github.com/TeXitoi) [(#217)](https://github.com/TeXitoi/structopt/issues/217), implemented by [@CreepySkeleton](https://github.com/CreepySkeleton) [(#229)](https://github.com/TeXitoi/structopt/pull/229).
+```rust
+#[derive(StructOpt)]
+struct Opt {
+ #[structopt(long)]
+ fruit: Option<Vec<String>>,
+}
+
+fn main() {
+ assert_eq!(Opt::from_args(&["test"]), None);
+ assert_eq!(Opt::from_args(&["test", "--fruit"]), Some(vec![]));
+ assert_eq!(Opt::from_args(&["test", "--fruit=apple orange"]), Some(vec!["apple", "orange"]));
+}
+```
+
+If you need to fall back to the old behavior you can use a type alias:
+```rust
+type Something = Vec<String>;
+
+#[derive(StructOpt)]
+struct Opt {
+ #[structopt(long)]
+ fruit: Option<Vec<String>>,
+}
+```
+
+### Change default case from 'Verbatim' into 'Kebab' by [@0ndorio](https://github.com/0ndorio) ([#202](https://github.com/TeXitoi/structopt/issues/202)).
+`structopt` 0.3 uses field renaming to deduce a name for long options and subcommands.
+
+```rust
+#[derive(StructOpt)]
+struct Opt {
+ #[structopt(long)]
+ http_addr: String, // will be renamed to `--http-addr`
+
+ #[structopt(subcommand)]
+ addr_type: AddrType // this adds `addr-type` subcommand
+}
+```
+
+`structopt` 0.2 used to leave things "as is", not renaming anything. If you want to keep old
+behavior add `#[structopt(rename_all = "verbatim")]` on top of a `struct`/`enum`.
+
+### Change `version`, `author` and `about` attributes behavior.
+Proposed by [@TeXitoi](https://github.com/TeXitoi) [(#217)](https://github.com/TeXitoi/structopt/issues/217), implemented by [@CreepySkeleton](https://github.com/CreepySkeleton) [(#229)](https://github.com/TeXitoi/structopt/pull/229).
+
+`structopt` have been deducing `version`, `author`, and `about` properties from `Cargo.toml`
+for a long time (more accurately, from `CARGO_PKG_...` environment variables).
+But many users found this behavior somewhat confusing, and a hack was added to cancel out
+this behavior: `#[structopt(author = "")]`.
+
+In `structopt` 0.3 this has changed.
+* `author` and `about` are no longer deduced by default. You should use `#[structopt(author, about)]`
+ to explicitly request `structopt` to deduce them.
+* Contrary, `version` **is still deduced by default**. You can use `#[structopt(no_version)]` to
+ cancel it out.
+* `#[structopt(author = "", about = "", version = "")]` is no longer a valid syntax
+ and will trigger an error.
+* `#[structopt(version = "version", author = "author", about = "about")]` syntax
+ stays unaffected by this changes.
+
+### Raw attributes are removed ([#198](https://github.com/TeXitoi/structopt/pull/198)) by [@sphynx](https://github.com/sphynx)
+In `structopt` 0.2 you were able to use any method from `clap::App` and `clap::Arg` via
+raw attribute: `#[structopt(raw(method_name = "arg"))]`. This syntax was kind of awkward.
+
+```rust
+#[derive(StructOpt, Debug)]
+#[structopt(raw(
+ global_settings = "&[AppSettings::ColoredHelp, AppSettings::VersionlessSubcommands]"
+))]
+struct Opt {
+ #[structopt(short = "l", long = "level", raw(aliases = r#"&["set-level", "lvl"]"#))]
+ level: Vec<String>,
+}
+```
+
+Raw attributes were removed in 0.3. Now you can use any method from `App` and `Arg` *directly*:
+```rust
+#[derive(StructOpt)]
+#[structopt(global_settings(&[AppSettings::ColoredHelp, AppSettings::VersionlessSubcommands]))]
+struct Opt {
+ #[structopt(short = "l", long = "level", aliases(&["set-level", "lvl"]))]
+ level: Vec<String>,
+}
+```
+
+## Improvements
+
+### Support skipping struct fields
+Proposed by [@Morganamilo](https://github.com/Morganamilo) in ([#174](https://github.com/TeXitoi/structopt/issues/174))
+implemented by [@sphynx](https://github.com/sphynx) in ([#213](https://github.com/TeXitoi/structopt/issues/213)).
+
+Sometimes you want to include some fields in your `StructOpt` `struct` that are not options
+and `clap` should know nothing about them. In `structopt` 0.3 it's possible via the
+`#[structopt(skip)]` attribute. The field in question will be assigned with `Default::default()`
+value.
 
-## improvements
+```rust
+#[derive(StructOpt)]
+struct Opt {
+ #[structopt(short, long)]
+ speed: f32,
+
+ car: String,
+
+ // this field should not generate any arguments
+ #[structopt(skip)]
+ meta: Vec<u64>
+}
+```
 
-* Support skipping struct fields by [@sphynx](https://github.com/sphynx)
- ([#174](https://github.com/TeXitoi/structopt/issues/174))
+### Add optional feature to support `paw` by [@gameldar](https://github.com/gameldar) ([#187](https://github.com/TeXitoi/structopt/issues/187))
 
-* Add optional feature to support `paw` by [@gameldar](https://github.com/gameldar)
- ([#187](https://github.com/TeXitoi/structopt/issues/187))
+### Significantly improve error reporting by [@CreepySkeleton](https://github.com/CreepySkeleton) ([#225](https://github.com/TeXitoi/structopt/pull/225/))
+Now (almost) every error message points to the location it originates from:
 
-* Significantly improve error reporting by [@CreepySkeleton](https://github.com/CreepySkeleton)
- ([#225](https://github.com/TeXitoi/structopt/pull/225/))
+```text
+error: default_value is meaningless for bool
+ --> $DIR/bool_default_value.rs:14:24
+ |
+14 | #[structopt(short, default_value = true)]
+ | ^^^^^^^^^^^^^
+```
 
 # v0.2.16 (2019-05-29)
 
-* Support optional options with optional argument, allowing `cmd [--opt[=value]]`
- by [@sphynx](https://github.com/sphynx)
- ([#188](https://github.com/TeXitoi/structopt/issues/188))
+### Support optional options with optional argument, allowing `cmd [--opt[=value]]` by [@sphynx](https://github.com/sphynx) ([#188](https://github.com/TeXitoi/structopt/issues/188))
+Sometimes you want to represent an optional option that optionally takes an argument,
+i.e `[--opt[=value]]`. This is represented by `Option<Option<T>>`
+
+```rust
+#[derive(StructOpt)]
+struct Opt {
+ #[structopt(long)]
+ fruit: Option<Option<String>>,
+}
+
+fn main() {
+ assert_eq!(Opt::from_args(&["test"]), None);
+ assert_eq!(Opt::from_args(&["test", "--fruit"]), Some(None));
+ assert_eq!(Opt::from_args(&["test", "--fruit=apple"]), Some("apple"));
+}
+```
 
 # v0.2.15 (2019-03-08)
 

examples/skip.rs

@@ -0,0 +1,36 @@
+use structopt::StructOpt;
+
+#[derive(StructOpt, Debug, PartialEq)]
+#[structopt(name = "a")]
+pub struct Opt {
+ #[structopt(long, short)]
+ number: u32,
+ #[structopt(skip)]
+ k: Kind,
+ #[structopt(skip)]
+ v: Vec<u32>,
+}
+
+#[derive(Debug, PartialEq)]
+#[allow(unused)]
+enum Kind {
+ A,
+ B,
+}
+
+impl Default for Kind {
+ fn default() -> Self {
+ return Kind::B;
+ }
+}
+
+fn main() {
+ assert_eq!(
+ Opt::from_iter(&["test", "-n", "10"]),
+ Opt {
+ number: 10,
+ k: Kind::B,
+ v: vec![],
+ }
+ );
+}