Crate gumdrop [−] [src]
Option parser with custom derive support
Examples
extern crate gumdrop; #[macro_use] extern crate gumdrop_derive; use std::env::args; use gumdrop::Options; // Defines options that can be parsed from the command line. // // `derive(Options)` will generate an implementation of the trait `Options`. // An implementation of `Default` (derived or otherwise) is required for the // generated implementation. // // (`Debug` is only derived here for demonstration purposes.) #[derive(Debug, Default, 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 args: Vec<String> = args().collect(); // Remember to skip the first argument. That's the program name. let opts = match MyOptions::parse_args_default(&args[1..]) { Ok(opts) => opts, Err(e) => { println!("{}: {}", args[0], e); return; } }; if opts.help { // Printing usage text for the `--help` option is handled explicitly // by the program. // However, `derive(Options)` does generate information about all // defined options. println!("Usage: {} [OPTIONS] [ARGUMENTS]", args[0]); println!(); println!("{}", MyOptions::usage()); } else { println!("{:#?}", opts); } }
derive(Options)
can also be used on enum
s to produce a subcommand
option parser.
extern crate gumdrop; #[macro_use] extern crate gumdrop_derive; use std::env::args; use gumdrop::Options; // Define options for the program. #[derive(Debug, Default, 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, Default, Options)] struct HelpOpts { #[options(free)] free: Vec<String>, } // Options accepted for the `make` command #[derive(Debug, Default, 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, Default, Options)] struct InstallOpts { #[options(help = "target directory")] dir: Option<String>, } fn main() { let args: Vec<String> = args().collect(); // Remember to skip the first argument. That's the program name. let opts = match MyOptions::parse_args_default(&args[1..]) { Ok(opts) => opts, Err(e) => { println!("{}: {}", args[0], e); return; } }; if opts.help { // Main options are printed in the usual way. // This does not include any mention of commands because that // information is held by the Command type itself. println!("Usage: {} [OPTIONS] [COMMAND] [ARGUMENTS]", args[0]); println!(); println!("{}", MyOptions::usage()); println!(); // Help text for commands comes can be found in the `usage` method // of our Command enum. println!("Available commands:"); println!(); println!("{}", Command::usage()); } else if let Some(Command::Help(ref opts)) = opts.command { let cmd = match opts.free.get(0) { Some(cmd) => cmd, None => { println!("{}: help: missing command", args[0]); return; } }; // The Command enum will also give us a list of a command's options // if we ask for it by name. These are the same strings you'd get // from the `usage` method on each option struct. if let Some(help) = Command::command_usage(cmd) { if help.is_empty() { println!("command `{}` has no options", cmd); } else { println!("command `{}` accepts the following options:", cmd); println!(); println!("{}", help); } } else { println!("{}: unrecognized command: {}", args[0], cmd); } } else { 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. |