getopt upgrade

[Andrej Mitrovic]

On 9/3/13, Jacob Carlborg <doob at me.com> wrote:
> Could we get some form of API to set a header and footer that is printed
> with the help text. Possible idea:
>
> bool help;
>
> getopt(args, "h|help", &help, @doc("Show this message and exit.");
> getopt.header = "Usage foo [options]\nVersion 0.0.1\n\n";
> getopt.footer = "\n\nUse the 'h' flag for help.";

I have a simpler idea, and I'm already working on the following features:

// no help string:
getopt(args, "foo", &foo);

$ app --help

I think it would be nice if getopt simply listed all the options here,
even if there are no help strings attached and no --help options
explicitly defined.

// help string is in-between the name and the address,
// which is an easy disambiguation for getopt:
getopt(args, "foo", "describe foo option", &foo);

$ app --help

This would print out all the options and their individual help strings
(when present).

// header and footer is described after an explicit "help" option:
getopt(args, "foo", "describe foo option", &foo,
                  "help", "this is the header for --help", "this is
the footer for --help");

$ app --help

This would print out the header, followed by all the options and their
individual help strings, followed by the footer.

Additionally, I was thinking that getopt could be smart enough that if you run:

$ app --help=foo

It would only display the help string for the foo option (if present).

Another addition: when parsing the runtime argument for some option fails:

bool threads;
getopt(args, "threads", "use multithreading", &threads);

$ app --threads=1

Currently this prints:

-----
std.conv.ConvException at std\conv.d(2794): Can't parse string: bool
should be case-insensitive 'true' or 'false'
-----

But if a help string is present we could append the help string to the
exception message:

-----
std.conv.ConvException at std\conv.d(2794): Can't parse string: bool
should be case-insensitive 'true' or 'false'

Help string for option 'threads': use multithreading
-----

The one special case is when the user actually wants --help to store
to a variable, e.g.:

getopt(args, "foo", &foo, "help", &help);

In that case getopt would simply parse --help as a regular option,
rather than attempt to print out the help screen. This avoids any
existing code from breaking.

Thoughts? Andrei?