Module 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 mod extra;
   use extra::getopts::*;
   use std::os;

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

   fn print_usage(program: &str, _opts: &[Opt]) {
       println(fmt!("Usage: %s [options]", program));
       println("-o\\t\\tOutput");
       println("-h --help\\tUsage");
   }

   fn main() {
       let args = os::args();

       let program = copy args[0];

       let opts = ~[
           optopt("o"),
           optflag("h"),
           optflag("help")
       ];
       let matches = match getopts(args.tail(), opts) {
           Ok(m) => { m }
           Err(f) => { fail!(fail_str(f)) }
       };
       if opt_present(&matches, "h") || opt_present(&matches, "help") {
           print_usage(program, opts);
           return;
       }
       let output = opt_maybe_str(&matches, "o");
       let input: &str = if !matches.free.is_empty() {
           copy matches.free[0]
       } else {
           print_usage(program, opts);
           return;
       };
       do_work(input, output);
   }

Type Result

type Result = result::Result<Matches, Fail_>

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

Enum FailType

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.

Enum HasArg

Enum Name

Enum Occur

Struct Matches

pub struct Matches {
    opts: ~[Opt],
    vals: ~[~[Optval]],
    free: ~[~str],
}

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

Struct Opt

pub struct Opt {
    name: Name,
    hasarg: HasArg,
    occur: Occur,
}

A description of a possible option

Implementation of ::std::cmp::Eq for Name

Automatically derived.

fn eq(&self, __arg_0: &Name) -> ::bool

fn ne(&self, __arg_0: &Name) -> ::bool

Implementation of ::std::cmp::Eq for HasArg

Automatically derived.

fn eq(&self, __arg_0: &HasArg) -> ::bool

fn ne(&self, __arg_0: &HasArg) -> ::bool

Implementation of ::std::cmp::Eq for Occur

Automatically derived.

fn eq(&self, __arg_0: &Occur) -> ::bool

fn ne(&self, __arg_0: &Occur) -> ::bool

Implementation of ::std::cmp::Eq for Opt

Automatically derived.

fn eq(&self, __arg_0: &Opt) -> ::bool

fn ne(&self, __arg_0: &Opt) -> ::bool

Implementation of ::std::cmp::Eq for Optval

Automatically derived.

fn eq(&self, __arg_0: &Optval) -> ::bool

fn ne(&self, __arg_0: &Optval) -> ::bool

Implementation of ::std::cmp::Eq for Matches

Automatically derived.

fn eq(&self, __arg_0: &Matches) -> ::bool

fn ne(&self, __arg_0: &Matches) -> ::bool

Implementation of ::std::cmp::Eq for Fail_

Automatically derived.

fn eq(&self, __arg_0: &Fail_) -> ::bool

fn ne(&self, __arg_0: &Fail_) -> ::bool

Implementation of ::std::cmp::Eq for FailType

Automatically derived.

fn eq(&self, __arg_0: &FailType) -> ::bool

fn ne(&self, __arg_0: &FailType) -> ::bool

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_count

fn opt_count(mm: &Matches, nm: &str) -> uint

Returns the number of times an option was matched

Function opt_default

fn opt_default(mm: &Matches, 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(mm: &Matches, nm: &str) -> Option<~str>

Returns the string argument supplied to a matching option or none

Function opt_present

fn opt_present(mm: &Matches, nm: &str) -> bool

Returns true if an option was matched

Function opt_str

fn opt_str(mm: &Matches, 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(mm: &Matches, 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 optflagmulti

fn optflagmulti(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(mm: &Matches, names: &[~str]) -> bool

Returns true if any of several options were matched

Function opts_str

fn opts_str(mm: &Matches, 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