Skip to content

HelpText Configuration

Jump to bottom
moh-hassan edited this page Jul 7, 2020 · 4 revisions

HelpText provide AutoBuild method to generate help by passing the different options.

For example:

//1- disable auto generated helpvarparser=newCommandLine.Parser(with =>with.HelpWriter=null);//2- run parser and get resultvarparserResult=parser.ParseArguments<Options>(args);//3- generate help based on result and parametersvarhelpText=HelpText.AutoBuild(parserResult, h =>{//configure HelpTexth.AdditionalNewLineAfterOption=false;//remove newline between optionsh.Heading="Myapp 2.0.0-beta";//change headerh.Copyright="Copyright (c) 2019 Global.com";//change copyright text// more options ...returnh;}, e =>e);// 4- display help from with NotParsed methodresult.WithNotParsed(errs =>DisplayHelp(parserResult,errs));//for complete example see example1 and example2

HelpText layout

Help text is layout as in the following figure:

alt text

It's composed of the following sections:

  • Heading: is formated as: <title> <version>

    Example: ConsoleApp2 1.0.0

  • Copyright: is formatted as 
    Copyright (C) `<year> <Company>`
    or in case of Copyright attribute available: 
    <copyrightAssemblyAttribute>

    Example: Copyright (C) 2019 ConsoleApp2

  • Examples: Syntax of command use.
  • Options_section: series of <Shortname, longName> with its help.
  • Pre_options: is optional block before options.
  • Post_options: is optional block after options.

HelpText Setting

HelpText can be configured using the following Properties and methods.

NameDescription
Properties
AddDashesToOptionGets or sets a value indicating whether the format of options should contain dashes. It modifies behavior of AddOptions(T)(ParserResult(T)) method.
AddEnumValuesToHelpTextGets or sets a value indicating whether to add the values of an enum after the description of the specification.
AdditionalNewLineAfterOptionGets or sets a value indicating whether to add an additional line after the description of the specification.
AutoHelpGets or sets a value indicating whether implicit option or verb 'help' should be supported.
AutoVersionGets or sets a value indicating whether implicit option or verb 'version' should be supported.
CopyrightGets or sets the copyright string. You can directly assign a CopyrightInfo instance.
HeadingGets or sets the heading string. You can directly assign a HeadingInfo instance.
MaximumDisplayWidthGets or sets the maximum width of the display. This determines word wrap when displaying the text.
Methods
AddPostOptionsLineAdds a text line at the bottom, after options usage string.
AddPostOptionsLinesAdds text lines at the bottom, after options usage string.
AddPostOptionsTextAdds a text block of lines at the bottom, after options usage string.
AddPreOptionsLine(String)Adds a text line after copyright and before options usage strings.
AddPreOptionsLinesAdds text lines after copyright and before options usage strings.
AddPreOptionsTextAdds a text block of lines after copyright and before options usage strings.

Example: 1

To use custom help, disable auto generating help by configuring Parser.HelpWriter= null. Use AutoBuild method to build help.

This example configure HelpText with AdditionalNewLineAfterOption

