# Crate getopts [−] [src]

🔬 This is a nightly-only experimental API. (`rustc_private`)

this crate is being loaded from the sysroot, an unstable location; did you mean to load this crate from crates.io via `Cargo.toml` instead?

Simple getopt alternative.

Construct a vector of options, either by using `reqopt`, `optopt`, and `optflag` or by building them from components yourself, and pass them to `getopts`, along with a vector of actual arguments (not including `argv[0]`). You'll either get a failure code back, or a match. You'll have to verify whether the amount of 'free' arguments in the match is what you expect. Use `opt_*` accessors to get argument values out of the matches object.

Single-character options are expected to appear on the command line with a single preceding dash; multiple-character options are expected to be proceeded by two dashes. Options that expect an argument accept their argument following either a space or an equals sign. Single-character options don't require the space.

# Usage

This crate is on crates.io and can be used by adding `getopts` to the dependencies in your project's `Cargo.toml`.

    [dependencies]
    getopts = "0.2"

and this to your crate root:

    extern crate getopts;

# Example

The following example shows simple command line parsing for an application that requires an input file to be specified, accepts an optional output file name following `-o`, and accepts both `-h` and `--help` as optional flags.

    extern crate getopts;
    use getopts::Options;
    use std::env;

    fn do_work(inp: &str, out: Option<String>) {
        println!("{}", inp);
        match out {
            Some(x) => println!("{}", x),
            None => println!("No Output"),
        }
    }

    fn print_usage(program: &str, opts: Options) {
        let brief = format!("Usage: {} FILE [options]", program);
        print!("{}", opts.usage(&brief));
    }

    fn main() {
        let args: Vec<String> = env::args().collect();
        let program = args[0].clone();

        let mut opts = Options::new();
        opts.optopt("o", "", "set output file name", "NAME");
        opts.optflag("h", "help", "print this help menu");
        let matches = match opts.parse(&args[1..]) {
            Ok(m) => { m }
            Err(f) => { panic!(f.to_string()) }
        };
        if matches.opt_present("h") {
            print_usage(&program, opts);
            return;
        }
        let output = matches.opt_str("o");
        let input = if !matches.free.is_empty() {
            matches.free[0].clone()
        } else {
            print_usage(&program, opts);
            return;
        };
        do_work(&input, output);
    }

## Structs

Matches | [ Experimental ] The result of checking command line arguments. Contains a vector of matches and a vector of free strings.
Options | [ Experimental ] A description of the options that a program can handle.

## Enums

Fail | [ Experimental ] The type returned when the command line does not conform to the expected format. Use the `Debug` implementation to output detailed information.
HasArg | [ Experimental ] Describes whether an option has an argument.
Occur | [ Experimental ] Describes how often an option may occur.
ParsingStyle | [ Experimental ] What parsing style to use when parsing arguments.

## Type Definitions

Result | [ Experimental ] The result of parsing a command line with a set of options.

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)