#args #command-line #flag #getopts #option

gumdrop

Option parser with custom derive support

8 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.1.0 May 23, 2017

#139 in Rust patterns

Download history 9380/week @ 2021-02-26 10010/week @ 2021-03-05 9634/week @ 2021-03-12 10271/week @ 2021-03-19 9991/week @ 2021-03-26 8529/week @ 2021-04-02 9715/week @ 2021-04-09 8166/week @ 2021-04-16 7905/week @ 2021-04-23 8810/week @ 2021-04-30 9011/week @ 2021-05-07 8288/week @ 2021-05-14 10237/week @ 2021-05-21 8962/week @ 2021-05-28 9919/week @ 2021-06-04 7267/week @ 2021-06-11

40,001 downloads per month
Used in 69 crates (51 directly)

MIT/Apache

89KB
2K 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:

Option parser with custom derive support

For full documentation on customization of derive(Options), please see the crate documentation for gumdrop_derive.

Examples

use gumdrop::Options;

// Defines options that can be parsed from the command line.
//
// `derive(Options)` will generate an implementation of the trait `Options`.
// Each field must either have a `Default` implementation or an inline
// default value provided.
//
// (`Debug` is only derived here for demonstration purposes.)
#[derive(Debug, Options)]
struct MyOptions {
    // Contains "free" arguments -- those that are not options.
    // If no `free` field is declared, free arguments will result in an error.
    #[options(free)]
    free: Vec<String>,

    // Boolean options are treated as flags, taking no additional values.
    // The optional `help` attribute is displayed in `usage` text.
    #[options(help = "print help message")]
    help: bool,

    // Non-boolean fields will take a value from the command line.
    // Wrapping the type in an `Option` is not necessary, but provides clarity.
    #[options(help = "give a string argument")]
    string: Option<String>,

    // A field can be any type that implements `FromStr`.
    // The optional `meta` attribute is displayed in `usage` text.
    #[options(help = "give a number as an argument", meta = "N")]
    number: Option<i32>,

    // A `Vec` field will accumulate all values received from the command line.
    #[options(help = "give a list of string items")]
    item: Vec<String>,

    // The `count` flag will treat the option as a counter.
    // Each time the option is encountered, the field is incremented.
    #[options(count, help = "increase a counting value")]
    count: u32,

    // Option names are automatically generated from field names, but these
    // can be overriden. The attributes `short = "?"`, `long = "..."`,
    // `no_short`, and `no_long` are used to control option names.
    #[options(no_short, help = "this option has no short form")]
    long_option_only: bool,
}

fn main() {
    let opts = MyOptions::parse_args_default_or_exit();

    println!("{:#?}", opts);
}

derive(Options) can also be used on enums to produce a subcommand option parser.

use gumdrop::Options;

// Define options for the program.
#[derive(Debug, Options)]
struct MyOptions {
    // Options here can be accepted with any command (or none at all),
    // but they must come before the command name.
    #[options(help = "print help message")]
    help: bool,
    #[options(help = "be verbose")]
    verbose: bool,

    // The `command` option will delegate option parsing to the command type,
    // starting at the first free argument.
    #[options(command)]
    command: Option<Command>,
}

// The set of commands and the options each one accepts.
//
// Each variant of a command enum should be a unary tuple variant with only
// one field. This field must implement `Options` and is used to parse arguments
// that are given after the command name.
#[derive(Debug, Options)]
enum Command {
    // Command names are generated from variant names.
    // By default, a CamelCase name will be converted into a lowercase,
    // hyphen-separated name; e.g. `FooBar` becomes `foo-bar`.
    //
    // Names can be explicitly specified using `#[options(name = "...")]`
    #[options(help = "show help for a command")]
    Help(HelpOpts),
    #[options(help = "make stuff")]
    Make(MakeOpts),
    #[options(help = "install stuff")]
    Install(InstallOpts),
}

// Options accepted for the `help` command
#[derive(Debug, Options)]
struct HelpOpts {
    #[options(free)]
    free: Vec<String>,
}

// Options accepted for the `make` command
#[derive(Debug, Options)]
struct MakeOpts {
    #[options(free)]
    free: Vec<String>,
    #[options(help = "number of jobs", meta = "N")]
    jobs: Option<u32>,
}

// Options accepted for the `install` command
#[derive(Debug, Options)]
struct InstallOpts {
    #[options(help = "target directory")]
    dir: Option<String>,
}

fn main() {
    let opts = MyOptions::parse_args_default_or_exit();

    println!("{:#?}", opts);
}

A custom parsing function can be supplied for each option field.

use gumdrop::Options;

#[derive(Debug, Options)]
struct MyOptions {
    // `try_from_str = "..."` supplies a conversion function that may fail
    #[options(help = "a hexadecimal value", parse(try_from_str = "parse_hex"))]
    hex: u32,
    // `from_str = "..."` supplies a conversion function that always succeeds
    #[options(help = "a string that becomes uppercase", parse(from_str = "to_upper"))]
    upper: String,
}

fn parse_hex(s: &str) -> Result<u32, std::num::ParseIntError> {
    u32::from_str_radix(s, 16)
}

fn to_upper(s: &str) -> String {
    s.to_uppercase()
}

fn main() {
    let opts = MyOptions::parse_args_default_or_exit();

    println!("{:#?}", opts);
}

Dependencies

~330–760KB
~19K SLoC