Mapping Properties To Options

Mapping Properties to Options

You can map almost any data type to command line option.

Scalars

Scalar values are mapped using OptionAttribute type. Let's define a string option.

class Options
{
  [Option('p', "person-to-greet", DefaultValue = "World")]
  public string PersonToGreet { get; set; }

  // Version 1.9.4.91+, use char for shortname
  [Option('f', "friend-to-greet", DefaultValue = "Someone")]
  public string FriendToGreet { get; set; }
}

Everything passed to the -p or --person-to-greet option will be loaded into the Options::PersonToGreet instance property. This option is not required (default Required = false), so if not specified the property will contain the string "World".

Both app -p Jhonny and app --person-to-greet Jhonny will be accepted.

You can also map without problems enum (System.Enum) and nullable (Nullabe<T>) values:

enum GreetType
{
  Hello,
  Bye,
  Regards
}

class Options
{
  [Option('g', "greet-type")]
  public GreetType SpecifiedGreetType { get; set; }

  [Option('t', "times-to-greet")]
  public int? TimesToGreet { get; set; }
}

When specifying enum values, you don't need to respect case. Both app -g bye and app --greet-type REGARDS are allowed.

Arrays

To map an array you need to use the OptionArrayAttribute type as in following sample:

class Options
{
  [OptionArray('v', "values", DefaultValue = new double[] {.1, .2, .3})]
  public double[] Temperatures { get; set; }
}

You can even specify a default when working with an array. All values specified after an OptionArray will be loaded into the array.

$ app -v 1.9 2.3 5.3 12.4 9.1334
$ app --values 192.9 .3 1.23 .324 3.3323

The parser is culture-sensitive. If you would like to subordinate the parsing process to a particular culture, just change the current thread culture:

Thread.CurrentThread.CurrentCulture = new CultureInfo("en-US");

Lists

The OptionListAttribute allows you to explicitly manage a list of strings from command line. The following target class:

class Options
{
  [OptionList('t', "tags")]
  public IList<string> Tags { get; set; }
}

will let accept a command line like these ones:

$ app -t csharp:vbnet:cpp
$ app -tpython:ruby
$ app --tags nodejs:sinatra:nancyfx:fubumvc

Lists are also used to capture all values not parsed as options. This job is done by ValueListAttribute.

class Options
{
  [Option('p', "person-to-greet", DefaultValue = "World")]
  public string PersonToGreet { get; set; }

  [ValueList(typeof(List<string>), MaximumElements = 2)]
  public IList<string> OtherStuff { get; set; }
}

Typing the following at command line:

$ app -p Someone Chair Table Pen

the parser will collect the string "Someone" in Options::PersonToGreet and other values ("Chair", "Table" and "Pen") in Options::OtherStuff.

Implicit Name

Now if you use the Option parameterless constructor, the library infers it from the property name (and acquires in lower case).

class Options
{
  [Option]
  public bool Verbose { get; set; } // --verbose

  [Option('q')]
  public bool Quiet { get; set; }   // -q
}