staticvoidMain(string[]args){varparser=newCommandLine.Parser(with =>with.HelpWriter=null);varparserResult=parser.ParseArguments<Options>(args);parserResult.WithParsed<Options>(options =>Run(options)).WithNotParsed(errs =>DisplayHelp(parserResult,errs));}staticvoidDisplayHelp<T>(ParserResult<T>result){varhelpText=HelpText.AutoBuild(result, h =>{h.AdditionalNewLineAfterOption=false;h.Heading="Myapp 2.0.0-beta";//change headerh.Copyright="Copyright (c) 2019 Global.com";//change copyright textreturnHelpText.DefaultParsingErrorsHandler(result,h);}, e =>e);Console.WriteLine(helpText);}privatestaticvoidRun(Optionsoptions){//do stuff}

Help is generated without a newline between options and setting heading and copyright text as displayed below:

Click to expand!
Myapp 2.0.0-beta
Copyright (c) 2019 Global.com
-r, --read Input files to be processed.
--verbose (Default: false) Prints all messages to standard output.
--stdin (Default: false) Read from stdin --help Display this help screen.
--version Display version information.
offset (pos. 0) File offset.

In case of parsing errors, the help text include an error section:

Myapp 2.0.0-beta
Copyright (c) 2019 Global.com
ERROR(S):
Option 'zz' is unknown.
-r, --read Input files to be processed.
--verbose (Default: false) Prints all messages to standard output.
--stdin (Default: false) Read from stdin
--help Display this help screen.
--version Display version information.
offset (pos. 0) File offset.

Example: 2

Control displaying help, version and errors based on the type of error using the extension methods: IsVersion() or IsHelp()

staticvoidDisplayHelp<T>(ParserResult<T>result,IEnumerable<Error>errs){HelpTexthelpText=null;if(errs.IsVersion())//check if error is version requesthelpText=HelpText.AutoBuild(result);else{helpText=HelpText.AutoBuild(result, h =>{//configure helph.AdditionalNewLineAfterOption=false;h.Heading="Myapp 2.0.0-beta";//change headerh.Copyright="Copyright (c) 2019 Global.com";//change copyright textreturnHelpText.DefaultParsingErrorsHandler(result,h);}, e =>e);}Console.WriteLine(helpText);}

Example: 3

Adding dynamic contents computed at runtime.

//get environment variablestaticFunc<string>dynamicData=()=>{varheader="-------Environment Variables----------";varwindir=Environment.GetEnvironmentVariable("windir");return$"{header}\nwindir={windir}";};staticvoidDisplayHelp<T>(ParserResult<T>result,IEnumerable<Error>errs){varhelpText=HelpText.AutoBuild(result, h =>{h.AddPostOptionsLine(dynamicData());returnh;}, e =>e);Console.WriteLine(helpText);}

Output

Myapp 2.0.0-beta
Copyright (c) 2019 Global.com
-r, --read Input files to be processed.
--verbose (Default: false) Prints all messages to standard output.
--stdin (Default: false) Read from stdin
--help Display this help screen.
--version Display version information.
offset (pos. 0) File offset.
-------Environment Variables----------
windir=C:\Windows

Complete Help Demo Example

Click to expand!
classProgram{staticintMain(string[]args){varparserResult=newParser(c =>c.HelpWriter=null).ParseArguments<Options>(args);returnparserResult.MapResult((Optionsopts)=>newRun(opts),
errs =>Console.WriteLine(DisplayHelp(parserResult)));}staticintDisplayHelp(ParserResult<object>parserResult){Console.WriteLine(HelpText.AutoBuild(parserResult, h =>{h.AdditionalNewLineAfterOption=false;h.Heading="Myapp 2.0.0-beta";//change headerh.Copyright="Copyright (c) 2019 Global.com";//change copyright textreturnh;}));return1;}}classOptions{[Option('r',"read",Required=false,HelpText="Input files to be processed.")]publicIEnumerable<string>InputFiles{get;set;}// Omitting long name, defaults to name of property, ie "--verbose"[Option(Default=false,HelpText="Prints all messages to standard output.")]publicboolVerbose{get;set;}[Option("stdin",Default=false,HelpText="Read from stdin")]publicboolstdin{get;set;}[Value(0,MetaName="offset",HelpText="File offset.")]publiclong?Offset{get;set;}}

Setting AssemblyInfo Attributes

HelpText retrieve AssemblyAttributes values to show header and copyright in help. The next AssemblyAttributes should be set:

If you are using AssemblyInfo.cs, add the following lines:

[assembly:AssemblyTitle("Application Title")][assembly:AssemblyCompany("Company")][assembly:AssemblyCopyright("Copyright")][assembly:AssemblyInformationalVersion("1.0.0-beta")]

An alternative method:

If you are not using AssemblyInfo.cs, Add these lines to the project file, just in PropertyGroup

<PropertyGroup>
...
<Copyright>Copyright_text</Copyright>
<Company>Company_text</Company>
<Version>1.2.3-beta</Version>
<AssemblyTitle>title_text</AssemblyTitle>
</PropertyGroup>

Modify the xml elements based on your values.

The new SDK for msbuild is auto generating an AssemblyInfo file during build including the assemblyAttributes described above.

Note: This PropertyGroup is the same in F# projects .fsproj or vb.net project .vbproj

The version is retrieved from AssemblyInformationalVersionAttribute or the AssemblyVersionAttribute if the former is not defined.

AssemblyInformationalVersionAttribute support Semantic Versioning standard like 1.0.0-beta, 1.0.0-beta.2, 1.0.0-beta.11,1.0.0-rc.1 and 1.0.0.

HelpText use these attributes by default to generate the heading text and copyright text.

Heading and copyright can be modified in custom help by changing the Heading and Copyright properties.

HelpText in V2.7+

A new overload method AutoBuild is added which simplify the Custom Help as given below:

publicstaticHelpTextAutoBuild<T>(ParserResult<T>parserResult,Func<HelpText,HelpText>onError,intmaxDisplayWidth=DefaultMaximumLength)
staticvoidDisplayHelp<T>(ParserResult<T>result){varhelpText=HelpText.AutoBuild(result, h =>{h.AddPostOptionsLine(dynamicData());returnh;});//without the option e=>eConsole.WriteLine(helpText);}

Custom Help for verbs

The overload method of AutoBuild has verbsIndex parameter which enables of displaying help summary for verbs. By default, verbsIndex= false

The syntax of the AutoBuild method is:

publicstaticHelpTextAutoBuild<T>(ParserResult<T>parserResult,Func<HelpText,HelpText>onError,Func<Example,Example>onExample,boolverbsIndex=false,intmaxDisplayWidth=DefaultMaximumLength)

To display custom help for verbs and display help summary:

intDisplayHelp<T>(ParserResult<T>result){varhelpText=HelpText.AutoBuild(result, h =>{h.AdditionalNewLineAfterOption=false;h.Heading="Myapp 2.0.0-beta";//change headerh.Copyright="Copyright (c) 2019 Global.com";//change copyright textreturnh;}, e =>e,verbsIndex:true);//set verbsIndex to display verb help summary.Console.WriteLine(helpText);return-1;}

Example: To display help summary of verbs, run the command:

$ myapp help
#or
$ myapp --help

The Output help text:

Myapp 2.0.0-beta
Copyright (c) 2019 Global.com
add Add files
edit Edit files
help Display more information on a specific command.
version Display version information.

Example: To display help of a verb, run the command:

$ myapp add --help

See also

HelpText API, HelpText

CommandLineParser

Clone this wiki locally