Display A Help Screen

Mapping a method with HelpOptionAttribute will allow the parser to display a help screen when parsing rule are violated.

class Options
{
  [Option('p', "person-to-greet", Required=true, HelpText="The person to greet.")]
  public string PersonToGreet { get; set; }

  [HelpOption]
  public string GetUsage()
  {
    return "Please read user manual!" + Environment.NewLine;
  }
}

In this sample the -p|--person-to-great option is mandatory. Omitting it will cause the parser to display the string returned by Options::GetUsage().

When mapping a method with HelpOption the are only few constraints to respect. The method must be an instance method, it has to return a string and accept no parameters. The name of the method is your choice.

Using HelpText Class

The CommandLine.Text namespace contains helper types to make easy the render of the help screen.

class Options
{
  [Option("p", "person-to-greet", Required=true, HelpText="The person to greet.")]
  public string PersonToGreet { get; set; }

  [HelpOption]
  public string GetUsage()
  {
    var help = new HelpText {
      Heading = new HeadingInfo("<<app title>>", "<<app version>>"),
      Copyright = new CopyrightInfo("<<app author>>", 2012),
      AdditionalNewLineAfterOption = true,
      AddDashesToOption = true
    };
    help.AddPreOptionsLine("<<license details here.>>");
    help.AddPreOptionsLine("Usage: app -p Someone");
    help.AddOptions(this);
    return help;
  }
}

In this example the method creates an HelpText instance, it uses secondary helper types to specify heading and copyright informations and sets some preferences.

Then it simply add text as a StringBuilder and with a single call (AddOptions) renders the options block. Every option attribute (except ValueList) inherits from BaseOptionAttribute and this type has a property named BaseOptionAttribute::HelpText and precisely the value of this property is used by AddOptions method.

Handling Parsing Errors

Parsing errors like badly formatted values or missing required options can be captured as generic list of ParsingError type. Access this data requires that your target class contains a property of type IParserState decored with ParserStateAttribute.

class Options
{
  [ParserState]
  public IParserState LastParserState { get; set; }
}

IParserState is simply defined as:

public interface IParserState
{
  IList<ParsingError> Errors { get; }
}

public class ParsingError
{
  public BadOptionInfo BadOption { get; }

  public bool ViolatesRequired { get; }

  public bool ViolatesFormat { get; }

  public bool ViolatesMutualExclusiveness { get; }
}

public sealed class BadOptionInfo
{
  public string ShortName { get; }

  public string LongName { get; }
}

Remarks: you're not entitled to provide your own implementation of IParserState. The library comes with a default implementation named ParserState with an internal constructor.

The following snippet of code demonstrates how to report errors using HelpText::RenderParsingErrorsText for render the text block automatically:

class Options
{
  [HelpOption]
  public string GetUsage()
  {
    var help = new HelpText();
    // ...
    if (this.LastParsingState.Errors.Count > 0) {
      var errors = help.RenderParsingErrorsText(this, 2); // indent with two spaces
      if (!string.IsNullOrEmpty(errors)) {
        help.AddPreOptionsLine(string.Concat(Environment.NewLine, "ERROR(S):"));
        help.AddPreOptionsLine(errors);
      }
    }
    // ...
    return help;
  }
}

Automatic Building

Taking advantage of assembly attributes you can build HelpText instance with one line of code.

As first thing define attributes (usually in Properties/AssemblyInfo.cs):

// from .NET class library
[assembly: AssemblyTitle("yourapp")]
[assembly: AssemblyCopyright("Copyright (C) 2012 Your Name")]
[assembly: AssemblyInformationalVersionAttribute("1.0")]

// from CommandLineParser.Text
[assembly: AssemblyLicense(
    "This is free software. You may redistribute copies of it under the terms of",
    "the MIT License <http://www.opensource.org/licenses/mit-license.php>.")]
[assembly: AssemblyUsage(
    "Usage: YourApp -rMyData.in -wMyData.out --calculate",
    "       YourApp -rMyData.in -i -j9.7 file0.def file1.def")]

Remarks: if you don't define this attributes the library will provide for you reasonable defaults.

Now inside Options::GetUsage method just make call AutoBuild with a delegate, intended to format errors:

return HelpText.AutoBuild(this, (HelpText current) => HelpText.DefaultParsingErrorsHandler(this, current));

As previously stated the parser knows when to call GetUsage and AutoBuild knows how to format the help screen for you.

If you want write a custom delegate the signature is Action<HelpText>. Please refer to the built-in one for reference.

Localize Help Strings

There's a quite (still now) undocumented feature that let you display words like Required in your national language.

There's an HelpText constructor overload that accept a:

public abstract class BaseSentenceBuilder
{
  // Gets a string containing word 'option'.
  public abstract string OptionWord { get; }

  // Gets a string containing the word 'and'.
  public abstract string AndWord { get; }

  // Gets a string containing the sentence 'required option missing'.
  public abstract string RequiredOptionMissingText { get; }

  // Gets a string containing the sentence 'violates format'.
  public abstract string ViolatesFormatText { get; }

  // Gets a string containing the sentence 'violates mutual exclusiveness'.
  public abstract string ViolatesMutualExclusivenessText { get; }

  // Gets a string containing the error heading text.
  public abstract string ErrorsHeadingText { get; }

  // Don't care about this factory method.
  public static BaseSentenceBuilder CreateBuiltIn()
  {
    return new EnglishSentenceBuilder();
  }
}

See the built-in sentence builder, the English one, to know how to implement one.

Remarks: this was not documented because a replacement was scheduled but never done. It may be replaced using delegates (so I can worry of one hierarchy less.).