10 releases (breaking)
0.8.1 | Mar 9, 2022 |
---|---|
0.8.0 | Apr 15, 2020 |
0.7.0 | Oct 13, 2019 |
0.6.0 | Jun 25, 2019 |
0.3.0 | Jul 1, 2017 |
#1355 in Procedural macros
97,120 downloads per month
Used in 110 crates
(5 directly)
63KB
1.5K
SLoC
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 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 typeOption<T>
whereT
is a type implementingOptions
. Typically, this type is anenum
containing subcommand option types.help_flag
marks an option as a help flag. The field must bebool
type. Options namedhelp
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 allfree
fields, in declared sequence. If the finalfree
field is of typeVec<T>
, it will contain all remaining free arguments.short = "?"
sets the short option name to the given characterno_short
prevents a short option from being assigned to the fieldlong = "..."
sets the long option name to the given stringno_long
prevents a long option from being assigned to the fielddefault
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.
Thedefault_expr
feature must be enabled to use this attribute.required
will cause an error if the option is not present, unless at least onehelp_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 toVec<T>
fields, unless theno_multi
option is present.no_multi
will inhibit automatically markingVec<T>
fields asmulti
not_required
will cancel a type-levelrequired
flag (see below).help = "..."
sets help text returned from theOptions::usage
method; field doc comment may also be provided to set the help text. If both are present, thehelp
attribute value is used.meta = "..."
sets the meta variable displayed in usage for options which accept an argumentparse(...)
uses a named function to parse a value from a string. Valid parsing function types are:parse(from_str = "...")
forfn(&str) -> T
parse(try_from_str = "...")
forfn(&str) -> Result<T, E> where E: Display
parse(from_str)
usesstd::convert::From::from
parse(try_from_str)
usesstd::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, thehelp
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.
Dependencies
~1.5MB
~33K SLoC