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