rust/src/libstd/getopts.rs

#[doc = "
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);
    }

"];

import core::result::{err, ok};
import core::option;
import core::option::{some, none};
export opt;
export reqopt;
export optopt;
export optflag;
export optflagopt;
export optmulti;
export getopts;
export match;
export fail_;
export fail_str;
export opt_present;
export opt_str;
export opt_strs;
export opt_maybe_str;
export opt_default;
export result; //NDM

enum name { long(str), short(char), }

enum hasarg { yes, no, maybe, }

enum occur { req, optional, multi, }

#[doc = "A description of a possible option"]
type opt = {name: name, hasarg: hasarg, occur: occur};

fn mkname(nm: str) -> name {
    ret if str::len(nm) == 1u {
            short(str::char_at(nm, 0u))
        } else { long(nm) };
}

#[doc = "Create an option that is required and takes an argument"]
fn reqopt(name: str) -> opt {
    ret {name: mkname(name), hasarg: yes, occur: req};
}

#[doc = "Create an option that is optional and takes an argument"]
fn optopt(name: str) -> opt {
    ret {name: mkname(name), hasarg: yes, occur: optional};
}

#[doc = "Create an option that is optional and does not take an argument"]
fn optflag(name: str) -> opt {
    ret {name: mkname(name), hasarg: no, occur: optional};
}

#[doc = "Create an option that is optional and takes an optional argument"]
fn optflagopt(name: str) -> opt {
    ret {name: mkname(name), hasarg: maybe, occur: optional};
}

#[doc = "
Create an option that is optional, takes an argument, and may occur
multiple times
"]
fn optmulti(name: str) -> opt {
    ret {name: mkname(name), hasarg: yes, occur: multi};
}

enum optval { val(str), given, }

#[doc = "
The result of checking command line arguments. Contains a vector
of matches and a vector of free strings.
"]
type match = {opts: [opt], vals: [[optval]], free: [str]};

fn is_arg(arg: str) -> bool {
    ret str::len(arg) > 1u && arg[0] == '-' as u8;
}

fn name_str(nm: name) -> str {
    ret alt nm { short(ch) { str::from_char(ch) } long(s) { s } };
}

fn find_opt(opts: [opt], nm: name) -> option<uint> {
    vec::position(opts, { |opt| opt.name == nm })
}

#[doc = "
The type returned when the command line does not conform to the
expected format. Pass this value to <fail_str> to get an error message.
"]
enum fail_ {
    argument_missing(str),
    unrecognized_option(str),
    option_missing(str),
    option_duplicated(str),
    unexpected_argument(str),
}

#[doc = "Convert a `fail_` enum into an error string"]
fn fail_str(f: fail_) -> str {
    ret alt f {
          argument_missing(nm) { "Argument to option '" + nm + "' missing." }
          unrecognized_option(nm) { "Unrecognized option: '" + nm + "'." }
          option_missing(nm) { "Required option '" + nm + "' missing." }
          option_duplicated(nm) {
            "Option '" + nm + "' given more than once."
          }
          unexpected_argument(nm) {
            "Option " + nm + " does not take an argument."
          }
        };
}

#[doc = "
The result of parsing a command line with a set of options
(result::t<match, fail_>)
"]
type result = result::result<match, fail_>;

