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);
}