This project is read-only.

Command line arguments

Command line arguments are passed to your application when it is started, and are typically accessed through the parameter of the static void Main(string[] args) method (Shared Sub Main(ByVal args() As String) in Visual Basic). This provides with the arguments as an array of strings, which is not terribly useful. What Ookii.CommandLine allows you to do is to convert that array of strings into a strongly typed set of named values, which are stored in the properties of the class that was used to define the arguments.

The method used to extract values from the array of string arguments is determined by the command line argument parsing rules. Ookii.CommandLine uses parsing rules that are very similar to how Microsoft PowerShell parses arguments for cmdlets, so if you have used PowerShell these rules will be familiar with you.

Command line arguments follow the name of your application on the command prompt, and typically take the following form:

-ArgumentName ArgumentValue


The argument name is preceded by the argument name prefix. This prefix is configurable, but Ookii.CommandLine defaults to accepting a forward slash (/) and a dash (-) on Windows, and only a dash (-) on other platforms (other platforms are supported through Mono).

The argument value follows the name, separated either by a space or a colon (:). Not all arguments require values; those that do not are called switch arguments and have a value determined by their presence or absence on the command line.

An argument can have one or more aliases: alternative names that can also be used to specify the command name. For example, a parameter named “Verbose” might use the alias “v” as a shorter to type alternative.

Positional arguments

An argument can be positional, which means that its value can be specified either by name as indicated above, or by position. In this case the name of the argument is not required, and the argument’s value can be supplied by specifying it in the correct position in relation to other positional arguments.

If an argument value is encountered without being preceded by a name, it is matched to the positional argument at the current position. For example, take the following command line arguments:

Value1 –ArgumentName Value2 Value3


In this case, Value1 is not preceded by a name; therefore it is matched to the first positional argument. Value2 follows a name, so it is matched to the argument with the name “ArgumentName”. Finally, Value3 is matched to the second positional argument.

A positional argument can still be supplied by explicitly supplying its name. If a positional argument is supplied by name, it cannot also be specified by position; in the previous example, if the argument named “ArgumentName” was the second positional argument, then Value3 becomes the value for the third positional argument, because the value for “ArgumentName” was already specified by name.

Required arguments

A command line argument that is required must be present on all invocations of the application. If a required argument is not present, the CommandLineParser class will throw an exception during parsing.

Any argument can be made required. Usually it is recommended for any required argument to also be a positional argument, but this is not necessary.

For positional arguments, required arguments must always come before optional arguments; it is an error to define a required argument after an optional argument.

Arguments with multiple values

Some arguments can take multiple values; these are multi-value arguments, also known as array arguments. These arguments can be supplied multiple times, and each value is added to the set of values. For example, consider the following command line arguments:

-ArgumentName Value1 –ArgumentName Value2 –ArgumentName Value3


In this case, the value of the argument named “ArgumentName” will be a list holding all three values.

The type of a multi-value argument must be an array type, for example string[] or int[] in C#, or any type implementing ICollection<T> when the argument is defined by a read-only property.

It’s possible to specify a separator for multi-value arguments using the MultiValueSeparatorAttribute attribute. This makes it possible to specify multiple values for the argument while the argument itself is specified only once. For example, if the separator is set to a comma, you can specify the values as follows:

-ArgumentName Value1,Value2,Value3


In this case, the value of the argument named “ArgumentName” will be a list with the three values “Value1”, “Value2” and “Value3”.

Note: if you specify a separator for a multi-value argument, it is not possible to have an argument value containing the separator. There is no way to escape the separator. Therefore, make sure you pick a separator that will never be used in the argument values, and be extra careful with culture-sensitive argument types (for example, if you use a comma as the separator for a multi-value argument of floating point numbers, cultures that use a comma as the decimal separator will not be able to specify values properly).

If an argument is not a multi-value argument, it is an error to supply it more than once, unless duplicate arguments are allowed in which case only the last value is used.

If a multi-value argument is positional, it must be the last positional argument. All remaining positional argument values will be considered values for the multi-value argument.

If a multi-value argument is required, it means it must have at least one value.

Dictionary arguments

Dictionary arguments are multi-value arguments that specify a set of key/value pairs. Each value for a dictionary argument takes the form key=value, like in the following example:

-ArgumentName Key1=Value1 –ArgumentName Key2=Value2


In this case, the value of the argument named “ArgumentName” will be a dictionary with two keys, Key1 and Key2, with the associated values Value1 and Value2 respectively.

A dictionary argument must have a type of Dictionary<TKey, TValue> where TKey and TValue are the types of the key and value. When using a read-only property to define the argument, you can use any type that implements IDictionary<TKey, TValue>.

If you specify the same key more than once an exception will be thrown unless the AllowDuplicateDictionaryKeysAttribute attribute is specified on the constructor parameter or property that defines the dictionary argument.

Switch arguments

A switch argument is an argument with a Boolean type (bool in C#). Its value is determined by its presence or absence on the command line; the value will be true if the argument is supplied, and false if not. The following arguments set the switch argument named “switch” to true:

-switch


A switch argument’s value can be specified explicitly, as in the following example:

-switch:true


You must use a colon to specify an explicit value for a switch argument; you cannot use white space to separate the name and the value.

If you use a nullable Boolean type (bool? In C#) as the type of the argument, it will be null if omitted, true if supplied, and false only if explicitly set to false using -switch:false.

If the type of the argument is an array of Boolean values, it will act as a multi-value argument and a switch. A value of true (or the explicit value if one is given) gets added to the array for every time that the argument is supplied.

Argument value conversion

Ookii.CommandLine allows you to define arguments with any .Net type, including types such as System.String, System.Int32, System.DateTime, and many more. Any type can be used; the only requirement is that it is possible to convert a string value to that type.

The .Net Framework provides a very flexible method for converting one type to another through the System.ComponentModel.TypeConverter class. You can use any type that has a type converter than can convert from a string for a command line argument. Most built-in types in .Net Framework have such a type converter. You can also use your own types by creating a type converter for that type.

It is possible to override the default conversion by specifying a custom type converter using the System.ComponentModel.TypeConverterAttribute. When this attribute is applied to a constructor parameter or property that defines an argument, the specified type converter will be used for conversion instead. Note that for multi-value, dictionary and nullable value-type arguments the converter must be for the element type (e.g. if the argument is a multi-value argument of type int[], the type converter must be able to convert to int). For a dictionary argument the element type is KeyValuePair<TKey, TValue>, and the type converter is responsible for parsing the key and value from the argument value.

For many types, the conversion can be culture dependent. For example, converting numbers or dates depends on the culture which defines the accepted formats and how they’re interpreted; some cultures might use a period as the decimal separators, while others use a comma.

The culture used for argument value conversions is specified the CommandLineParser.Culture property, which defaults to the current culture. If you wish your argument parsing to be independent of the user’s culture, set this property to System.Globalization.CultureInfo.InvariantCulture.

Last edited Feb 6, 2013 at 11:39 AM by SvenGroot, version 3

Comments

No comments yet.