// longopt: command line long option parsing
//
// longopt provides an interface for parsing command line arguments modeled
// after getopt from the standard library. It automatically generates a help
// message and command usage. See [[parse]] or [[tryparse]] for the main entry
// point.
//
// Terminology used by this package:
//
// * short flag: an argument that is a single character prefixed by a hyphen
// * long flag: an argument that is one or more characters prefixed by two hyphens
// * alias: a group of short or long flags
// * opt: a flag that takes a value
// * arg: non-flag arguments
//
// The caller provides [[help]] arguments to specify which command line flags and
// parameters are supported, and to provide some help text which describes their
// use. Provide [[flag_help]] to add a flag which does not take a parameter,
// [[flag_opt]] to add a flag which does take a parameter, and [[flag_cmd]] to
// describe arguments.
//
// By convention, the caller should sort the list of options, first providing all
// flags, then all opts, then all args, alpha-sorted within each group. This
// package does not do that for you, if you prefer a specific ordering.
//
// Usage:
//
// // Usage for sed
// const cmd = longopt::parse(os::args,
// "stream editor for filtering and transforming text",
// ("version", "output version information and exit"),
// (['n', "quiet", "silent"]: longopt::alias, "quiet mode"),
// ("debug", "annotate program execution"),
// (['e', "expression"]: longopt::alias, "script", "script to execute"),
// "[file...]",
// );
//
// let quiet = false;
// let debug = false;
// for (let flag .. cmd.flags) {
// if (longopt::isflag(flag, "version")) {
// fmt::println("v0.0.1")!;
// os::exit(0);
// } else if (longopt::isflag(flag, 'n')) {
// quiet = true;
// } else if (longopt::isflag(flag, "debug")) {
// debug = true;
// };
// };
//
// let expression: (void | str) = void;
// for (let opt .. cmd.opts) {
// if (longopt::isflag(opt.0, 'e')) {
// expression = opt.1;
// };
// };
//
// for (let arg .. cmd.args) {
// // ...
// };
// An alias groups flags together.
type alias = []flag;
// Help text for a short summary of the command, or providing names of
// arguments.
type cmd_help = str;
// The result of parsing the set of command line arguments, including any
// flags, options, and arguments. Flags indicate when a flag is present, an
// option is a flag with a value, and args are rest of the arguments.
type command = struct {
opts: []opt,
subcmd: (void | (str, *command)),
flags: []flag,
args: []str,
help: []help,
};
// A flag can be either a short or long flag.
type flag = (rune | str);
// Help text for a flag.
type flag_help = ((flag | alias), str);
// Help text for a flag or option.
type help = (cmd_help | flag_help | opt_help | subcmd_help);
// An option is a flag with a value.
type opt = (flag, str);
// Help text for an option. The second field is the placeholder value and the
// third field is the help string.
type opt_help = ((flag | alias), str, str);
// Definition for named subcommands.
type subcmd_help = (str, []help);
// Convenience function for comparing long and short flags.
fn isflag(candidate: flag, val: (rune | str)) bool;
// A wrapper for [[tryparse]]. If an error occurs, usage (from [[printusage]])
// is printed to [[os::stderr]], and [[os::exit]] is called with
// [[os::status::FAILURE]].
fn parse(args: []str, help: help...) command;
// Print command help to the provided stream.
fn printhelp(out: io::handle, name: str, help: []help) (void | io::error);
// Format and print command usage to the provided stream.
fn printusage(out: io::handle, name: str, help: []help) (void | io::error);
// Parses command line arguments and returns a [[command]], or an [[error]] if
// an error occurs. The argument list must include the command name as the first
// item; [[os::args]] fulfills this criteria.
fn tryparse(args: []str, helps: help...) (command | error | nomem);
use fmt;
use strings;
use longopt;
use os;
export fn main() void = {
const cmd = longopt::parse(os::args,
"output a string repeatedly until killed",
("version", "output version information and exit"),
"[STRING]...",
);
for (let flag .. cmd.flags) {
if (longopt::isflag(flag, "version")) {
fmt::println("v0.0.1")!;
os::exit(0);
};
};
let s = "y";
if (len(cmd.args) > 0) {
// We don't need to bother freeing this.
s = strings::join(" ", cmd.args...)!;
};
for (true) {
fmt::println(s)!;
};
};