D-Programming-Language/phobos — pull request #1840 by AndrejMitrovic (2014-01-06 19:08:37+00:00)
Title: Issue 11876 - Implement automatic --help and --help=option printout for getopt.

**Note**: I haven't added any documentation yet, as I'm looking forward to any comments before the API is settled.

This pull implements automatic `--help` and `--help=option` generation. This means that if the user **doesn't** explicitly list a `"help"` option in the call to getopt, then getopt will attempt to print out a help string to `stdout` if `--help` or `--help=option` is specified on the command-line.

A separate `header` and `footer` can be specified which will be displayed in the help string. This can be used to provide a sensible introduction string and a copyright string at the end.

Finally, if parsing an option fails (e.g. the user specifies a non-digit where a digit was expected), getopt will append the help option of that string to the in-flight exception.

---

The help strings for individual options are specified by adding a string in-between the option name and the receiver, e.g.:

```D
string[] args;
int foo;
getopt(args, "foo", "this is the foo option", &foo);
```

For the `header` and `footer` feature I'm introducing an `OptHelp` struct which can be used as follows:

```D
string[] args;
int foo;
getopt(args, "foo_option", "this is the foo option", &foo,
OptHelp("Invoke via myapp ", "Copyright My Name 2014");
```

I will add the appropriate documentation if the design is OK to you guys.

---

Here are some examples of the code and the printouts:

`Example 1:`

```D
auto optHelp = OptHelp("Documentation: http://dlang.org/
Usage:
app files.d ... { -switch }", "Copyright John Doe 2014");

int size, colors;
args = ["main", "--help"];
getopt(args, optHelp, "size", "The size option is great.", &size,
"colors", "The colors option is nice.", &colors);
```

```
rdmd app.d --help
```

```
Documentation: http://dlang.org/
Usage:
app files.d ... { -switch }
Options:
colors The colors option is nice.
size The size option is great.
Copyright John Doe 2014
```

`Example 2:`

```D
int threads;
args = ["main", "--help=threads"];
getopt(args, "threads", "Specify the number of CPU threads to use.", &threads);
```

```
rdmd app.d --help=threads
```

```
Help for option 'threads': Specify the number of CPU threads to use.
```

`Example 3:`

```D
int threads;
args = ["main", "--help=threads"];
getopt(args, "threads", "Specify the number of CPU threads to use.", &threads);
```

```
rdmd app.d --threads=max
```

```
std.conv.ConvException@C:\dmd-git\dmd2\windows\bin\..\..\src\phobos\std\conv.d(1901):
Unexpected 'm' when converting from type string to type int

Help string for option 'threads': Specify the number of CPU threads to use.
----------------
stack-trace below...
```

---

Notifying: @monarchdodra @andralex

https://d.puremagic.com/issues/show_bug.cgi?id=11876