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 match 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.

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.

use std;
import std::getopts::{optopt,optflag,getopts,opt_present,opt_maybe_str,
    fail_str};

fn do_work(in: str, out: option<str>) {
    // ...
}

fn print_usage(program: str) {
    io::println("Usage: " + program + " [options]/~");
    io::println("-o\\t\\tOutput");
    io::println("-h --help\\tUsage");
}

fn main(args: [str]/~) {
    check vec::is_not_empty(args);

    let program : str = vec::head(args);

    let opts = [
        optopt("o"),
        optflag("h"),
        optflag("help")
    ]/~;
    let match = alt getopts(vec::tail(args), opts) {
        result::ok(m) { m }
        result::err(f) { fail fail_str(f) }
    };
    if opt_present(match, "h") || opt_present(match, "help") {
        print_usage(program);
        ret;
    }
    let output = opt_maybe_str(match, "o");
    let input = if vec::is_not_empty(match.free) {
        match.free[0]
    } else {
        print_usage(program);
        ret;
    };
    do_work(input, output);
}

Type match

type match = {opts: ~[opt], vals: ~[~[optval]], free: ~[str],}

The result of checking command line arguments. Contains a vector of matches and a vector of free strings.

Type opt

type opt = {name: name, hasarg: hasarg, occur: occur,}

A description of a possible option

Type result

type result = result::result<match, fail_>

The result of parsing a command line with a set of options (result::t)

Enum fail_

The type returned when the command line does not conform to the expected format. Pass this value to to get an error message.

Variants

Function fail_str

fn fail_str(f: fail_) -> str

Convert a fail_ enum into an error string

Function getopts

fn getopts(args: ~[str], opts: ~[opt]) -> result

Parse command line arguments according to the provided options

On success returns ok(opt). Use functions such as opt_present opt_str, etc. to interrogate results. Returns err(fail_) on failure. Use to get an error message.

Function opt_default

fn opt_default(m: match, nm: str, def: str) -> option<str>

Returns the matching string, a default, or none

Returns none if the option was not present, def if the option was present but no argument was provided, and the argument if the option was present and an argument was provided.

Function opt_maybe_str

fn opt_maybe_str(m: match, nm: str) -> option<str>

Returns the string argument supplied to a matching option or none

Function opt_present

fn opt_present(m: match, nm: str) -> bool

Returns true if an option was matched

Function opt_str

fn opt_str(m: match, nm: str) -> str

Returns the string argument supplied to a matching option

Fails if the option was not matched or if the match did not take an argument

Function opt_strs

fn opt_strs(m: match, nm: str) -> ~[str]

Returns a vector of the arguments provided to all matches of the given option.

Used when an option accepts multiple values.

Function optflag

fn optflag(name: str) -> opt

Create an option that is optional and does not take an argument

Function optflagopt

fn optflagopt(name: str) -> opt

Create an option that is optional and takes an optional argument

Function optmulti

fn optmulti(name: str) -> opt

Create an option that is optional, takes an argument, and may occur multiple times

Function optopt

fn optopt(name: str) -> opt

Create an option that is optional and takes an argument

Function opts_present

fn opts_present(m: match, names: ~[str]) -> bool

Returns true if any of several options were matched

Function opts_str

fn opts_str(m: match, names: ~[str]) -> str

Returns the string argument supplied to one of several matching options

Fails if the no option was provided from the given list, or if the no such option took an argument

Function reqopt

fn reqopt(name: str) -> opt

Create an option that is required and takes an argument