Provides `derive(Options)` for `gumdrop` crate
# `derive(Options)`
`derive(Options)` generates an implementation of the trait `Options`,
creating an option for each field of the decorated `struct`.
See the `gumdrop` [documentation](https://docs.rs/gumdrop/) for an example
of its usage.
## `options` attribute
Behavior of `derive(Options)` can be controlled by adding `#[options(...)]`
attributes to one or more fields within a decorated struct.
Supported items for `struct` fields are:
* `command` indicates that a field represents a subcommand. The field must
be of type `Option` where `T` is a type implementing `Options`.
Typically, this type is an `enum` containing subcommand option types.
* `help_flag` marks an option as a help flag. The field must be `bool` type.
Options named `help` will automatically receive this option.
* `no_help_flag` prevents an option from being considered a help flag.
* `count` marks a field as a counter value. The field will be incremented
each time the option appears in the arguments, i.e. `field += 1;`
* `free` marks a field as a positional argument field. Non-option arguments
will be used to fill all `free` fields, in declared sequence.
If the final `free` field is of type `Vec`, it will contain all
remaining free arguments.
* `short = "?"` sets the short option name to the given character
* `no_short` prevents a short option from being assigned to the field
* `long = "..."` sets the long option name to the given string
* `no_long` prevents a long option from being assigned to the field
* `default` provides a default value for the option field.
The value of this field is parsed in the same way as argument values.
* `default_expr` provides a default value for the option field.
The value of this field is parsed at compile time as a Rust expression
and is evaluated before any argument values are processed.
The `default_expr` feature must be enabled to use this attribute.
* `required` will cause an error if the option is not present,
unless at least one `help_flag` option is also present.
* `multi = "..."` will allow parsing an option multiple times,
adding each parsed value to the field using the named method.
This behavior is automatically applied to `Vec` fields, unless the
`no_multi` option is present.
* `no_multi` will inhibit automatically marking `Vec` fields as `multi`
* `not_required` will cancel a type-level `required` flag (see below).
* `help = "..."` sets help text returned from the `Options::usage` method;
field doc comment may also be provided to set the help text.
If both are present, the `help` attribute value is used.
* `meta = "..."` sets the meta variable displayed in usage for options
which accept an argument
* `parse(...)` uses a named function to parse a value from a string.
Valid parsing function types are:
* `parse(from_str = "...")` for `fn(&str) -> T`
* `parse(try_from_str = "...")` for
`fn(&str) -> Result where E: Display`
* `parse(from_str)` uses `std::convert::From::from`
* `parse(try_from_str)` uses `std::str::FromStr::from_str`
Additionally, the following flags may be set at the type level to establish
default values for all contained fields: `no_help_flag`, `no_long`,
`no_short`, and `required`.
Supported items for `enum` variants are:
* `name = "..."` sets the user-facing command name.
If this option is not present, one is automatically generated from the variant name.
* `help = "..."` sets the help string for the command;
variant doc comment may also be provided to set the help text.
If both are present, the `help` attribute value is used.
The `help` attribute (or a type-level doc comment) can be used to provide
some introductory text which will precede option help text in the usage
string.