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.
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);
}
match
- The result of checking command line argumentsopt
- A description of a possible optionresult
- The result of parsing a command line with a set of options (result::tfail_
- The type returned when the command line does not conform to the expected formatfail_str
- Convert a fail_
enum into an error stringgetopts
- Parse command line arguments according to the provided optionsopt_default
- Returns the matching string, a default, or noneopt_maybe_str
- Returns the string argument supplied to a matching option or noneopt_present
- Returns true if an option was matchedopt_str
- Returns the string argument supplied to a matching optionopt_strs
- Returns a vector of the arguments provided to all matches of the given option.optflag
- Create an option that is optional and does not take an argumentoptflagopt
- Create an option that is optional and takes an optional argumentoptmulti
- Create an option that is optional, takes an argument, and may occur multiple timesoptopt
- Create an option that is optional and takes an argumentopts_present
- Returns true if any of several options were matchedopts_str
- Returns the string argument supplied to one of several matching optionsreqopt
- Create an option that is required and takes an argumentmatch
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.
opt
type opt = {name: name, hasarg: hasarg, occur: occur,}
A description of a possible option
result
type result = result::result<match, fail_>
The result of parsing a command line with a set of options (result::t
fail_
The type returned when the command line does not conform to the expected format. Pass this value to
argument_missing(str)
unrecognized_option(str)
option_missing(str)
option_duplicated(str)
unexpected_argument(str)
fail_str
fn fail_str(f: fail_) -> str
Convert a fail_
enum into an error string
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
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.
opt_maybe_str
fn opt_maybe_str(m: match, nm: str) -> option<str>
Returns the string argument supplied to a matching option or none
opt_present
fn opt_present(m: match, nm: str) -> bool
Returns true if an option was matched
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
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.
optflag
fn optflag(name: str) -> opt
Create an option that is optional and does not take an argument
optflagopt
fn optflagopt(name: str) -> opt
Create an option that is optional and takes an optional argument
optmulti
fn optmulti(name: str) -> opt
Create an option that is optional, takes an argument, and may occur multiple times
optopt
fn optopt(name: str) -> opt
Create an option that is optional and takes an argument
opts_present
fn opts_present(m: match, names: ~[str]) -> bool
Returns true if any of several options were matched
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
reqopt
fn reqopt(name: str) -> opt
Create an option that is required and takes an argument