GetOpts 0.3.0

A command line argument parser that is able to extract pre-defined options from supplied arguments.

Install-Package GetOpts -Version 0.3.0
dotnet add package GetOpts --version 0.3.0
paket add GetOpts --version 0.3.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

The main namespace of this library is DD.GetOpts.

First we need to define the required options:

var option1 = new Option( "a", "alpha", Argument.NONE, Occur.ONCE );
var option2 = new Option( "b", "beta", Argument.REQUIRED, Occur.OPTIONAL );
var option3 = new Option( "g", "gamma", Argument.OPTIONAL, Occur.MULTIPLE );

Every option consists a short and long name, as well as various occurrence and argument rules. A short name has to prefixed with a - in the supplied arguments while a long name has to be prefixed with a --. In the above example option1 can be parsed either via -a or --alpha. The argument rules of the above options are as follows:

  • option1 doesn't have an argument (Only -a or --alpha are valid).
  • option2 requires and argument (Only -b argument or --beta argument are valid).
  • option3 can either have an argument or omit it.

The occurance rules of the above options are as follows:

  • option1 must occur exactly once in the provided arguments.
  • option2 can occur once in the provided arguments but doesn't have to.
  • option3 can occur multiple times in the provided arguments but doesn't have to.

The next step is to add these options to the Options collection.

var options = new Options();
options.Add( option1 ).Add( options2 ).Add( options3 );

Options inherits IEnumerable so it can be iterated:

foreach ( var option in options ) {
    Console.WriteLine( $"Included Option: {option}" );
}

Now we are ready to parse command line arguments. In the following snippet we assume args is string[] provided by the Main method:

var matches = options.Parse( args );

Should a supplied argument not match any Option in the Options collection then the method will throw a ArgumentException with a detailed description. The exception are free-standing arguments without a short or long prefix. The return value of the Parse() method is a IEnumerable where T is Match. Let's assume we parsed first -a -g foo -g bar last then the result would include three matches. The first one for the free standing arguments first and last, the second for -a, and the third for -g. A Match has the following properties:

  • ShortName: The short name of the matched option (In this example either a or g).
  • LongName: The long name of the matched option (In this example either alpha or gamma).
  • Count: The number of times the Option was matched. (1 for a and 2 for g ).
  • Arguments: The read-only collection of all arguments supplied to the matched options. (Empty for a but would contain foo and bar for g).

A match for free-standing arguments doesn't have a ShortName or LongName. The Count is set to the amount of free-standing arguments. Arguments will be a list of all free-standing arguments encountered (In this case "first" and "last").

The best way to query the matches is by using Linq extensions:

// Get all arguments for -g/--gamma
var arguments = matches.Where( x => x.ShortName == "g" ).First().Arguments;

The default option prefixes - and -- can be changed to something else during the initialization of Options:

var options = new Options( "/", "//" );

Now short-name options would have to be prefixed with / and long-name options with // instead of - and --.

The main namespace of this library is DD.GetOpts.

First we need to define the required options:

var option1 = new Option( "a", "alpha", Argument.NONE, Occur.ONCE );
var option2 = new Option( "b", "beta", Argument.REQUIRED, Occur.OPTIONAL );
var option3 = new Option( "g", "gamma", Argument.OPTIONAL, Occur.MULTIPLE );

Every option consists a short and long name, as well as various occurrence and argument rules. A short name has to prefixed with a - in the supplied arguments while a long name has to be prefixed with a --. In the above example option1 can be parsed either via -a or --alpha. The argument rules of the above options are as follows:

  • option1 doesn't have an argument (Only -a or --alpha are valid).
  • option2 requires and argument (Only -b argument or --beta argument are valid).
  • option3 can either have an argument or omit it.

The occurance rules of the above options are as follows:

  • option1 must occur exactly once in the provided arguments.
  • option2 can occur once in the provided arguments but doesn't have to.
  • option3 can occur multiple times in the provided arguments but doesn't have to.

The next step is to add these options to the Options collection.

var options = new Options();
options.Add( option1 ).Add( options2 ).Add( options3 );

Options inherits IEnumerable so it can be iterated:

foreach ( var option in options ) {
    Console.WriteLine( $"Included Option: {option}" );
}

Now we are ready to parse command line arguments. In the following snippet we assume args is string[] provided by the Main method:

var matches = options.Parse( args );

Should a supplied argument not match any Option in the Options collection then the method will throw a ArgumentException with a detailed description. The exception are free-standing arguments without a short or long prefix. The return value of the Parse() method is a IEnumerable where T is Match. Let's assume we parsed first -a -g foo -g bar last then the result would include three matches. The first one for the free standing arguments first and last, the second for -a, and the third for -g. A Match has the following properties:

  • ShortName: The short name of the matched option (In this example either a or g).
  • LongName: The long name of the matched option (In this example either alpha or gamma).
  • Count: The number of times the Option was matched. (1 for a and 2 for g ).
  • Arguments: The read-only collection of all arguments supplied to the matched options. (Empty for a but would contain foo and bar for g).

A match for free-standing arguments doesn't have a ShortName or LongName. The Count is set to the amount of free-standing arguments. Arguments will be a list of all free-standing arguments encountered (In this case "first" and "last").

The best way to query the matches is by using Linq extensions:

// Get all arguments for -g/--gamma
var arguments = matches.Where( x => x.ShortName == "g" ).First().Arguments;

The default option prefixes - and -- can be changed to something else during the initialization of Options:

var options = new Options( "/", "//" );

Now short-name options would have to be prefixed with / and long-name options with // instead of - and --.

  • .NETStandard 2.0

    • No dependencies.

Version History

Version Downloads Last updated
0.3.0 121 6/3/2018
0.2.0 115 5/30/2018
0.1.0 121 5/21/2018