structopt

• Fix duplication of aliases in subcommands #504

• Update minimal rust version to 1.46 because of bitflags 1.3
• Fixed a bug that occurs when the type of map becomes ambiguous.
• Add support for skip for enum variant subcommands

• Add support for generics in derive

• Fixed another breakage when the struct is placed inside a macro_rules! macro.

• Fixed a breakage when the struct is placed inside a macro_rules! macro.

• Added StructOpt::from_args_safe as a shortcut for StructOpt::from_iter_safe(std::env::args_os()).
• Some links in documentation have been corrected.

• Unsafe code has been forbidden. This makes cargo geiger list structopt as "safe". Maybe it will help somebody trying to locate a bug in their dependency tree.

• Fixed a breakage with resent rustc versions due to quote_spanned misuse.

• Added the new example.
• Allow #[structopt(flatten)] fields to have doc comments. The comments are ignored.
• The paw crate is now being reexported when paw feature is enabled, see #407.

• Minor documentation improvements.
• Fixed a latent bug, courtesy of @Aaron1011.

• Minor documentation improvements.

• Bump proc-macro-error to 1.0.

• Fixed bug in external_subcommand.

• syn's "full" feature is now explicitly enabled. It must have been, but hasn't.

• Fixed the breakage due to a required syn feature was not enabled.

• clippy warnings triggered by generated code shall not annoy you anymore! Except for those from clippy::correctness, these lints are useful even for auto generated code.
• Improved error messages.

• You don't have to apply #[no_version] to every enum variant anymore. Just annotate the enum and the setting will be propagated down (#242).
• Auto-default.
• External subcommands.
• Flattening subcommands.

Nothing's new. Just re-release of v0.3.6 due to the mess with versioning.

You may notice that structopt-derive was bumped to v0.4.0, that's OK, it's not a breaking change. structopt will pull the right version in on its on.

This is unusually big patch release. It contains a number of bugfixes and new features, some of them may theoretically be considered breaking. We did our best to avoid any problems on user's side but, if it wasn't good enough, please file an issue ASAP.

Bugfixes

• structopt used to treat ::path::to::type::Vec<T> as Vec<T> special type. This was considered erroneous. (same for Option<T> and bool). Now only exact Vec<T> match is a special type.

• #[structopt(version = expr)] where expr is not a string literal used to get overridden by auto generated .version() call, incorrectly. Now it doesn't.

• Fixed bug with top-level App::* calls on multiple structs, see #289.

• Positional bool args with no explicit #[structopt(parse(...))] annotation are now prohibited. This couldn't work well anyway, see this example for details.

• Now we've instituted strict priority between doc comments, about, help, and the like. See the documentation.

  HUGE THANKS to @ssokolow for tidying up our documentation, teaching me English and explaining why our doc used to suck. I promise I'll make the rest of the doc up to your standards... sometime later!

New features

