gumdrop

To use gumdrop in your Rust project, add it as a dependency in your Cargo.toml file. This provides an option parser with custom derive support.

[dependencies]
gumdrop = "0.8"

In addition to field attributes, certain flags can be set at the type level (on the struct or enum itself) to establish defaults for all contained fields:

• no_help_flag
• no_long
• no_short
• required

The ParsingStyle enum controls how the parser treats "free" (non-option) arguments.

• ParsingStyle::AllOptions: The default. The parser continues to look for options (like -o or --long) even after encountering free arguments.
• ParsingStyle::StopAtFirstFree: Once the first non-option argument is encountered, all subsequent arguments are treated as free arguments, even if they look like options.

use gumdrop::{Options, ParsingStyle};

#[derive(Debug, Options)]
struct MyOptions {
    #[options(help = "flag")]
    flag: bool,
    #[options(free)]
    free: Vec<String>,
}

// If args are ["foo", "-flag"]
// AllOptions: flag=true, free=["foo", "-flag"]
// StopAtFirstFree: flag=false, free=["foo", "-flag"]

The gumdrop_derive crate provides the #[derive(Options)] procedural macro. When applied to a struct or enum, it automatically generates an implementation of the gumdrop::Options trait, allowing you to parse command-line arguments into your data structures.

Supported Types

• Structs: Used to define a collection of options and positional arguments. Unit structs and tuple structs are not supported.
• Enums: Used to define subcommands. Each variant must be a unary tuple variant (e.g., Variant(SubcommandOptions)).

#[derive(gumdrop::Options)]
struct MyOptions {
    #[options(help = "a help flag")]
    help: bool,
}

In gumdrop, you can define subcommands and their specific options using the #[options] attribute on a struct. This attribute can be used on the main configuration struct or on nested subcommand structs.

Supported attributes within #[options(...)] include:

• name: Sets the name of the command.
• help: Sets the help text for the command.

Additionally, you can use #[doc = "..."] to provide documentation that gumdrop will use for help generation.

Gumdrop provides helper functions to parse arguments directly from the process environment and handle errors or help requests automatically.

• parse_args_default_or_exit(): The most common entry point. It uses the default ParsingStyle. If parsing fails, it prints the error to stderr and exits with code 2. If --help is requested, it prints usage and exits with code 0.
• parse_args_or_exit(style): Same as above, but allows specifying a ParsingStyle.

use gumdrop::Options;

#[derive(Debug, Options)]
struct MyOptions {
    #[options(help = "help")]
    help: bool,
}

fn main() {
    // Automatically handles --help and errors
    let opts = MyOptions::parse_args_default_or_exit();
}

The Options trait is the core interface for all CLI structures in gumdrop. It is typically implemented via #[derive(Options)].

Key Methods:

• parse<S: AsRef<str>>(parser: &mut Parser<S>) -> Result<Self, Error>: The low-level parsing logic.
• parse_args<S: AsRef<str>>(args: &[S], style: ParsingStyle) -> Result<Self, Error>: Parses a slice of arguments with a specific style.
• parse_args_default<S: AsRef<str>>(args: &[S]) -> Result<Self, Error>: Parses a slice of arguments using ParsingStyle::AllOptions.
• usage() -> &'static str: Returns the usage string for the type.
• self_usage() -> &'static str: Returns usage for the current instance (useful for subcommands).
• command_list() -> Option<&'static str>: Returns a list of available commands.
• command_name(&self) -> Option<&'static str>: Returns the name of the active command (for enums).

You can apply global settings to your entire parser using the #[options(...)] attribute on your main struct. These settings affect how all subsequent options are treated:

• no_help_flag: Disables the automatic --help flag.
• no_short: Disables short flags (e.g., -s) for all options.
• no_long: Disables long flags (e.g., --short) for all options.
• no_multi: Disables multi-value support (e.g., Vec<T>) for all options.
• required: Makes all options required by default.
• help = "...": Sets global help text.

Example:

#[derive(Options)]
#[options(no_short, help = "My CLI Tool")]
struct MyOpts {
    // ...
}

You can control how a field's string argument is converted into its target type using parsing attributes:

• from_str = "path": Uses the specified function to convert the string argument. If no path is provided (from_str), it uses ::std::convert::From::from.
• try_from_str = "path": Uses the specified function which returns a Result. If no path is provided (try_from_str), it defaults to ::std::str::FromStr::from_str.

Example usage in an attribute:

#[options(from_str = "my_custom_parser")]
field: MyType,