Implement help pages

[lecode-official]

The command line parser should be able to generate help pages from the a declared parser and command line arguments. The help page should adapt to the command that the help was requested for. For example test --help command should produce the general help page for test, while test command --help should generate the help page for the command. If there are multiple help flags such as in test --help command -h, then the most specific help page should be generated, i.e. in this case the help page for the command should be generated. The name and alias of the help switch should be configurable, but should default to --help and -h.

The API should look something like this:

// Uses --help and -h as default for the flag that is used to determine which help page is to be generated
parser.GenerateHelpPage(commandLineArguments);

// But they can be explicitly be defined by the user
parser.GenerateHelpPage(commandLineArguments, "help", "h");

The format for the help pages should be similar to most help pages generated by programs today. There should be a line showing the usage, then a description should follow, then all positional, named, and flag arguments should be documented, and finally a list of commands should be displayed. A project which has nice help pages is docopt. The .NET Core CLI also produces nice help pages and can be used as a reference.

[lecode-official]

An even better way to implement this feature would be to just have a GenerateHelpPage method, which takes no arguments. Sub parsers can then generate the help page for the command the sub parser represents.

To make this easier a Parent property should be implemented. In turn, the sub parsers property should be renamed to Children. This makes it possible that when generating the help page, a parser can navigate upwards to its parent and grand parents to generate the usage description. SubResults should also be renamed to ChildResults.

[lecode-official]

I just figured out that is very important that positional arguments must be optional, when a help flag is present. Imagine command line arguments likes this: ./test file01 file02 --option --value=test. If I wanted help in that case, usually I would expect to just type ./test -h. But due to how the current implementation works, this would result in a parse error, as the two non-optional positional arguments could not be found. Therefore I believe there should be some designated flag, which is the help flag and it should be configurable but default to --help and -h. If this flag is present that even the positional arguments are optional. I'll have to think more about the consequences, but this sounds like a reasonable thing to do.

[lecode-official]

I thought about this a little more and I came to the conclusion that having a default (but configurable) help flag is not elegant. The easiest way to get around the problem of having non-optional positional arguments is, that the parser should not directly raise an exception when an error occurs, but should keep on parsing and include the errors in the result. This way, even if the arguments are invalid, the user could generate a help page and display without having to show an error message to the user.

[lecode-official]

I also thought about the two options for implementing the GenerateHelpPage method:

• The first method were the user supplies the command line arguments and a switch, and the parser determines which help page to generate on its ow
• The second method were the user selects the correct sub-parser for which she wants to generate the help page

I actually now think both implementations are nice and allow for multiple scenarios. The first version makes it very easy for beginners, but the second method allows for way more flexibility. So I'll probably implement both of them.