• Implement StructOpt for Box<impl StructOpt> so from now on you can use Box<T> with flatten and subcommand (#304).

  enum Command {
      #[structopt(name = "version")]
      PrintVersion,
  
      #[structopt(name = "second")]
      DoSomething {
          #[structopt(flatten)]
          config: Box<DoSomethingConfig>,
      },
  
      #[structopt(name = "first")]
      DoSomethingElse {
          #[structopt(flatten)]
          config: Box<DoSomethingElseConfig>,
      }
  }
  

• Introduced #[structopt(verbatim_doc_comment)] attribute that keeps line breaks in doc comments, see the documentation.

• Introduced #[structopt(rename_all_env)] and #[structopt(env)] magical methods so you can derive env var's name from field's name. See the documentation.

Improvements

• Now we have nice README for our examples, check it out!

• Some error messages were improved and clarified, thanks for all people involved!

• try_from_str functions are now called with a &str instead of a &String (#282)

• rename_all does not apply to fields that were annotated with explicit short/long/name = "..." anymore (#265)
• Now raw idents are handled correctly (#269)
• Some documentation improvements and clarification.

• Add from_flag custom parser to create flags from non-bool types. Fixes #185

• structopt does not replace : with , inside "author" strings while inside <...>. Fixes #156
• Introduced #[structopt(skip = expr)] syntax.

• Fix error messages (#241)
• Fix "skip plus long doc comment" bug (#245)
• Now structopt emits dummy StructOpt implementation along with an error. It suppresses meaningless errors like from_args method is not found for Opt
• .version() not get generated if CARGO_PKG_VERSION is not set anymore.

Breaking changes

Bump minimum rustc version to 1.36 by @TeXitoi

Now rustc 1.36 is the minimum compiler version supported by structopt, it likely won't work with older compilers.

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.

Support optional vectors of arguments for distinguishing between -o 1 2, -o and no option provided at all by @sphynx (#180).

#[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:

type Something = Vec<String>;

#[derive(StructOpt)]
struct Opt {
  #[structopt(long)]
  fruit: Option<Something>,
}

Change default case from 'Verbatim' into 'Kebab' by @0ndorio (#202).

structopt 0.3 uses field renaming to deduce a name for long options and subcommands.

#[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 (#217), implemented by @CreepySkeleton (#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) by @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.

#[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:

#[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 in (#174) implemented by @sphynx in (#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.

#[derive(StructOpt)]
struct Opt {
    #[structopt(short, long)]
    speed: f32,

    car: String,

    // this field should not generate any arguments
    #[structopt(skip)]
    meta: Vec<u64>
}

Add optional feature to support paw by @gameldar (#187)

Significantly improve error reporting by @CreepySkeleton (#225)

Now (almost) every error message points to the location it originates from:

error: default_value is meaningless for bool
  --> $DIR/bool_default_value.rs:14:24
   |
14 |     #[structopt(short, default_value = true)]
   |                        ^^^^^^^^^^^^^

Support optional options with optional argument, allowing cmd [--opt[=value]] by @sphynx (#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>>

#[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"));
}

• Fix #168 by @TeXitoi

• Introduce smarter parsing of doc comments by @0ndorio

• Automatic naming of fields and subcommands by @0ndorio

• Fix minimal clap version by @TeXitoi

• Upgrade syn to 0.15 by @konstin

• 1.21.0 is the minimum required rustc version by @TeXitoi

• Fix a bug when using flatten by @fbenkstein
• Update syn, quote and proc_macro2 by @TeXitoi
• Fix a regression when there is multiple authors by @windwardly

• Add StructOpt::from_iter_safe(), which returns an Error instead of killing the program when it fails to parse, or parses one of the short-circuiting flags. (#98 by @quodlibetor)
• Allow users to enable clap features independently by @Kerollmops
• Fix a bug when flattening an enum (#103 by @TeXitoi

• Add flattening, the insertion of options of another StructOpt struct into another (#92) by @birkenfeld
• Fail compilation when using default_value or required with Option (#88) by @Kerollmops

• Fail compilation when using default_value or required with bool (#80) by @TeXitoi
• Fix compilation with #[deny(warnings)] with the ! type (https://github.com/rust-lang/rust/pull/49039#issuecomment-376398999) by @TeXitoi
• Improve first example in the documentation (#82) by @TeXitoi

• Work around breakage when proc-macro2's nightly feature is enabled. (#77 and proc-macro2#67) by @fitzgen

• Fix compilation with #![deny(missig_docs] (#74) by @TeXitoi
• Fix #76 by @TeXitoi
• Re-licensed to Apache-2.0/MIT by @CAD97

• An empty line in a doc comment will result in a double linefeed in the generated about/help call by @TeXitoi

• Fix #66 by @TeXitoi

• Fix a bug around enum tuple and the about message in the global help by @TeXitoi
• Fix #65 by @TeXitoi

Breaking changes

Don't special case u64 by @SergioBenitez

If you are using a u64 in your struct to get the number of occurrence of a flag, you should now add parse(from_occurrences) on the flag.

For example

#[structopt(short = "v", long = "verbose")]
verbose: u64,

must be changed by

#[structopt(short = "v", long = "verbose", parse(from_occurrences))]
verbose: u64,

This feature was surprising as shown in #30. Using the parse feature seems much more natural.

Change the signature of Structopt::from_clap to take its argument by reference by @TeXitoi

There 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.

Fail if attributes are not used by @TeXitoi

StructOpt was quite fuzzy in its attribute parsing: it was only searching for interesting things, e. g. something like #[structopt(foo(bar))] was accepted but not used. It now fails the compilation.

You should have nothing to do here. This breaking change may highlight some misuse that can be bugs.

In future versions, if there is cases that are not highlighted, they will be considerated as bugs, not breaking changes.

Use raw() wrapping instead of _raw suffixing by @TeXitoi

The syntax of raw attributes is changed to improve the syntax.

You have to change foo_raw = "bar", baz_raw = "foo" by raw(foo = "bar", baz = "foo") or raw(foo = "bar"), raw(baz = "foo").

New features

• Add parse(from_occurrences) parser by @SergioBenitez
• Support 1-uple enum variant as subcommand by @TeXitoi
• structopt-derive crate is now an implementation detail, structopt reexport the custom derive macro by @TeXitoi
• Add the StructOpt::from_iter method by @Kerollmops

Documentation

• Improve doc by @bestouff
• All the documentation is now on the structopt crate by @TeXitoi

Breaking changes

Don't special case u64 by @SergioBenitez

If 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.

For example

#[structopt(short = "v", long = "verbose")]
verbose: u64,

must be changed by

#[structopt(short = "v", long = "verbose", parse(from_occurrences))]
verbose: u64,

This feature was surprising as shown in #30. Using the parse feature seems much more natural.

Change the signature of Structopt::from_clap to take its argument by reference by @TeXitoi

There 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.

Fail if attributes are not used by @TeXitoi

StructOpt 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.

You should have nothing to do here. This breaking change may highlight some missuse that can be bugs.

In future versions, if there is cases that are not highlighed, they will be considerated as bugs, not breaking changes.

Use raw() wrapping instead of _raw suffixing by @TeXitoi

The syntax of raw attributes is changed to improve the syntax.

You have to change foo_raw = "bar", baz_raw = "foo" by raw(foo = "bar", baz = "foo") or raw(foo = "bar"), raw(baz = "foo").

New features

• Add parse(from_occurrences) parser by @SergioBenitez
• Support 1-uple enum variant as subcommand by @TeXitoi
• structopt-derive crate is now an implementation detail, structopt reexport the custom derive macro by @TeXitoi
• Add the StructOpt::from_iter method by @Kerollmops

Documentation

• Improve doc by @bestouff
• All the documentation is now on the structopt crate by @TeXitoi

• Allow opting out of clap default features by @ski-csis

• Improve documentation by @TeXitoi
• Fix bug #31 by @TeXitoi

• Fix a bug with optional subsubcommand and Enum by @TeXitoi

• Implement custom string parser from either &str or &OsStr by @kennytm

• Improve doc by @TeXitoi

• Fix bugs #24 and #25 by @TeXitoi
• Support of methods with something else that a string as argument thanks to _raw suffix by @Flakebi

• Better formatting of multiple authors by @killercup

• Better formating of multiple authors by @killercup

• Subcommand support by @williamyaoh

• Using doc comment to populate help by @killercup

• First version with flags, arguments and options support by @TeXitoi