9 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

#1 in #struct-types

Download history 17762/week @ 2023-11-02 18737/week @ 2023-11-09 20796/week @ 2023-11-16 18290/week @ 2023-11-23 17408/week @ 2023-11-30 21342/week @ 2023-12-07 22435/week @ 2023-12-14 14281/week @ 2023-12-21 15214/week @ 2023-12-28 21025/week @ 2024-01-04 20679/week @ 2024-01-11 23745/week @ 2024-01-18 23225/week @ 2024-01-25 29257/week @ 2024-02-01 20825/week @ 2024-02-08 16492/week @ 2024-02-15

94,019 downloads per month
Used in 109 crates (89 directly)

MIT/Apache

36KB
489 lines

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 derived here only 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.
    //
    // A boolean field named `help` is automatically given the `help_flag` attribute.
    // The `parse_args_or_exit` and `parse_args_default_or_exit` functions use help flags
    // to automatically display usage to the user.
    #[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

~1.5MB
~34K SLoC