CommandLineParser80

Sample Usage

Construction Examples

string[] args = Environment.GetCommandLineArgs()

CommandLineTokens tokens = CommandLineParser
	.Create(new WindowsCmdTokenParser())
	.Parse(args);

string[] args = Environment.GetCommandLineArgs()

ITokenParser tokenParser = new LinuxTokenParser();
CommandLineParser commandLinParser = CommandLineParser.Create(tokenParser)
CommandLineTokens tokens = commandLinParser.Parse(args);

Example Consumption

string command = tokens.Command;
bool quiet = tokens.HasSwitch("quiet"); || tokens.HasFlag("q")
bool verbose = tokens.HasSwitch("verbose") || tokens.HasFlag("v")
string? filename = tokens.SwitchValue("filename")?.Text ?? string.Empty;

if (string.IsNullOrEmpty(filename))
	throw new Exception("You must specify a filename with thee  --filename parameter.");

if (quite && verbose)
	throw new Exception("--quiet and --verbose are mutually exclusive!")

string[] lines = []
if (!FileExists(filename))
	throw new FileNotFoundException(filename);

lines = File.ReadAllLines(filename)
if (verbose)
	lines.ToList().ForEach(line => Console.WriteLine(line));

if(!quiet)
	Console.WriteLine($"Done reading file {filename}.");

CommandLineParser and associated test app, unit tests and packages.

Publishing

Build the project. From the repository root, push the .nupkg file to the NuGet server.

dotnet nuget push -s https://nuget.pillidar.com/v3/index.json .\source\CommandLineParser80\bin\debug\CommandLineParser80.1.0.0.nupkg -k <security_key_goes_here>

Usage

Input

You'll need an ICommandLineProvider to provide input. The normal provider for an application is the EnvironmentCommandLineProvider class. The normal provider for unit tests is the ListCommandLineProvider.

The provided ICommandLineProvider implementations are:

• EnvironmentCommandLineProvider
• MainArgsCommandLineProvider
• ListCommandLineProvider

EnvironmentCommandLineProvider

This provider reads the command line parameters from the .NET Environment.GetCommandLineParameters() function.

MainArgsCommandLineProvider

This accepts a string array and feeds it back on demand. This is a simple straight-through implementation. It is designed to make it easy to consume your main(string[] args) parameters in a convenient way.

ListCommandLineProvider

While it may be useful in other scenarios, this is primarily provided for unit testing. It is similar to the MainArgsCommandLineProvider except that it works as a List instead of a string[] array.

Parsers

There are different ICommandLineParsers available. The one you choose usually depends on your operating system or your command line shell.

• WindowsCmdTokenParser - a token parser that handles DOS/Windows (CMD)-style command lines.
• LinuxTokenParser - a token parser that handles Linux-style command lines.
• PowerShellTokenParser - a token parser that handles PowerShell-style command lines.
• UniversalTokenParser - a hybrid parser that handles some CMD and Linux-style aspects.

WindowsCmdTokenParser

This parser handles these kinds of parameters:

• /switch
• /switch:value
• /switch=value
• -switch
• -switch:value
• -switch=value
• --switch
• --switch:value
• --switch=value
• paramvalue

LinuxTokenParser

The LinuxTokenparser parser handles these kinds of parameters:

• -abcd (flags a, b, c, and d, same as -a -b -c -d)
• --switch
• --switch=value
• paramvalue

PowerShellTokenParser

The PowerShellTokenParser parser handles these kinds of parameters:

• -switch
• -switch:value
• -switch=value
• paramvalue

UniversalTokenParser

The UniversalTokenParser parser handles these kinds of parameters:

• -switch
• --switch
• paramvalue

Tokens

Parsers accept an array of parameters. There is no mechanism in this library to tokenize a command line because .NET always provides the command lines pre-tokenized for you. If you want this functionality, use this in combination with a tokenizing library.

When a parser parses an array of parameters, it produces a list of CommandLineToken objects.
The CommandLineToken class has these concepts:

• Switch - A single parameter whose existence indicates that a value is "on" and whose absence indicates "off". Switches can also be name/value pairs when specified as a colon-delimited token.
• Parameter - A single value. This may be treated as a switch by the application, but not by this library. A parameter may be treated by the application as a key or a value in a key/value pair.

Token Types

The valid token types are:

The CommandLineToken Class

The CommandLineToken class represents a single token on the command line. It holds all the queryable attributes about the token.

The CommandLineTokens Class

The CommandLineTokens class is a collection of CommandLineToken objects. It provides convenience methods for querying the tokens as a whole command line.

| Switch | Returns the token which contains the specified switch by name. | "/switch1 /switch2 param1" | tokens.Switch("switch2") | CommandLineToken { text: "switch2" } | | SwitchValue | Returns the token following the specified switch token, specified by switch name. | "/switch1 /switch2 param1" | tokens.SwitchValue("switch2") | CommandLineToken { text: "param1" } | | Param | Returns the token which contains the specified text / rawtext. | "param1 param2 param3" | tokens.Param("param2") | CommandLineToken { text: "param2" } | | ParamValue | Returns the token following the specified param token. | "param1 param2 param3" | tokens.ParamValue("param2") | CommandLineToken { text: "param3" } |

To Do

• The WindowsTokenParser should be broken out into a CmdTokenParser and a PowerShellTokenParser. It makes no sense to cram both into a single parser.

• The LinuxTokenParser does not support flags. That should be fixed.