getopt
getopt provides an interface for parsing command line arguments and automatically generates a brief help message explaining the command usage. See parse or tryparse for the main entry point.
The caller provides help arguments to specify which command line flags and parameters are supported, and to provide some brief help text which describes their use. Provide flag_help to add a flag which does not take a parameter, and parameter_help to add a flag with a required parameter. The first cmd_help is used as a short, one-line summary of the command's purpose, and any later cmd_help arguments are used to provide the name of any arguments which follow the options list.
By convention, the caller should sort the list of options, first providing all flags, then all parameters, alpha-sorted within each group by the flag rune.
// Usage for sed
const cmd = getopt::parse(os::args,
"stream editor",
('E', "use extended regular expressions"),
('i', "edit files in place"),
('s', "treat files as separate, rather than one continuous stream"),
('z', "separate lines by NUL characters"),
('e', "script", "execute commands from script"),
('f', "file", "execute commands from a file"),
"files...",
);
defer getopt::finish(&cmd);
for (let opt .. cmd.opts) {
switch (opt.0) {
case 'E' =>
extended = true;
case 'i' =>
in_place = true;
case 's' =>
continuous = false;
case 'z' =>
sep = '\0';
case 'e' =>
script = opt.1;
case 'f' =>
file = opt.1;
case => abort(); // unreachable
};
};
for (let arg .. cmd.args) {
// ...
};
If any non-option arguments are provided on the command line, the options list is terminated by the first non-option argument, or by a "--" argument if one is present. The arguments list is NOT reordered to accomodate for options which appear after other arguments. Overriding the behavior of "--" is not supported; providing '-' as a flag or parameter rune will have no effect.
If "-h" is not among the options defined by the caller, the "-h" option will cause a summary of the command usage to be printed to os::stderr (see also printhelp), and os::exit will be called with os::status::SUCCESS. The help text is brief and should serve only as a reminder. It is recommended that your command line program be accompanied by a man page to provide detailed usage information. 'h' may be provided as a flag or parameter rune to override the default behavior.
Index
Types
type cmd_help = str;
type command = struct {
opts: [](rune, str),
subcmd: (void | (str, *command)),
args: []str,
help: []help,
};
type flag_help = (rune, str);
type help = (cmd_help | flag_help | parameter_help | subcmd_help);
type parameter_help = (rune, str, str);
type subcmd_help = (str, []help);
type requires_arg = rune;
type unknown_option = rune;
type unknown_subcmd = str;
Errors
type error = !(str, []help, (requires_arg | unknown_option | unknown_subcmd));
Functions
fn finish(cmd: *command) void;
fn parse(args: []str, help: help...) command;
fn printhelp(out: io::handle, name: str, help: []help) (void | io::error);
fn printusage(out: io::handle, name: str, help: []help) (void | io::error);
fn strerror(err: error) str;
fn tryparse(args: []str, help: help...) (command | error);
Types
type cmd_help
type cmd_help = str;
Help text providing a short, one-line summary of the command; or providing the name of an argument.
type command
type command = struct {
opts: [](rune, str),
subcmd: (void | (str, *command)),
args: []str,
help: []help,
};
The result of parsing the set of command line arguments, including any options specified and the list of non-option arguments. If a subcommand is present in the help passed to parse, then there will be no args.
type flag_help
type flag_help = (rune, str);
Help text for a flag, formatted as "-a: help text".
type help
type help = (cmd_help | flag_help | parameter_help | subcmd_help);
Help text for a command or option. cmd_help, flag_help, and parameter_help compose such that the following []help:
[
"foo bars in order",
('a', "a help text"),
('b', "b help text"),
('c', "cflag", "c help text"),
('d', "dflag", "d help text"),
"files...",
]
will produce this help text:
foo: foo bars in order
Usage: foo [-ab] [-c <cflag>] [-d <dflag>] files...
-a: a help text
-b: b help text
-c <cflag>: c help text
-d <dflag>: d help text
type parameter_help
type parameter_help = (rune, str, str);
Help text for a parameter, formatted as "-a param: help text" where "param" is the first string and "help text" is the second string.
type subcmd_help
type subcmd_help = (str, []help);
Definition of a named subcommand.
type requires_arg
Show undocumented member
type requires_arg = rune;
type unknown_option
Show undocumented member
type unknown_option = rune;
type unknown_subcmd
Show undocumented member
type unknown_subcmd = str;
Errors
type error
Show undocumented member
type error = !(str, []help, (requires_arg | unknown_option | unknown_subcmd));
Functions
fn finish
fn finish(cmd: *command) void;
Frees resources associated with the return value of parse.
fn printhelp
fn printhelp(out: io::handle, name: str, help: []help) (void | io::error);
Prints command help to the provided stream.
fn printusage
fn printusage(out: io::handle, name: str, help: []help) (void | io::error);
Prints command usage to the provided stream.
fn strerror
fn strerror(err: error) str;
Converts a parsing error into a human-friendly string. The result may be statically allocated.
fn tryparse
fn tryparse(args: []str, help: help...) (command | 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.