#[doc = "
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 <fail_str>
to get an error message.
"]
fn getopts(args: [str], opts: [opt]) -> result unsafe {
    let n_opts = vec::len::<opt>(opts);
    fn f(_x: uint) -> [optval] { ret []; }
    let vals = vec::to_mut(vec::from_fn(n_opts, f));
    let mut free: [str] = [];
    let l = vec::len(args);
    let mut i = 0u;
    while i < l {
        let cur = args[i];
        let curlen = str::len(cur);
        if !is_arg(cur) {
            free += [cur];
        } else if str::eq(cur, "--") {
            let mut j = i + 1u;
            while j < l { free += [args[j]]; j += 1u; }
            break;
        } else {
            let mut names;
            let mut i_arg = option::none::<str>;
            if cur[1] == '-' as u8 {
                let tail = str::slice(cur, 2u, curlen);
                let tail_eq = str::splitn_char(tail, '=', 1u);
                if vec::len(tail_eq) <= 1u {
                    names = [long(tail)];
                } else {
                    names =
                        [long(tail_eq[0])];
                    i_arg =
                        option::some::<str>(tail_eq[1]);
                }
            } else {
                let mut j = 1u;
                names = [];
                while j < curlen {
                    let range = str::char_range_at(cur, j);
                    names += [short(range.ch)];
                    j = range.next;
                }
            }
            let mut name_pos = 0u;
            for vec::each(names) {|nm|
                name_pos += 1u;
                let optid = alt find_opt(opts, nm) {
                  some(id) { id }
                  none { ret err(unrecognized_option(name_str(nm))); }
                };
                alt opts[optid].hasarg {
                  no {
                    if !option::is_none::<str>(i_arg) {
                        ret err(unexpected_argument(name_str(nm)));
                    }
                    vals[optid] += [given];
                  }
                  maybe {
                    if !option::is_none::<str>(i_arg) {
                        vals[optid] += [val(option::get(i_arg))];
                    } else if name_pos < vec::len::<name>(names) ||
                                  i + 1u == l || is_arg(args[i + 1u]) {
                        vals[optid] += [given];
                    } else { i += 1u; vals[optid] += [val(args[i])]; }
                  }
                  yes {
                    if !option::is_none::<str>(i_arg) {
                        vals[optid] += [val(option::get::<str>(i_arg))];
                    } else if i + 1u == l {
                        ret err(argument_missing(name_str(nm)));
                    } else { i += 1u; vals[optid] += [val(args[i])]; }
                  }
                }
            }
        }
        i += 1u;
    }
    i = 0u;
    while i < n_opts {
        let n = vec::len::<optval>(vals[i]);
        let occ = opts[i].occur;
        if occ == req {
            if n == 0u {
                ret err(option_missing(name_str(opts[i].name)));
            }
        }
        if occ != multi {
            if n > 1u {
                ret err(option_duplicated(name_str(opts[i].name)));
            }
        }
        i += 1u;
    }
    ret ok({opts: opts, vals: vec::from_mut(vals), free: free});
}

