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

Download history 17797/week @ 2023-10-28 17546/week @ 2023-11-04 20819/week @ 2023-11-11 17923/week @ 2023-11-18 18599/week @ 2023-11-25 18922/week @ 2023-12-02 21916/week @ 2023-12-09 21339/week @ 2023-12-16 11740/week @ 2023-12-23 18253/week @ 2023-12-30 21862/week @ 2024-01-06 21117/week @ 2024-01-13 23197/week @ 2024-01-20 32238/week @ 2024-01-27 20064/week @ 2024-02-03 17397/week @ 2024-02-10

97,120 downloads per month
Used in 110 crates (5 directly)

MIT/Apache

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 type Option<T> 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<T>, 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<T> fields, unless the no_multi option is present.
  • no_multi will inhibit automatically marking Vec<T> 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<T, E> 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.

Dependencies

~1.5MB
~33K SLoC