Skip to content
This repository has been archived by the owner on Jun 27, 2022. It is now read-only.

Generic reader

Jump to bottom
Craig Fowler edited this page Jan 27, 2017 · 1 revision

Generic parameter reader

The generic parameter reader is best-suited to most applications which need to read parameters from the command-line.

This reader allows you to design your own C♯ class (a POCO). When the parameters are parsed, the reader constructs an instance of your class and sets its properties with appropriate values from the parameters. Your application may then consume this class as it sees fit.

The parameters class

There are a few simple restrictions upon the design of your parameters class:

  • It must be a class (not a struct)
  • It must not be abstract
  • It must have a parameterless constructor
  • An implied parameterless constructor (IE: the class has no constructors explicitly defined) is also OK
  • The properties which will hold the parsed parameter values must be settable

Creating a parser builder

Creating a generic parser builder is simple, just new one up:

// using CSF.Cli.Parameters;
var builder = new ParameterParserBuilder<MyParamsClass>();

In this example, MyParamsClass is your parameters class.

Registering your parameters

With a builder instance, the next step is to tell it about which parameters you expect to see on the command-line. Each parameter is associated with a property of the parameters class; upon parsing, the value for that parameter will be set into the corresponding property. There are three methods on the builder, provided for registering parameters:

  • AddFlag
  • AddValue
  • RemainingArguments

Please read the corresponding wiki page for an in-depth look at what flags & value parameters, as well as remaining arguments mean.

For each of these three methods, the first parameter is an expression which indicates the corresponding property of the parameters class, which will receive the value of this parameter.

For flags and value parameters, there are two optional parameters on the registration method which facilitate the specification of long and short parameter names. Whilst both naming parameters are optional, either at least one short name or at least one long name must be provided. These naming parameters may be used to provide a single name (the most common choice), or a collection of string names.

AddFlag

The AddFlag method is used the following manner:

builder.AddFlag(x => x.MyBooleanProperty,
                shortName: "f",
                longName: "flag");

When parsed, if the flag is present then the property of the parameters class will be set to true. If the flag is not present then the property will not be changed. Note that the property will not be explicitly set to false if the command-line parameter is not present.

AddValue

To declare a value parameter, use the AddValue registration method as follows:

builder.AddValue(x => x.MyStringProperty,
                 shortName: "v",
                 longName: "my-value",
                 optional: true);

The optional parameter is itself optional (defaulting to true). If it is set to true, then it indicates that this is a value-optional command-line parameter.

When parsed, value parameters have the following effect upon the property of the parameters class.

  • If the parameter is not present then the property value is left unchanged.
  • If the parameter is present, has no associated value and the parameter was registered as optional then the property value is set to an empty string.
  • If the parameter is present, has no associated value and the parameter was not registered as optional then the value is left unchanged (as if the parameter was not present).
  • If the parameter is present and has an associated value then the parameter is set to that value.

Thus, it is best to initialise all of the parameters class value properties to null. This permits easy distinction between "parameter not present", "parameter present with no value" and "parameter present with value".

RemainingArguments

To nominate a property of the parameters class to receive the remaining arguments, use the following syntax:

builder. RemainingArguments(x => x.MyListProperty);

The specified property must implement IList<string>. When the parameters are parsed, this property will receive the remaining arguments.

Build the parser

Once all of your parameters are registered, you may build a parser/reader instance from the builder. This is one line of code:

var reader = builder.Build();

Read parameters

Finally, the reader instance is used to read your parameters. The arguments must be an IList<string> (a string array is fine).

// 'args' is an IList<string>
var myParameters = reader.Parse(args);

The output received from the Parse method is an instance of your parameters class.

Clone this wiki locally