CommandLineSwitchParser 1.0.0

This is a simple parser for command line options on .NET Framewrok & .NET Core.
What you should do is only define your option class and write code like "var option = CommandLineSwicth.Parse<YourOptionClass>(ref args);".
There is no need to annotate your option class with any attributes.

Install-Package CommandLineSwitchParser -Version 1.0.0
dotnet add package CommandLineSwitchParser --version 1.0.0
<PackageReference Include="CommandLineSwitchParser" Version="1.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add CommandLineSwitchParser --version 1.0.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

CommandLineSwitchParser NuGet Package Build status

Summary

This is a simple parser for command line options on .NET Framework & .NET Core.

What you should do is only define your option class and write code like "var option = CommandLineSwitch.Parse&lt;YourOptionClass&gt;(ref args);".

There is no need to annotate your option class with any attributes.

eye catch

Install

PM> Install-Package CommandLineSwitchParser

Example

This library provides CommandLineSwitch.Parse&lt;T&gt;() static method.

// Open name space.
using CommandLineSwitchParser;
...

// Declare your own class that represents a command line switch.
public class Option1
{
    public bool Recursive { get; set; }

    public int Port { get; set; } = 8080;
}

// if args is "--port 80 c:\wwwroot\inetpub -r", then ...
public static void Main(string[] args)
{
  var options = CommandLineSwitch.Parse<Option1>(ref args);

  // Short switch matches an initial of option class property name.
  Console.WriteLine(options.Recursive); // True

  // Long switch matches a full name of option class property name.
  Console.WriteLine(options.Port);     // 80

  // Switches in "args" are stripped.
  Console.WriteLine(args[0])           // "c:\wwwroot\inetpub"
}

This library also provides CommandLineSwitch.TryParse&lt;T&gt;() static method, too.

  if (CommandLineSwitch.TryParse<Option1>(ref args, out var options, out var err)){
    // Success!
  }

Command line switches/options naming convention

  • All properties of option class are mapped to lowercase option name.
  • A full property name with converted to lower case is mapped to long name starts with a double hyphen ("--").
  • An initial of property name with converted to lower case is mapped to short name starts with single hyphen ("-").
public class Option1
{
    public bool Recursive { get; set; }
      // -> mapped to "-r" and "--recursive"

    public int Port { get; set; }
      // -> mapped to "-p" and "--port"
}
  • If the option class has some properties those are same initials, those properties aren't mapped to short name. Those properties are mapped only long name.
// In this case, short name "-a" is unavailable.
public class Option2
{
    public bool AutoGenerate { get; set; }
      // -> mapped to only "--autogenerate"

    public int Align { get; set; }
      // -> mapped to only "--align"
}
  • You can use "enum" type in properties of option class.
  • "enum" values are also mapped to lower case symbols.
public enum {
  Left,
  Center,
  Right
}

public class Option3
{
    public int Align { get; set; }
      // -> mapped to "-a" and "--align", 
      //    and this option can specify with 
      //    one of the "left", "center", "right".
}

Parsing error handling

If CommandLineSwitch.Parse&lt;T&gt;() encountered invalid syntax command line arguments, it throws InvalidCommandLineSwitchException exception.

You can retrieve the details of parsing error from ParserError property of the InvalidCommandLineSwitchException exception object.

// The option class has not "-x" switch/option.
public class Option1
{
    public bool Recursive { get; set; }

    public int Port { get; set; }
}

// if args is new []{"-x"} ...
try {
  var option = CommandLineSwitch.Parse<Option1>(ref args);
    // -> it throw exception!
}
catch (InvalidCommandLineSwitchException e){
  // You can access "e.ParserError" property
  // to retrieve details of the error.
}

CommandLineSwitch.TryParse&lt;T&gt;() return false when it encountered invalid command line arguments instead of throwing exception.

You can retrieve the details of parsing error from 3rd output argument of CommandLineSwitch.TryParse&lt;T&gt;() method.

// if args is new []{"-x"} ...

if (CommandLineSwitch.TryParse<Option1>(ref args, out var option, out var err) == false){
  // -> it returns false.
  // You can access "err" output variable
  // to retrieve details of the error.
}

The parsing error information is provided by CommandLineSwitchParserError class.

CommandLineSwitchParserError class exposes the following properties:

Property type and name | Description
-----------------------|-------------
ErrorTypes ErrorType | It represents the reason of parsing error.
string OptionName | The option name that causes parsing error.
string Parameter | The option parameter that causes parsing error.
Type ExpectedParameterType | The .NET type that expected to option parameter.

ErrorType take the one of ErrorTypes enum values the following:

  • UnknownOption
  • MissingParameter
  • InvalidParameterFormat
  • ParameterOverflow

When the parsing error occurred:

  • It returns only one of the first parsing error.
  • The command line arguments are not stripped.

FAQ

Questions

  • Is there any way to setup custom option name?
  • Can I get "usage" document automatically generated?
  • Can I use "/" instead of "-" ?
  • Can I use "-name=value" syntax instead of "-name value" ?
  • Can I use "-ab" syntax instead of "-a -b" ?

Answer

Sorry, no way.

I'm interested in keeping this library to simple usage.
That is the most important reason I created this library despite there are already numerous command line parsing libraries.

So I have no plan at this time.

If you need those features, you may consider using Microsoft.Extensions.CommandLineUtils (see also), or choose one of the many libraries published on NuGet that was tagged with "commandline" (search result is here).

License

Mozilla Public License, version 2.0

CommandLineSwitchParser NuGet Package Build status

Summary

