| 1 |
getopt: command line option parsing |
| 2 |
|
| 3 |
getopt provides an interface for parsing command line arguments and |
| 4 |
automatically generates a brief help message explaining the command usage. See |
| 5 |
[[parse]] or [[tryparse]] for the main entry point. |
| 6 |
|
| 7 |
The caller provides [[help]] arguments to specify which command line flags and |
| 8 |
parameters are supported, and to provide some brief help text which describes |
| 9 |
their use. Provide [[flag_help]] to add a flag which does not take a parameter, |
| 10 |
and [[parameter_help]] to add a flag with a required parameter. The first |
| 11 |
[[cmd_help]] is used as a short, one-line summary of the command's purpose, and |
| 12 |
any later [[cmd_help]] arguments are used to provide the name of any arguments |
| 13 |
which follow the options list. |
| 14 |
|
| 15 |
By convention, the caller should sort the list of options, first providing all |
| 16 |
flags, then all parameters, alpha-sorted within each group by the flag rune. |
| 17 |
|
| 18 |
// Usage for sed |
| 19 |
const cmd = getopt::parse(os::args, |
| 20 |
"stream editor", |
| 21 |
('E', "use extended regular expressions"), |
| 22 |
('i', "edit files in place"), |
| 23 |
('s', "treat files as separate, rather than one continuous stream"), |
| 24 |
('z', "separate lines by NUL characters"), |
| 25 |
('e', "script", "execute commands from script"), |
| 26 |
('f', "file", "execute commands from a file"), |
| 27 |
"files...", |
| 28 |
); |
| 29 |
defer getopt::finish(&cmd); |
| 30 |
|
| 31 |
for (let opt .. cmd.opts) { |
| 32 |
switch (opt.0) { |
| 33 |
case 'E' => |
| 34 |
extended = true; |
| 35 |
case 'i' => |
| 36 |
in_place = true; |
| 37 |
case 's' => |
| 38 |
continuous = false; |
| 39 |
case 'z' => |
| 40 |
sep = '\0'; |
| 41 |
case 'e' => |
| 42 |
script = opt.1; |
| 43 |
case 'f' => |
| 44 |
file = opt.1; |
| 45 |
case => abort(); // unreachable |
| 46 |
}; |
| 47 |
}; |
| 48 |
|
| 49 |
for (let arg .. cmd.args) { |
| 50 |
// ... |
| 51 |
}; |
| 52 |
|
| 53 |
If any non-option arguments are provided on the command line, the options list |
| 54 |
is terminated by the first non-option argument, or by a "--" argument if one is |
| 55 |
present. The arguments list is NOT reordered to accomodate for options which |
| 56 |
appear after other arguments. Overriding the behavior of "--" is not supported; |
| 57 |
providing '-' as a flag or parameter rune will have no effect. |
| 58 |
|
| 59 |
If "-h" is not among the options defined by the caller, the "-h" option will |
| 60 |
cause a summary of the command usage to be printed to [[os::stderr]] (see also |
| 61 |
[[printhelp]]), and [[os::exit]] will be called with [[os::status::SUCCESS]]. |
| 62 |
The help text is brief and should serve only as a reminder. It is recommended |
| 63 |
that your command line program be accompanied by a man page to provide detailed |
| 64 |
usage information. 'h' may be provided as a flag or parameter rune to override |
| 65 |
the default behavior. |