Static class: RT.CommandLine.CommandLineParser

Assembly: RT.CommandLine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
Namespace: RT.CommandLine

Summary

Implements a command-line parser that can turn the commands and options specified by the user on the command line into a strongly-typed instance of a specific class. See remarks for more details.

Remarks

The following conditions must be met by the class wishing to receive the options and parameters:

It must be a reference type (a class) and it must have a parameterless constructor.
Field with any of the following custom attributes are processed by CommandLineParser:
- IsPositionalAttribute (allowed for all supported types except bool) — specifies that the field is a positional parameter; the user specifies this as a single parameter without any extra syntax.
- OptionAttribute (allowed for all supported types except abstract classes) — specifies that the field is a parameter invoked by an option, e.g. -x. (This does not imply that the parameter is necessarily optional.)
- EnumOptionsAttribute (allowed for enum types only) — specifies that the field is a parameter that can be invoked by one of several options, which are specified on the enum values in the enum type.
- Any field that has none of those three is completely ignored.
Each field may optionally have any of the following custom attributes:
- IsMandatoryAttribute (allowed for all supported types except bool) — specifies that the parameter must be specified by the user. For a string[] field, it means that at least one value must be specified.
- UndocumentedAttribute — specifies that the option or command does not appear in the help screen generated by CommandLineParser.
Each field in the class must be of one of the following types:
- string, any integer type, float, double, or any nullable version of these. The field can be positional (IsPositionalAttribute) or not (OptionAttribute).
- string[]. The field can be positional (IsPositionalAttribute) or not (OptionAttribute), but if it is positional, it must be the last field in the class.
- bool. The field must have an OptionAttribute and cannot be positional or mandatory.
- An abstract class with the CommandGroupAttribute. The field must be the last field in the class and must be marked positional (IsPositionalAttribute). The abstract class must have at least two derived classes, each with a CommandNameAttribute.
- Any enum type. There are three ways that enum types can be used. To explain these, the following enum type declaraction is used as an example:
```
enum OutputFormat { PlainText, Xml }
```
  - IsPositionalAttribute — The user can specify a single parameter (e.g. plain or xml) to select an enum value. Every value in the enum type must have a CommandNameAttribute to specify the name by which that enum value is selected:
```
enum OutputFormat
{
    [CommandName("plain")]
    PlainText,
    [CommandName("xml")]
    Xml
}
```
  - OptionAttribute — The user can select an enum value by specifying an option followed by a parameter that identifies the enum value (e.g. -x plain or -x xml). As above, every value in the enum type must have a CommandNameAttribute to specify the name by which that enum value is selected.
  - EnumOptionsAttribute — The user can select an enum value by specifying just an option (e.g. -p or -x). Every value in the enum type must have an OptionAttribute to specify the option by which that enum value is selected:
```
enum OutputFormat
{
    [Option("-p", "--plain")]
    PlainText,
    [Option("-x", "--xml")]
    Xml
}
```
    A parameter on the attribute determines whether the user is allowed to specify only one enum value or multiple (which will be combined using bitwise or).
  - If the field is optional, the enum value that corresponds to the field’s initial (default) value may omit the CommandNameAttribute or OptionAttribute.
Every field must have documentation or be explicitly marked with UndocumentedAttribute, except for fields that use EnumOptionsAttribute. For every field whose type is an enum type, the values in the enum type must also have documentation or UndocumentedAttribute, except for the enum value that corresponds to the field’s default value if the field is not mandatory.
Documentation can be provided in one of the following ways:
- Use DocumentationAttribute to specify unformatted text directly.
- Use DocumentationEggsMLAttribute or DocumentationRhoMLAttribute to format your text with coloration using one of the two markup systems.
IsPositionalAttribute and IsMandatoryAttribute can be used together. However, a positional field can only be made mandatory if all the positional fields preceding it are also mandatory.

SectionAttribute can be used to split the help screen into sections with headers for better readability.

Static methods

ConsoleColoredString	Colorize(RhoElement text)	Converts the specified RhoML parse tree into a console colored string according to CommandLineParser-specific rules. This method is used to convert DocumentationRhoMLAttribute documentation into colored text. See Remarks. (see also remarks)
ConsoleColoredString	Colorize(EggsNode text)	Converts the specified EggsML parse tree into a console colored string using the rules described in EggsNode.ToConsoleColoredStringWordWrap(int, int). This method is used to convert DocumentationEggsMLAttribute documentation into colored text, as well as any documentation using the legacy DocumentationLiteralAttribute.
ConsoleColoredString	GenerateHelp<TArgs>(int? wrapWidth = null, Type subType = null, Func<ConsoleColoredString, ConsoleColoredString> helpProcessor = null)	Generates the help screen for this command line.
TArgs	Parse<TArgs>(string[] args, Func<ConsoleColoredString, ConsoleColoredString> helpProcessor = null)	Parses the specified command-line arguments into an instance of the specified type. See the remarks section of the documentation for CommandLineParser for features and limitations.
TArgs	ParseOrWriteUsageToConsole<TArgs>(string[] args, Func<ConsoleColoredString, ConsoleColoredString> helpProcessor = null)	Parses the specified command-line arguments into an instance of the specified type. In case of failure, prints usage information to the console and returns `default(TArgs)`. See the remarks section of the documentation for CommandLineParser for features and limitations.
void	PostBuildStep<TArgs>(IPostBuildReporter rep)	Performs safety checks to ensure that the structure of your command-line syntax defining class is valid according to the criteria laid out in the documentation of CommandLineParser. Run this method as a post-build step to ensure reliability of execution. For an example of use, see PostBuildChecker.RunPostBuildChecks(string, params Assembly[]).