Static class: RT.CommandLine.CommandLineParser

Assembly: RT.CommandLine, Version=1.0.0.9999, 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), must have CommandLineAttribute, and it must have a parameterless constructor (unless it has subcommands, see below).
Every field in the class must have one of the following custom attributes:
- IsPositionalAttribute (allowed for all supported types except bool) — specifies that the parameter is positional; the user specifies the value(s) in place without an option preceding it.
- OptionAttribute (allowed for all supported types) — specifies that the parameter invoked by an option, e.g. -x, which may or may not be followed by a value. (This does not imply that the parameter is necessarily optional.)
- EnumOptionsAttribute (allowed for enum types only) — specifies that the parameter can be invoked by one of several options, which are specified on the enum values in the enum type.
- IgnoreAttribute — specifies that CommandLineParser shall completely ignore the field.
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 positional parameter.
- bool. The field must have an OptionAttribute and cannot be positional or mandatory.
- 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. -f plain or -f 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 or IgnoreAttribute). 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 is provided in one of the following ways:
- Monolingual, translation-agnostic (unlocalizable) applications use the DocumentationAttribute to specify documentation directly.
- Translatable applications must declare methods with the following signature:
```
static string FieldNameDoc(Translation)
```
  The first parameter must be of the same type as the object passed in for the applicationTr parameter of CommandLineParser.Parse<TArgs>(string[], TranslationBase, Func<ConsoleColoredString, ConsoleColoredString>). The name of the method is the name of the field or enum value followed by Doc. The return value is the translated string.
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.

Subcommands can be implemented by using derived classes. For example, in order to allow the user to invoke commands of the following form:

MyTool.exe create new_item
MyTool.exe rename old_name new_name

you would declare the following classes:

[CommandLine]
abstract class CmdBase { }

[CommandName("create")]
sealed class CmdCreate : CmdBase
{
    [IsPositional, IsMandatory]
    public string ItemName;
}

[CommandName("rename")]
sealed class CmdRename : CmdBase
{
    [IsPositional, IsMandatory]
    public string OldName;
    [IsPositional, IsMandatory]
    public string NewName;
}

In this example, we have omitted the documentation attributes, but in practice they would be required. The following points are of note here:

The class CmdBase is abstract to indicate that the subcommand is mandatory. The class could be made non-abstract to indicate that the subcommand is optional.
The class CmdBase does not need to have a parameterless constructor because only CmdCreate and CmdRename would actually be instantiated by CommandLineParser. However, if it were non-abstract, it would need a parameterless constructor.
Parameters that pertain to all subcommands can be added in CmdBase and the user would specify those before the command name.
You can have any arbitrary multi-level class hierarchy. Only classes marked with CommandNameAttribute become subcommands.

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.
TArgs	Parse<TArgs>(string[] args, TranslationBase applicationTr = null, 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, TranslationBase applicationTr = null, Translation cmdLineTr = null, 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, Type applicationTrType)	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[]).