9 releases (breaking)

0.8.0 Apr 15, 2020
0.7.0 Oct 13, 2019
0.6.0 Jun 25, 2019
0.5.0 Jul 28, 2018
0.3.0 Jul 1, 2017

#135 in Procedural macros

Download history 9887/week @ 2021-08-10 10098/week @ 2021-08-17 11392/week @ 2021-08-24 10456/week @ 2021-08-31 11501/week @ 2021-09-07 11839/week @ 2021-09-14 10626/week @ 2021-09-21 10624/week @ 2021-09-28 10415/week @ 2021-10-05 11184/week @ 2021-10-12 10085/week @ 2021-10-19 9924/week @ 2021-10-26 10113/week @ 2021-11-02 10620/week @ 2021-11-09 14631/week @ 2021-11-16 11600/week @ 2021-11-23

48,852 downloads per month
Used in 82 crates (5 directly)

MIT/Apache

62KB
1.5K SLoC

gumdrop

Option parser with custom derive support

Documentation

Building

To include gumdrop in your project, add the following to your Cargo.toml:

[dependencies]
gumdrop = "0.8"

License

gumdrop is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT for details.


lib.rs:

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

The options attribute may also be added at the type level.

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.

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.

Dependencies

~290–710KB
~18K SLoC

"[^