longopt

A long option parser for hare programs.

Usage

See haredoc longopt:

// 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);

Examples

All examples are provided in cmd/.

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)!;
	};
};
hare run cmd/yes --help
cmd/yes: output a string repeatedly until killed

Usage: cmd/yes [-h] [--help] [--version] [STRING]...

	-h, --help: display this help and exit
	--version: output version information and exit