Parameters - DoctorKrolic/ArgumentParsing GitHub Wiki

Parameters are unbound values, which are captured from arguments based on parameters' indices. There are two kinds of parameters: ordinal parameters and remaining parameters.

Ordinal parameters represent separate values at their positions. In order to declare an ordinal parameter C# property in options type is annotated with [Parameter(index)] attribute from ArgumentParsing namespace, where index is an actual index of the parameter, e.g.:

using ArgumentParsing;

[OptionsType]
class Options
{
    [Parameter(0)]
    public string Parameter1 { get; set; }

    [Parameter(1)]
    public string Parameter2 { get; set; }
}

With this setup the following behavior is applied:

Parameters are captured from unbound arguments, i.e. areguments, that are not option names and option values. As a consequence, when there are no options declared, parameters are bound to arguments' indices directly, i.e. paramater with index 0 binds to the first argument, parameter with index 1 binds to the second one and so on. When there is at least one option, there is no straight forward connection between parameters' and arguments' indices, e.g.:

using ArgumentParsing;

[OptionsType]
class Options
{
    [Option('o')]
    public string Option { get; set; }

    [Parameter(0)]
    public string Parameter1 { get; set; }

    [Parameter(1)]
    public string Parameter2 { get; set; }
}

With this setup the following behavior is applied:

Ordinal parameters support the same base type and nullable types as options do. Parse strategies are mostly the same as well: string parameters are directly captured, char parameters are captured with a length check and parameters of other types are parsed with error recovery. Nullable parameters hold the same semantics as nullable options: if a nullable parameter isn't specified, it is null, otherwise it has a value of an underlying type.

The only difference is with bool and bool? parameters. These types behave specially when it comes to options, but as parameters they are just yet another parsable types. So if you declare a bool parameters, arguments "true" and "false" are gonna be mapped to respetive bool values.

Similarly to options, ordinal parameters can be made required. Same as for options, this is done by making parameter's property required or annotating it with [System.ComponentModel.DataAnnotations.Required] attribute. If a required parameter is missing, MissingRequiredParameterError is reported.

There is one additional rule for required parameters though. Let's say we have 3 parameters. Parameter with index 2 is required. Given required semantics, this means, that in all valid cases parameter 2 must be present. Since parameters are ordinal, this in its turn implies, that parameters 0 and 1 are also always present in all valid scenarios, making them implicitly required as well. The design choice here is to avoid implicit/hidden behavior patterns, thus the library demands parameters 0 and 1 to be explicitly required by producing an error diagnostic, if that rule is not satisfied.

Ordinal parameters have names. Name of an ordinal parameter can be assigned via Name property of [Parameter] attribute. If name is not specified, generator will automatically assign it as a C# property name in lower kebab case. Parameter names are used in parse errors messages and in default help screen.

Remaining parameters are another kind of parameters. They represent all parameters after ordinals parameters are over. Despite the name remaining parameters are represented as a single C# property, which captures all of them. Thus, it must be of a valid sequence type. In order to declare remaining parameters property it is annotated with [RemainingParameters] attribute from ArgumentParsing namespace. So in the simplest from remaining parameters can be declared as:

using ArgumentParsing;
using System.Collections.Immutable;

[OptionsType]
class Options
{
    [RemainingParameters]
    public ImmutableArray<string> RemainingParams { get; set; }
}

In this example RemainingParams are just gonna capture all arguments into an immutable array with the exception of built-in error recovery of option names.

Here is an example of how remaining parameters work with ordinal ones:

using ArgumentParsing;
using System.Collections.Immutable;

[OptionsType]
class Options
{
    [Parameter(0)]
    public string Param1 { get; set; }

    [Parameter(1)]
    public string Param2 { get; set; }

    [RemainingParameters]
    public ImmutableArray<string> RemainingParams { get; set; }
}

With this setup the following behavior is applied:

Parsing of underlying remaining parameters' types is the same as for ordinal parameters including bool and bool? types.