fn opt_vals(m: match, nm: str) -> [optval] {
    ret alt find_opt(m.opts, mkname(nm)) {
          some(id) { m.vals[id] }
          none { #error("No option '%s' defined", nm); fail }
        };
}

fn opt_val(m: match, nm: str) -> optval { ret opt_vals(m, nm)[0]; }

#[doc = "Returns true if an option was matched"]
fn opt_present(m: match, nm: str) -> bool {
    ret vec::len::<optval>(opt_vals(m, nm)) > 0u;
}

#[doc = "
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
"]
fn opt_str(m: match, nm: str) -> str {
    ret alt opt_val(m, nm) { val(s) { s } _ { fail } };
}

#[doc = "
Returns a vector of the arguments provided to all matches of the given option.

Used when an option accepts multiple values.
"]
fn opt_strs(m: match, nm: str) -> [str] {
    let mut acc: [str] = [];
    for vec::each(opt_vals(m, nm)) {|v|
        alt v { val(s) { acc += [s]; } _ { } }
    }
    ret acc;
}

#[doc = "
Returns the string argument supplied to a matching option or none
"]
fn opt_maybe_str(m: match, nm: str) -> option<str> {
    let vals = opt_vals(m, nm);
    if vec::len::<optval>(vals) == 0u { ret none::<str>; }
    ret alt vals[0] { val(s) { some::<str>(s) } _ { none::<str> } };
}


#[doc = "
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.
"]
fn opt_default(m: match, nm: str, def: str) -> option<str> {
    let vals = opt_vals(m, nm);
    if vec::len::<optval>(vals) == 0u { ret none::<str>; }
    ret alt vals[0] { val(s) { some::<str>(s) } _ { some::<str>(def) } }
}

#[cfg(test)]
mod tests {
    import opt = getopts;
    import result::{err, ok};

    enum fail_type {
        argument_missing_,
        unrecognized_option_,
        option_missing_,
        option_duplicated_,
        unexpected_argument_,
    }

    fn check_fail_type(f: fail_, ft: fail_type) {
        alt f {
          argument_missing(_) { assert (ft == argument_missing_); }
          unrecognized_option(_) { assert (ft == unrecognized_option_); }
          option_missing(_) { assert (ft == option_missing_); }
          option_duplicated(_) { assert (ft == option_duplicated_); }
          unexpected_argument(_) { assert (ft == unexpected_argument_); }
        }
    }


    // Tests for reqopt
    #[test]
    fn test_reqopt_long() {
        let args = ["--test=20"];
        let opts = [reqopt("test")];
        let rs = getopts(args, opts);
        alt check rs {
          ok(m) {
            assert (opt_present(m, "test"));
            assert (opt_str(m, "test") == "20");
          }
        }
    }

    #[test]
    fn test_reqopt_long_missing() {
        let args = ["blah"];
        let opts = [reqopt("test")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) { check_fail_type(f, option_missing_); }
          _ { fail; }
        }
    }

    #[test]
    fn test_reqopt_long_no_arg() {
        let args = ["--test"];
        let opts = [reqopt("test")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) { check_fail_type(f, argument_missing_); }
          _ { fail; }
        }
    }

    #[test]
    fn test_reqopt_long_multi() {
        let args = ["--test=20", "--test=30"];
        let opts = [reqopt("test")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) { check_fail_type(f, option_duplicated_); }
          _ { fail; }
        }
    }

    #[test]
    fn test_reqopt_short() {
        let args = ["-t", "20"];
        let opts = [reqopt("t")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) {
            assert (opt_present(m, "t"));
            assert (opt_str(m, "t") == "20");
          }
          _ { fail; }
        }
    }

    #[test]
    fn test_reqopt_short_missing() {
        let args = ["blah"];
        let opts = [reqopt("t")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) { check_fail_type(f, option_missing_); }
          _ { fail; }
        }
    }

    #[test]
    fn test_reqopt_short_no_arg() {
        let args = ["-t"];
        let opts = [reqopt("t")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) { check_fail_type(f, argument_missing_); }
          _ { fail; }
        }
    }

    #[test]
    fn test_reqopt_short_multi() {
        let args = ["-t", "20", "-t", "30"];
        let opts = [reqopt("t")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) { check_fail_type(f, option_duplicated_); }
          _ { fail; }
        }
    }


    // Tests for optopt
    #[test]
    fn test_optopt_long() {
        let args = ["--test=20"];
        let opts = [optopt("test")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) {
            assert (opt_present(m, "test"));
            assert (opt_str(m, "test") == "20");
          }
          _ { fail; }
        }
    }

    #[test]
    fn test_optopt_long_missing() {
        let args = ["blah"];
        let opts = [optopt("test")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) { assert (!opt_present(m, "test")); }
          _ { fail; }
        }
    }

    #[test]
    fn test_optopt_long_no_arg() {
        let args = ["--test"];
        let opts = [optopt("test")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) { check_fail_type(f, argument_missing_); }
          _ { fail; }
        }
    }

    #[test]
    fn test_optopt_long_multi() {
        let args = ["--test=20", "--test=30"];
        let opts = [optopt("test")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) { check_fail_type(f, option_duplicated_); }
          _ { fail; }
        }
    }

    #[test]
    fn test_optopt_short() {
        let args = ["-t", "20"];
        let opts = [optopt("t")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) {
            assert (opt_present(m, "t"));
            assert (opt_str(m, "t") == "20");
          }
          _ { fail; }
        }
    }

    #[test]
    fn test_optopt_short_missing() {
        let args = ["blah"];
        let opts = [optopt("t")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) { assert (!opt_present(m, "t")); }
          _ { fail; }
        }
    }

    #[test]
    fn test_optopt_short_no_arg() {
        let args = ["-t"];
        let opts = [optopt("t")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) { check_fail_type(f, argument_missing_); }
          _ { fail; }
        }
    }

    #[test]
    fn test_optopt_short_multi() {
        let args = ["-t", "20", "-t", "30"];
        let opts = [optopt("t")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) { check_fail_type(f, option_duplicated_); }
          _ { fail; }
        }
    }


    // Tests for optflag
    #[test]
    fn test_optflag_long() {
        let args = ["--test"];
        let opts = [optflag("test")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) { assert (opt_present(m, "test")); }
          _ { fail; }
        }
    }

    #[test]
    fn test_optflag_long_missing() {
        let args = ["blah"];
        let opts = [optflag("test")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) { assert (!opt_present(m, "test")); }
          _ { fail; }
        }
    }

    #[test]
    fn test_optflag_long_arg() {
        let args = ["--test=20"];
        let opts = [optflag("test")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) {
            log(error, fail_str(f));
            check_fail_type(f, unexpected_argument_);
          }
          _ { fail; }
        }
    }

    #[test]
    fn test_optflag_long_multi() {
        let args = ["--test", "--test"];
        let opts = [optflag("test")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) { check_fail_type(f, option_duplicated_); }
          _ { fail; }
        }
    }

    #[test]
    fn test_optflag_short() {
        let args = ["-t"];
        let opts = [optflag("t")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) { assert (opt_present(m, "t")); }
          _ { fail; }
        }
    }

    #[test]
    fn test_optflag_short_missing() {
        let args = ["blah"];
        let opts = [optflag("t")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) { assert (!opt_present(m, "t")); }
          _ { fail; }
        }
    }

    #[test]
    fn test_optflag_short_arg() {
        let args = ["-t", "20"];
        let opts = [optflag("t")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) {
            // The next variable after the flag is just a free argument

            assert (m.free[0] == "20");
          }
          _ { fail; }
        }
    }

    #[test]
    fn test_optflag_short_multi() {
        let args = ["-t", "-t"];
        let opts = [optflag("t")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) { check_fail_type(f, option_duplicated_); }
          _ { fail; }
        }
    }


    // Tests for optmulti
    #[test]
    fn test_optmulti_long() {
        let args = ["--test=20"];
        let opts = [optmulti("test")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) {
            assert (opt_present(m, "test"));
            assert (opt_str(m, "test") == "20");
          }
          _ { fail; }
        }
    }

    #[test]
    fn test_optmulti_long_missing() {
        let args = ["blah"];
        let opts = [optmulti("test")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) { assert (!opt_present(m, "test")); }
          _ { fail; }
        }
    }

    #[test]
    fn test_optmulti_long_no_arg() {
        let args = ["--test"];
        let opts = [optmulti("test")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) { check_fail_type(f, argument_missing_); }
          _ { fail; }
        }
    }

    #[test]
    fn test_optmulti_long_multi() {
        let args = ["--test=20", "--test=30"];
        let opts = [optmulti("test")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) {
            assert (opt_present(m, "test"));
            assert (opt_str(m, "test") == "20");
            assert (opt_strs(m, "test")[0] == "20");
            assert (opt_strs(m, "test")[1] == "30");
          }
          _ { fail; }
        }
    }

    #[test]
    fn test_optmulti_short() {
        let args = ["-t", "20"];
        let opts = [optmulti("t")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) {
            assert (opt_present(m, "t"));
            assert (opt_str(m, "t") == "20");
          }
          _ { fail; }
        }
    }

    #[test]
    fn test_optmulti_short_missing() {
        let args = ["blah"];
        let opts = [optmulti("t")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) { assert (!opt_present(m, "t")); }
          _ { fail; }
        }
    }

    #[test]
    fn test_optmulti_short_no_arg() {
        let args = ["-t"];
        let opts = [optmulti("t")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) { check_fail_type(f, argument_missing_); }
          _ { fail; }
        }
    }

    #[test]
    fn test_optmulti_short_multi() {
        let args = ["-t", "20", "-t", "30"];
        let opts = [optmulti("t")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) {
            assert (opt_present(m, "t"));
            assert (opt_str(m, "t") == "20");
            assert (opt_strs(m, "t")[0] == "20");
            assert (opt_strs(m, "t")[1] == "30");
          }
          _ { fail; }
        }
    }

    #[test]
    fn test_unrecognized_option_long() {
        let args = ["--untest"];
        let opts = [optmulti("t")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) { check_fail_type(f, unrecognized_option_); }
          _ { fail; }
        }
    }

    #[test]
    fn test_unrecognized_option_short() {
        let args = ["-t"];
        let opts = [optmulti("test")];
        let rs = getopts(args, opts);
        alt rs {
          err(f) { check_fail_type(f, unrecognized_option_); }
          _ { fail; }
        }
    }

    #[test]
    fn test_combined() {
        let args =
            ["prog", "free1", "-s", "20", "free2", "--flag", "--long=30",
             "-f", "-m", "40", "-m", "50", "-n", "-A B", "-n", "-60 70"];
        let opts =
            [optopt("s"), optflag("flag"), reqopt("long"),
             optflag("f"), optmulti("m"), optmulti("n"),
             optopt("notpresent")];
        let rs = getopts(args, opts);
        alt rs {
          ok(m) {
            assert (m.free[0] == "prog");
            assert (m.free[1] == "free1");
            assert (opt_str(m, "s") == "20");
            assert (m.free[2] == "free2");
            assert (opt_present(m, "flag"));
            assert (opt_str(m, "long") == "30");
            assert (opt_present(m, "f"));
            assert (opt_strs(m, "m")[0] == "40");
            assert (opt_strs(m, "m")[1] == "50");
            assert (opt_strs(m, "n")[0] == "-A B");
            assert (opt_strs(m, "n")[1] == "-60 70");
            assert (!opt_present(m, "notpresent"));
          }
          _ { fail; }
        }
    }

}

// Local Variables:
// mode: rust;
// fill-column: 78;
// indent-tabs-mode: nil
// c-basic-offset: 4
// buffer-file-coding-system: utf-8-unix
// End: