help generation example sorely missing

[janslav]

You talk about help generation all over the place but you never mention any related code. Not in the readme, and not in the sample.
Please include an actual example of a Main method that contains all the features - parsing and help output and error output.

[janslav]

Oh I noticed the Parse method writes the help automatically when provided with "-h". That's not very wise API.

[nemec]

Hi janslav, the default help settings (-h/--help) are there to make it easy to get a full "command line experience" without having to worry about anything beyond the specific command line options you need for your application. Both the short and long argument are commonly used help options, so that's why we provide both.

Since Help is added automatically I didn't really go into detail on how to customize it, but I agree that there should be a section on Help included in the README. There are method/constructor overloads that let you pass in your own HelpGenerator and if you want to remove the trigger on -h you can subclass the default generator and set the ShortName to null:

class CustomHelp : AutomaticHelpGenerator<CommandLineOpts>
{
    public CustomHelp()
    {
        ShortName = null;
        LongName = "help";
    }
}

Then pass it in to the parser:

var parser = new CliParser<CommandLineOpts>(
    obj, 
    ParserOptions.None, 
    new CustomHelp());

I'll look into making this both more visible to users and easier to use. Thanks for your input!

[janslav]

my API comment wasn't about the fact that -h means help. That part is ok.
It was about the fact that a method called Parse writes out help as a side effect, which is both counter-intuitive and undocumented. Not to mention a clear indication is missing saying that the help was actually written out.
Also i didn't find a way to actually obtain the written-out help text other than looking at the console. The GetUsage method only returns a small subset of the whole thing.

[nemec]

Ah, I see. Yes, help, version, and other Triggers are a way to introduce execution of code into the parsing process, but I don't do a good job of explaining that.

There is a GetHelp method, but that requires a ParserConfig which I see now is not publicly accessible. I'll find a better way to expose the full help text.

[Nebur99]

So is it possible to get the help text as a string right now by exposing classes that are currently internal ? How? I would appreciate if you could elaborate a bit more. I don't mind if it is messy as long as I'm able to get the help text into a string instead of stdout. Thank you.

[nemec]

You need two pieces.

1. The private HelpGenerator property on the CliParser object.
2. A ParserConfig (see the Parse method)

The easiest solution would be to copy the Parse method above in the CliParser class, rename it GetHelp, and replace the last line of the method with return HelpGenerator.GetHelp(config).

Then you can call Console.WriteLine(parser.GetHelp()); to display the full help message.

[nemec]

@Spainman FYI I just committed some code that makes it much easier to get the help message as a string. It's not on NuGet (yet).

var parser = new CliParser<Options>(new Options());
var help = new AutomaticHelpGenerator<Options>();
// Gets the usage message, a short summary of available arguments.
Console.WriteLine(help.GetUsage(parser.Config));
// Gets the full help message with argument descriptions.
Console.WriteLine(help.GetHelp(parser.Config));