getopt
getopt provides an interface for parsing command line arguments and
automatically generates a brief help message explaining the command usage. See
parse 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"),
('s', "treat files as separate, rather than one continuous stream"),
('i', "edit files in place"),
('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 i = 0z; i < len(cmd.opts); i += 1) {
const opt = cmd.opts[i];
switch (opt.0) {
case 'E' =>
extended = true;
case 's' =>
continuous = false;
// ...
case 'e' =>
script = opt.1;
case 'f' =>
file = opt.1;
};
};
for (let i = 0z; i < len(cmd.args); i += 1) {
const arg = cmd.args[i];
// ...
};
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 a successful exit status.
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.
Index
Types
type cmd_help;
type command;
type flag;
type flag_help;
type help;
type option;
type parameter;
type parameter_help;
Functions
fn finish(*command) void;
fn parse([]str, help...) command;
fn printhelp(io::handle, str, []help) void;
fn printusage(io::handle, str, []help) void;
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: []option,
args: []str,
};
The result of parsing the set of command line arguments, including any
options specified and the list of non-option arguments.
type flag
type flag = rune;
A flag which does not take a parameter, e.g. "-a".
type flag_help
type flag_help = (flag, str);
Help text for a flag, formatted as "-a: help text".
type help
type help = (cmd_help | flag_help | parameter_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 option
type option = (flag, parameter);
A command line option.
type parameter
type parameter = str;
An option with an included parameter, e.g. "-a foo".
type parameter_help
type parameter_help = (flag, 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.
Functions
fn finish
fn finish(cmd: *command) void;
Frees resources associated with the return value of parse.
fn parse
fn parse(args: []str, help: help...) command;
Parses command line arguments and returns a tuple of the options specified,
and the remaining arguments. If an error occurs, details are printed to
os::stderr and os::exit is called with a nonzero exit status. The
argument list must include the command name as the first item; os::args
fulfills this criteria.
fn printhelp
fn printhelp(out: io::handle, name: str, help: []help) void;
Prints command help to the provided stream.
fn printusage
fn printusage(out: io::handle, name: str, help: []help) void;
Prints command usage to the provided stream.