getopt +linux +x86_64

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[link] 

type cmd_help = str;

Help text providing a short, one-line summary of the command; or providing the name of an argument.

type command[link] 

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[link] 

type flag = rune;

A flag which does not take a parameter, e.g. "-a".

type flag_help[link] 

type flag_help = (flag, str);

Help text for a flag, formatted as "-a: help text".

type help[link] 

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[link] 

type option = (flag, parameter);

A command line option.

type parameter[link] 

type parameter = str;

An option with an included parameter, e.g. "-a foo".

type parameter_help[link] 

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[link] 

fn finish(cmd: *command) void;

Frees resources associated with the return value of parse.

fn parse[link] 

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[link] 

fn printhelp(out: io::handle, name: str, help: []help) void;

Prints command help to the provided stream.

fn printusage[link] 

fn printusage(out: io::handle, name: str, help: []help) void;

Prints command usage to the provided stream.