hare

commit 4d8f8121c2fdfd958fc51b053dd11cc9d690728d
parent e34554b7d315cce08d8a0df78bcbf39c25834af8
Author: Sebastian <sebastian@sebsite.pw>
Date:   Thu,  5 May 2022 17:34:23 -0400

getopt: migrate long doc comment to README

Signed-off-by: Sebastian <sebastian@sebsite.pw>

Diffstat:
M
getopt/README
 | 
47
+++++++++++++++++++++++++++++++++++++++++++++++
M
getopt/getopts.ha
 | 
49
-------------------------------------------------

2 files changed, 47 insertions(+), 49 deletions(-)
diff --git a/getopt/README b/getopt/README
@@ -2,6 +2,53 @@ 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.
diff --git a/getopt/getopts.ha b/getopt/getopts.ha
@@ -67,55 +67,6 @@ export type help = (cmd_help | flag_help | parameter_help);
 // [[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.
-//
-// 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) {
-// 		let 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) {
-// 		let 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 stderr, and
-// [[os::exit]] will be called with a successful exit status.
 export fn parse(args: []str, help: help...) command = {
 	let opts: []option = [];
 	let i = 1z;