Crate gumdrop[−][src]
Option parser with custom derive support
Examples
#[macro_use] extern crate gumdrop; 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 enum
s to produce a subcommand
option parser.
#[macro_use] extern crate gumdrop; 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.
#[macro_use] extern crate gumdrop; 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); }
Structs
Error |
Represents an error encountered during argument parsing |
Parser |
Parses options from a series of |
Enums
Opt |
Represents an option parsed from a |
ParsingStyle |
Controls behavior of free arguments in |
Traits
Options |
Implements a set of options parsed from command line arguments. |
Functions
parse_args |
Parses arguments from the command line. |
parse_args_default |
Parses arguments from the command line using the default parsing style. |
parse_args_default_or_exit |
Parses arguments from the environment, using the default parsing style. |
parse_args_or_exit |
Parses arguments from the environment. |