This is a simple parser for command line options on .NET Framework & .NET Core.

What you should do is only define your option class and write code like "var option = CommandLineSwitch.Parse&lt;YourOptionClass&gt;(ref args);".

There is no need to annotate your option class with any attributes.

eye catch

Install

PM> Install-Package CommandLineSwitchParser

Example

This library provides CommandLineSwitch.Parse&lt;T&gt;() static method.

// Open name space.
using CommandLineSwitchParser;
...

// Declare your own class that represents a command line switch.
public class Option1
{
    public bool Recursive { get; set; }

    public int Port { get; set; } = 8080;
}

// if args is "--port 80 c:\wwwroot\inetpub -r", then ...
public static void Main(string[] args)
{
  var options = CommandLineSwitch.Parse<Option1>(ref args);

  // Short switch matches an initial of option class property name.
  Console.WriteLine(options.Recursive); // True

  // Long switch matches a full name of option class property name.
  Console.WriteLine(options.Port);     // 80

  // Switches in "args" are stripped.
  Console.WriteLine(args[0])           // "c:\wwwroot\inetpub"
}

This library also provides CommandLineSwitch.TryParse&lt;T&gt;() static method, too.

  if (CommandLineSwitch.TryParse<Option1>(ref args, out var options, out var err)){
    // Success!
  }

Command line switches/options naming convention

  • All properties of option class are mapped to lowercase option name.
  • A full property name with converted to lower case is mapped to long name starts with a double hyphen ("--").
  • An initial of property name with converted to lower case is mapped to short name starts with single hyphen ("-").
public class Option1
{
    public bool Recursive { get; set; }
      // -> mapped to "-r" and "--recursive"

    public int Port { get; set; }
      // -> mapped to "-p" and "--port"
}
  • If the option class has some properties those are same initials, those properties aren't mapped to short name. Those properties are mapped only long name.
// In this case, short name "-a" is unavailable.
public class Option2
{
    public bool AutoGenerate { get; set; }
      // -> mapped to only "--autogenerate"

    public int Align { get; set; }
      // -> mapped to only "--align"
}
  • You can use "enum" type in properties of option class.
  • "enum" values are also mapped to lower case symbols.
public enum {
  Left,
  Center,
  Right
}

public class Option3
{
    public int Align { get; set; }
      // -> mapped to "-a" and "--align", 
      //    and this option can specify with 
      //    one of the "left", "center", "right".
}

Parsing error handling

If CommandLineSwitch.Parse&lt;T&gt;() encountered invalid syntax command line arguments, it throws InvalidCommandLineSwitchException exception.

You can retrieve the details of parsing error from ParserError property of the InvalidCommandLineSwitchException exception object.

// The option class has not "-x" switch/option.
public class Option1
{
    public bool Recursive { get; set; }

    public int Port { get; set; }
}

// if args is new []{"-x"} ...
try {
  var option = CommandLineSwitch.Parse<Option1>(ref args);
    // -> it throw exception!
}
catch (InvalidCommandLineSwitchException e){
  // You can access "e.ParserError" property
  // to retrieve details of the error.
}

CommandLineSwitch.TryParse&lt;T&gt;() return false when it encountered invalid command line arguments instead of throwing exception.

You can retrieve the details of parsing error from 3rd output argument of CommandLineSwitch.TryParse&lt;T&gt;() method.

// if args is new []{"-x"} ...

if (CommandLineSwitch.TryParse<Option1>(ref args, out var option, out var err) == false){
  // -> it returns false.
  // You can access "err" output variable
  // to retrieve details of the error.
}

The parsing error information is provided by CommandLineSwitchParserError class.

CommandLineSwitchParserError class exposes the following properties:

Property type and name | Description
-----------------------|-------------
ErrorTypes ErrorType | It represents the reason of parsing error.
string OptionName | The option name that causes parsing error.
string Parameter | The option parameter that causes parsing error.
Type ExpectedParameterType | The .NET type that expected to option parameter.

ErrorType take the one of ErrorTypes enum values the following:

  • UnknownOption
  • MissingParameter
  • InvalidParameterFormat
  • ParameterOverflow

When the parsing error occurred:

  • It returns only one of the first parsing error.
  • The command line arguments are not stripped.

FAQ

Questions

  • Is there any way to setup custom option name?
  • Can I get "usage" document automatically generated?
  • Can I use "/" instead of "-" ?
  • Can I use "-name=value" syntax instead of "-name value" ?
  • Can I use "-ab" syntax instead of "-a -b" ?

Answer

Sorry, no way.

I'm interested in keeping this library to simple usage.
That is the most important reason I created this library despite there are already numerous command line parsing libraries.

So I have no plan at this time.

If you need those features, you may consider using Microsoft.Extensions.CommandLineUtils (see also), or choose one of the many libraries published on NuGet that was tagged with "commandline" (search result is here).

License

Mozilla Public License, version 2.0

Release Notes

v.1.0.0
- Official public 1st release.
- Fix: typo of "ErrorTypes.UnknownOption".
v.0.5.0
- Add enum type property support!
- Disallow ambiguous short name of switch/option.
v.0.4.0
- Add "TryParse()" static method.
- Implement parsing error handling.
v.0.3.0
- .NET Standard support
v.0.2.0
- Beta release

This package is not used by any popular GitHub repositories.

Version History

Version Downloads Last updated
1.0.0 668 9/28/2017
0.5.0-beta 464 9/15/2017
0.4.0-beta 465 9/14/2017
0.3.0-beta 469 9/13/2017
0.2.0-beta 366 1/5/2017