1# v0.3.22 (2021-07-04) 2 3* Add support for [generics in derive](https://github.com/TeXitoi/structopt/issues/128) 4 5# v0.3.21 (2020-11-30) 6 7* Fixed [another breakage](https://github.com/TeXitoi/structopt/issues/447) 8 when the struct is placed inside a `macro_rules!` macro. 9 10# v0.3.20 (2020-10-12) 11 12* Fixed [a breakage](https://github.com/TeXitoi/structopt/issues/439) 13 when the struct is placed inside a `macro_rules!` macro. 14 15# v0.3.19 (2020-10-08) 16 17* Added [StructOpt::from_args_safe](https://docs.rs/structopt/0.3/structopt/trait.StructOpt.html#tymethod.from_args_safe) as a shortcut for `StructOpt::from_iter_safe(std::env::args_os())`. 18* Some links in documentation have been corrected. 19 20# v0.3.18 (2020-09-23) 21 22* Unsafe code [has been forbidden](https://github.com/TeXitoi/structopt/issues/432). This makes 23 [`cargo geiger`](https://github.com/rust-secure-code/cargo-geiger) list structopt as "safe". 24 Maybe it will help somebody trying to locate a bug in their dependency tree. 25 26# v0.3.17 (2020-08-25) 27 28* Fixed [a breakage](https://github.com/TeXitoi/structopt/issues/424) with resent rustc versions 29 due to `quote_spanned` misuse. 30 31# v0.3.16 (2020-08-05) 32 33* Added [the new example](https://github.com/TeXitoi/structopt/blob/master/examples/required_if.rs). 34* Allow `#[structopt(flatten)]` fields to have doc comments. The comments are ignored. 35* The `paw` crate is now being reexported when `paw` feature is enabled, 36 see [`#407`](https://github.com/TeXitoi/structopt/issues/407). 37 38# v0.3.15 (2020-06-16) 39 40* Minor documentation improvements. 41* Fixed [a latent bug](https://github.com/TeXitoi/structopt/pull/398), 42 courtesy of [@Aaron1011](https://github.com/Aaron1011). 43 44# v0.3.14 (2020-04-22) 45 46* Minor documentation improvements. 47 48# v0.3.13 (2020-04-9) 49 50* Bump `proc-macro-error` to `1.0`. 51 52# v0.3.12 (2020-03-18) 53 54* Fixed [bug in `external_subcommand`](https://github.com/TeXitoi/structopt/issues/359). 55 56# v0.3.11 (2020-03-01) 57 58* `syn`'s "full" feature is now explicitly enabled. It must have been, but hasn't. 59 60# v0.3.10 (2020-03-01) - YANKED 61 62* Fixed the breakage due to a required `syn` feature was not enabled. 63 64# v0.3.9 (2020-02-01) - YANKED 65 66* `clippy` warnings triggered by generated code shall not annoy you anymore! 67 Except for those from `clippy::correctness`, these lints are useful even 68 for auto generated code. 69* Improved error messages. 70 71# v0.3.8 (2020-1-19) - YANKED 72 73* You don't have to apply `#[no_version]` to every `enum` variant anymore. 74 Just annotate the `enum` and the setting will be propagated down 75 ([#242](https://github.com/TeXitoi/structopt/issues/242)). 76* [Auto-default](https://docs.rs/structopt/0.3/structopt/#default-values). 77* [External subcommands](https://docs.rs/structopt/0.3/structopt/#external-subcommands). 78* [Flattening subcommands](https://docs.rs/structopt/0.3.8/structopt/#flattening-subcommands). 79 80# v0.3.7 (2019-12-28) 81 82Nothing's new. Just re-release of `v0.3.6` due to 83[the mess with versioning](https://github.com/TeXitoi/structopt/issues/315#issuecomment-568502792). 84 85You may notice that `structopt-derive` was bumped to `v0.4.0`, that's OK, it's not a breaking change. 86`structopt` will pull the right version in on its on. 87 88# v0.3.6 (2019-12-22) - YANKED 89 90This is unusually big patch release. It contains a number of bugfixes and 91new features, some of them may theoretically be considered breaking. We did our best 92to avoid any problems on user's side but, if it wasn't good enough, please 93[file an issue ASAP](https://github.com/TeXitoi/structopt/issues). 94 95## Bugfixes 96 97* `structopt` used to treat `::path::to::type::Vec<T>` as `Vec<T>` 98 special type. [This was considered erroneous](https://github.com/TeXitoi/structopt/pull/287). 99 (same for `Option<T>` and `bool`). Now only exact `Vec<T>` match is a special type. 100 101* `#[structopt(version = expr)]` where `expr` is not a string literal used to get 102 overridden by auto generated `.version()` call, 103 [incorrectly](https://github.com/TeXitoi/structopt/issues/283). Now it doesn't. 104 105* Fixed bug with top-level `App::*` calls on multiple `struct`s, see 106 [#289](https://github.com/TeXitoi/structopt/issues/265). 107 108* Positional `bool` args with no explicit `#[structopt(parse(...))]` annotation are 109 now prohibited. This couldn't work well anyway, see 110 [this example](https://github.com/TeXitoi/structopt/blob/master/examples/true_or_false.rs) 111 for details. 112 113* Now we've instituted strict priority between doc comments, about, help, and the like. 114 See [the documentation](https://docs.rs/structopt/0.3/structopt/#help-messages). 115 116 **HUGE THANKS to [`@ssokolow`](https://github.com/ssokolow)** for tidying up our documentation, 117 teaching me English and explaining why our doc used to suck. I promise I'll make the rest 118 of the doc up to your standards... sometime later! 119 120## New features 121 122* Implement `StructOpt` for `Box<impl StructOpt>` so from now on you can use `Box<T>` 123 with `flatten` and `subcommand` ([#304](https://github.com/TeXitoi/structopt/issues/304)). 124 125 ```rust 126 enum Command { 127 #[structopt(name = "version")] 128 PrintVersion, 129 130 #[structopt(name = "second")] 131 DoSomething { 132 #[structopt(flatten)] 133 config: Box<DoSomethingConfig>, 134 }, 135 136 #[structopt(name = "first")] 137 DoSomethingElse { 138 #[structopt(flatten)] 139 config: Box<DoSomethingElseConfig>, 140 } 141 } 142 ``` 143 144* Introduced `#[structopt(verbatim_doc_comment)]` attribute that keeps line breaks in 145 doc comments, see 146 [the documentation](https://docs.rs/structopt/0.3/structopt/#doc-comment-preprocessing-and-structoptverbatim_doc_comment). 147 148* Introduced `#[structopt(rename_all_env)]` and `#[structopt(env)]` magical methods 149 so you can derive env var's name from field's name. See 150 [the documentation](https://docs.rs/structopt/0.3/structopt/#auto-deriving-environment-variables). 151 152## Improvements 153 154* Now we have nice README for our examples, 155 [check it out](https://github.com/TeXitoi/structopt/tree/master/examples)! 156 157* Some error messages were improved and clarified, thanks for all people involved! 158 159 160# v0.3.5 (2019-11-22) 161 162* `try_from_str` functions are now called with a `&str` instead of a `&String` ([#282](https://github.com/TeXitoi/structopt/pull/282)) 163 164# v0.3.4 (2019-11-08) 165 166* `rename_all` does not apply to fields that were annotated with explicit 167 `short/long/name = "..."` anymore ([#265](https://github.com/TeXitoi/structopt/issues/265)) 168* Now raw idents are handled correctly ([#269](https://github.com/TeXitoi/structopt/issues/269)) 169* Some documentation improvements and clarification. 170 171# v0.3.3 (2019-10-10) 172 173* Add `from_flag` custom parser to create flags from non-bool types. 174 Fixes [#185](https://github.com/TeXitoi/structopt/issues/185) 175 176# v0.3.2 (2019-09-18) 177 178* `structopt` does not replace `:` with `, ` inside "author" strings while inside `<...>`. 179 Fixes [#156](https://github.com/TeXitoi/structopt/issues/156) 180* Introduced [`#[structopt(skip = expr)]` syntax](https://docs.rs/structopt/0.3.2/structopt/#skipping-fields). 181 182# v0.3.1 (2019-09-06) 183 184* Fix error messages ([#241](https://github.com/TeXitoi/structopt/issues/241)) 185* Fix "`skip` plus long doc comment" bug ([#245](https://github.com/TeXitoi/structopt/issues/245)) 186* Now `structopt` emits dummy `StructOpt` implementation along with an error. It suppresses 187 meaningless errors like `from_args method is not found for Opt` 188* `.version()` not get generated if `CARGO_PKG_VERSION` is not set anymore. 189 190# v0.3.0 (2019-08-30) 191 192## Breaking changes 193 194### Bump minimum rustc version to 1.36 by [@TeXitoi](https://github.com/TeXitoi) 195Now `rustc` 1.36 is the minimum compiler version supported by `structopt`, 196it likely won't work with older compilers. 197 198### Remove "nightly" feature 199Once upon a time this feature had been used to enable some of improvements 200in `proc-macro2` crate that were available only on nightly. Nowadays this feature doesn't 201mean anything so it's now removed. 202 203### 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)). 204 205```rust 206#[derive(StructOpt)] 207struct Opt { 208 #[structopt(long)] 209 fruit: Option<Vec<String>>, 210} 211 212fn main() { 213 assert_eq!(Opt::from_args(&["test"]), None); 214 assert_eq!(Opt::from_args(&["test", "--fruit"]), Some(vec![])); 215 assert_eq!(Opt::from_args(&["test", "--fruit=apple orange"]), Some(vec!["apple", "orange"])); 216} 217``` 218 219If you need to fall back to the old behavior you can use a type alias: 220```rust 221type Something = Vec<String>; 222 223#[derive(StructOpt)] 224struct Opt { 225 #[structopt(long)] 226 fruit: Option<Something>, 227} 228``` 229 230### Change default case from 'Verbatim' into 'Kebab' by [@0ndorio](https://github.com/0ndorio) ([#202](https://github.com/TeXitoi/structopt/issues/202)). 231`structopt` 0.3 uses field renaming to deduce a name for long options and subcommands. 232 233```rust 234#[derive(StructOpt)] 235struct Opt { 236 #[structopt(long)] 237 http_addr: String, // will be renamed to `--http-addr` 238 239 #[structopt(subcommand)] 240 addr_type: AddrType // this adds `addr-type` subcommand 241} 242``` 243 244`structopt` 0.2 used to leave things "as is", not renaming anything. If you want to keep old 245behavior add `#[structopt(rename_all = "verbatim")]` on top of a `struct`/`enum`. 246 247### Change `version`, `author` and `about` attributes behavior. 248Proposed 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). 249 250`structopt` have been deducing `version`, `author`, and `about` properties from `Cargo.toml` 251for a long time (more accurately, from `CARGO_PKG_...` environment variables). 252But many users found this behavior somewhat confusing, and a hack was added to cancel out 253this behavior: `#[structopt(author = "")]`. 254 255In `structopt` 0.3 this has changed. 256* `author` and `about` are no longer deduced by default. You should use `#[structopt(author, about)]` 257 to explicitly request `structopt` to deduce them. 258* Contrary, `version` **is still deduced by default**. You can use `#[structopt(no_version)]` to 259 cancel it out. 260* `#[structopt(author = "", about = "", version = "")]` is no longer a valid syntax 261 and will trigger an error. 262* `#[structopt(version = "version", author = "author", about = "about")]` syntax 263 stays unaffected by this changes. 264 265### Raw attributes are removed ([#198](https://github.com/TeXitoi/structopt/pull/198)) by [@sphynx](https://github.com/sphynx) 266In `structopt` 0.2 you were able to use any method from `clap::App` and `clap::Arg` via 267raw attribute: `#[structopt(raw(method_name = "arg"))]`. This syntax was kind of awkward. 268 269```rust 270#[derive(StructOpt, Debug)] 271#[structopt(raw( 272 global_settings = "&[AppSettings::ColoredHelp, AppSettings::VersionlessSubcommands]" 273))] 274struct Opt { 275 #[structopt(short = "l", long = "level", raw(aliases = r#"&["set-level", "lvl"]"#))] 276 level: Vec<String>, 277} 278``` 279 280Raw attributes were removed in 0.3. Now you can use any method from `App` and `Arg` *directly*: 281```rust 282#[derive(StructOpt)] 283#[structopt(global_settings(&[AppSettings::ColoredHelp, AppSettings::VersionlessSubcommands]))] 284struct Opt { 285 #[structopt(short = "l", long = "level", aliases(&["set-level", "lvl"]))] 286 level: Vec<String>, 287} 288``` 289 290## Improvements 291 292### Support skipping struct fields 293Proposed by [@Morganamilo](https://github.com/Morganamilo) in ([#174](https://github.com/TeXitoi/structopt/issues/174)) 294implemented by [@sphynx](https://github.com/sphynx) in ([#213](https://github.com/TeXitoi/structopt/issues/213)). 295 296Sometimes you want to include some fields in your `StructOpt` `struct` that are not options 297and `clap` should know nothing about them. In `structopt` 0.3 it's possible via the 298`#[structopt(skip)]` attribute. The field in question will be assigned with `Default::default()` 299value. 300 301```rust 302#[derive(StructOpt)] 303struct Opt { 304 #[structopt(short, long)] 305 speed: f32, 306 307 car: String, 308 309 // this field should not generate any arguments 310 #[structopt(skip)] 311 meta: Vec<u64> 312} 313``` 314 315### Add optional feature to support `paw` by [@gameldar](https://github.com/gameldar) ([#187](https://github.com/TeXitoi/structopt/issues/187)) 316 317### Significantly improve error reporting by [@CreepySkeleton](https://github.com/CreepySkeleton) ([#225](https://github.com/TeXitoi/structopt/pull/225/)) 318Now (almost) every error message points to the location it originates from: 319 320```text 321error: default_value is meaningless for bool 322 --> $DIR/bool_default_value.rs:14:24 323 | 32414 | #[structopt(short, default_value = true)] 325 | ^^^^^^^^^^^^^ 326``` 327 328# v0.2.16 (2019-05-29) 329 330### Support optional options with optional argument, allowing `cmd [--opt[=value]]` by [@sphynx](https://github.com/sphynx) ([#188](https://github.com/TeXitoi/structopt/issues/188)) 331Sometimes you want to represent an optional option that optionally takes an argument, 332i.e `[--opt[=value]]`. This is represented by `Option<Option<T>>` 333 334```rust 335#[derive(StructOpt)] 336struct Opt { 337 #[structopt(long)] 338 fruit: Option<Option<String>>, 339} 340 341fn main() { 342 assert_eq!(Opt::from_args(&["test"]), None); 343 assert_eq!(Opt::from_args(&["test", "--fruit"]), Some(None)); 344 assert_eq!(Opt::from_args(&["test", "--fruit=apple"]), Some("apple")); 345} 346``` 347 348# v0.2.15 (2019-03-08) 349 350* Fix [#168](https://github.com/TeXitoi/structopt/issues/168) by [@TeXitoi](https://github.com/TeXitoi) 351 352# v0.2.14 (2018-12-10) 353 354* Introduce smarter parsing of doc comments by [@0ndorio](https://github.com/0ndorio) 355 356# v0.2.13 (2018-11-01) 357 358* Automatic naming of fields and subcommands by [@0ndorio](https://github.com/0ndorio) 359 360# v0.2.12 (2018-10-11) 361 362* Fix minimal clap version by [@TeXitoi](https://github.com/TeXitoi) 363 364# v0.2.11 (2018-10-05) 365 366* Upgrade syn to 0.15 by [@konstin](https://github.com/konstin) 367 368# v0.2.10 (2018-06-07) 369 370* 1.21.0 is the minimum required rustc version by 371 [@TeXitoi](https://github.com/TeXitoi) 372 373# v0.2.9 (2018-06-05) 374 375* Fix a bug when using `flatten` by 376 [@fbenkstein](https://github.com/fbenkstein) 377* Update syn, quote and proc_macro2 by 378 [@TeXitoi](https://github.com/TeXitoi) 379* Fix a regression when there is multiple authors by 380 [@windwardly](https://github.com/windwardly) 381 382# v0.2.8 (2018-04-28) 383 384* Add `StructOpt::from_iter_safe()`, which returns an `Error` instead of 385 killing the program when it fails to parse, or parses one of the 386 short-circuiting flags. ([#98](https://github.com/TeXitoi/structopt/pull/98) 387 by [@quodlibetor](https://github.com/quodlibetor)) 388* Allow users to enable `clap` features independently by 389 [@Kerollmops](https://github.com/Kerollmops) 390* Fix a bug when flattening an enum 391 ([#103](https://github.com/TeXitoi/structopt/pull/103) by 392 [@TeXitoi](https://github.com/TeXitoi) 393 394# v0.2.7 (2018-04-12) 395 396* Add flattening, the insertion of options of another StructOpt struct 397 into another ([#92](https://github.com/TeXitoi/structopt/pull/92)) 398 by [@birkenfeld](https://github.com/birkenfeld) 399* Fail compilation when using `default_value` or `required` with 400 `Option` ([#88](https://github.com/TeXitoi/structopt/pull/88)) by 401 [@Kerollmops](https://github.com/Kerollmops) 402 403# v0.2.6 (2018-03-31) 404 405* Fail compilation when using `default_value` or `required` with `bool` ([#80](https://github.com/TeXitoi/structopt/issues/80)) by [@TeXitoi](https://github.com/TeXitoi) 406* Fix compilation with `#[deny(warnings)]` with the `!` type (https://github.com/rust-lang/rust/pull/49039#issuecomment-376398999) by [@TeXitoi](https://github.com/TeXitoi) 407* Improve first example in the documentation ([#82](https://github.com/TeXitoi/structopt/issues/82)) by [@TeXitoi](https://github.com/TeXitoi) 408 409# v0.2.5 (2018-03-07) 410 411* Work around breakage when `proc-macro2`'s nightly feature is enabled. ([#77](https://github.com/Texitoi/structopt/pull/77) and [proc-macro2#67](https://github.com/alexcrichton/proc-macro2/issues/67)) by [@fitzgen](https://github.com/fitzgen) 412 413# v0.2.4 (2018-02-25) 414 415* Fix compilation with `#![deny(missig_docs]` ([#74](https://github.com/TeXitoi/structopt/issues/74)) by [@TeXitoi](https://github.com/TeXitoi) 416* Fix [#76](https://github.com/TeXitoi/structopt/issues/76) by [@TeXitoi](https://github.com/TeXitoi) 417* Re-licensed to Apache-2.0/MIT by [@CAD97](https://github.com/cad97) 418 419# v0.2.3 (2018-02-16) 420 421* An empty line in a doc comment will result in a double linefeed in the generated about/help call by [@TeXitoi](https://github.com/TeXitoi) 422 423# v0.2.2 (2018-02-12) 424 425* Fix [#66](https://github.com/TeXitoi/structopt/issues/66) by [@TeXitoi](https://github.com/TeXitoi) 426 427# v0.2.1 (2018-02-11) 428 429* Fix a bug around enum tuple and the about message in the global help by [@TeXitoi](https://github.com/TeXitoi) 430* Fix [#65](https://github.com/TeXitoi/structopt/issues/65) by [@TeXitoi](https://github.com/TeXitoi) 431 432# v0.2.0 (2018-02-10) 433 434## Breaking changes 435 436### Don't special case `u64` by [@SergioBenitez](https://github.com/SergioBenitez) 437 438If you are using a `u64` in your struct to get the number of occurence of a flag, you should now add `parse(from_occurrences)` on the flag. 439 440For example 441```rust 442#[structopt(short = "v", long = "verbose")] 443verbose: u64, 444``` 445must be changed by 446```rust 447#[structopt(short = "v", long = "verbose", parse(from_occurrences))] 448verbose: u64, 449``` 450 451This feature was surprising as shown in [#30](https://github.com/TeXitoi/structopt/issues/30). Using the `parse` feature seems much more natural. 452 453### Change the signature of `Structopt::from_clap` to take its argument by reference by [@TeXitoi](https://github.com/TeXitoi) 454 455There was no reason to take the argument by value. Most of the StructOpt users will not be impacted by this change. If you are using `StructOpt::from_clap`, just add a `&` before the argument. 456 457### Fail if attributes are not used by [@TeXitoi](https://github.com/TeXitoi) 458 459StructOpt was quite fuzzy in its attribute parsing: it was only searching for interresting things, e. g. something like `#[structopt(foo(bar))]` was accepted but not used. It now fails the compilation. 460 461You should have nothing to do here. This breaking change may highlight some missuse that can be bugs. 462 463In future versions, if there is cases that are not highlighed, they will be considerated as bugs, not breaking changes. 464 465### Use `raw()` wrapping instead of `_raw` suffixing by [@TeXitoi](https://github.com/TeXitoi) 466 467The syntax of raw attributes is changed to improve the syntax. 468 469You have to change `foo_raw = "bar", baz_raw = "foo"` by `raw(foo = "bar", baz = "foo")` or `raw(foo = "bar"), raw(baz = "foo")`. 470 471## New features 472 473* Add `parse(from_occurrences)` parser by [@SergioBenitez](https://github.com/SergioBenitez) 474* Support 1-uple enum variant as subcommand by [@TeXitoi](https://github.com/TeXitoi) 475* structopt-derive crate is now an implementation detail, structopt reexport the custom derive macro by [@TeXitoi](https://github.com/TeXitoi) 476* Add the `StructOpt::from_iter` method by [@Kerollmops](https://github.com/Kerollmops) 477 478## Documentation 479 480* Improve doc by [@bestouff](https://github.com/bestouff) 481* All the documentation is now on the structopt crate by [@TeXitoi](https://github.com/TeXitoi) 482 483# v0.1.7 (2018-01-23) 484 485* Allow opting out of clap default features by [@ski-csis](https://github.com/ski-csis) 486 487# v0.1.6 (2017-11-25) 488 489* Improve documentation by [@TeXitoi](https://github.com/TeXitoi) 490* Fix bug [#31](https://github.com/TeXitoi/structopt/issues/31) by [@TeXitoi](https://github.com/TeXitoi) 491 492# v0.1.5 (2017-11-14) 493 494* Fix a bug with optional subsubcommand and Enum by [@TeXitoi](https://github.com/TeXitoi) 495 496# v0.1.4 (2017-11-09) 497 498* Implement custom string parser from either `&str` or `&OsStr` by [@kennytm](https://github.com/kennytm) 499 500# v0.1.3 (2017-11-01) 501 502* Improve doc by [@TeXitoi](https://github.com/TeXitoi) 503 504# v0.1.2 (2017-11-01) 505 506* Fix bugs [#24](https://github.com/TeXitoi/structopt/issues/24) and [#25](https://github.com/TeXitoi/structopt/issues/25) by [@TeXitoi](https://github.com/TeXitoi) 507* Support of methods with something else that a string as argument thanks to `_raw` suffix by [@Flakebi](https://github.com/Flakebi) 508 509# v0.1.1 (2017-09-22) 510 511* Better formating of multiple authors by [@killercup](https://github.com/killercup) 512 513# v0.1.0 (2017-07-17) 514 515* Subcommand support by [@williamyaoh](https://github.com/williamyaoh) 516 517# v0.0.5 (2017-06-16) 518 519* Using doc comment to populate help by [@killercup](https://github.com/killercup) 520 521# v0.0.3 (2017-02-11) 522 523* First version with flags, arguments and options support by [@TeXitoi](https://github.com/TeXitoi) 524