CommandParser - A getopt() Inspired Command Line Parser for C# using LINQ

• Download demo project - 6.03 KB
• Download source - 5.81 KB

Introduction

CommandParser for C# is a simple object that is designed to handle the bulk of the problems any creator of a command line tool will run into while dealing with command line arguments. It was inspired by, but does not faithfully copy all aspects of, the C runtime function "getopt()".

One might classify these common problems as follows:

1. Parsing command line arguments in a user friendly manner
2. Allowing programmers to easily specify and handle command line arguments
3. Generating a help screen that depends directly on the available arguments
4. Detecting unknown or invalid commands
5. Detecting commands that are required, but were not supplied

When I say this project was inspired by getopt(), the inspiration is mostly in terms of how the command line arguments can be supplied by the user. Everything else about this project is very much NOT like getopt(). I have instead tried to make use of the latest language features available in C# to achieve a similar effect. I have in no way tried to implement a fully POSIX compliant library, so if there are any deviances from that standard, I apologize.

Background

Anyone familiar with the getopt() method should know that it does a lot of useful things, not the least of which is handling the parsing of command line arguments in a flexible way. To illustrate this point, imagine you had a program that needed to take 3 different flags, p, q, and z, and the z flag takes an argument.

With getopt, you could specify these commands in any of the following ways, and they would all be treated the same:

-p -q -z7
-p -q -z 7
-pqz7
-p -qz7
-p -qz "7"
-p -qz"7"

You can see how flexible this is. Getopt also supports the use of a long form of an argument. Thus, you could let the "-p" option also be specified with an argument like "-populate". This can make the available commands easier to remember and understand.

This is all well and good, but there are a number of ways in which I think getopt() is not, well, all that opt. These include:

1. A cryptic, yet powerful, format for letting you specify command arguments
2. No easy to use mechanism for generating help screens for supported commands
3. The mechanism for dispatching commands with getopt typically involves a cumbersome switch statement
4. No implementations, to my knowledge, are available that solve all of these problems for the .NET programmer

It is for these reasons that I decided to build this project and share it. I hope you find it useful.

Using the Code

Using the CommandParser is fairly straightforward. You essentially need to specify the arguments the parser will handle, parse the command line, and handle the results.

Specifying Arguments

The following example shows a typical argument specification for a command that is required and takes a parameter:

var parser = new CommandParser("A Sample Test Harness for CommandParser.cs");

parser.Argument("h", "host", "Specify a host ip address", "ip_addr",
                 CommandArgumentFlags.TakesParameter | CommandArgumentFlags.Required,
                 (p, v) => {
                     host = v;
                 });

In this example, we have passed 6 arguments to the "Argument" method. The first argument is the short form for the flag, the second is the long form, the third is a description for the flag that will appear in the auto-generated help screen, and the fourth is the string to use to define the parameter that this argument takes in the help screen.

Finally, the handler argument describes what to do when the command flag is encountered. This handler is a function that takes a reference to the CommandParser doing the parsing, and a string that contains the value of the argument passed to it. In the example above, we make use of a C# lambda expression to define the handler inline. Since, in practice, many command line arguments are just flags that need to be stored on a settings object for a tool, being able to specify what to do with the flag alongside its definition is very handy.

Parsing the Command Line

Once you have specified all of the arguments you want the parser to handle, telling the parser to do its work is a simple matter:

parser.Parse();

When you call the Parse() method, the command line parser will determine which flags are present, and when it encounters them, it will call the actions provided when the arguments were defined as described above.

During the parsing, any unknown commands that were detected as well as any commands that are required that weren't provided will be stored by the parser object. This lets you take appropriate action depending on how you want to handle these issues.

Handling Post-Parsing Results

In the included test harness for this project, the following code is supplied to show one way to handle program execution after the parsing completes.

if (parser.UnknownCommands.Count > 0) {
    foreach (var unknown in parser.UnknownCommands) {
        Console.WriteLine("Invalid command: " + unknown);
    }

    Console.WriteLine(parser.GetHelp());
} else if (parser.MissingRequiredCommands.Count > 0) {
    foreach (var missing in parser.MissingRequiredCommands) {
        Console.WriteLine("ERROR: Missing argument: " + missing);
    }

    Console.WriteLine(parser.GetHelp());
} else if (!showHelp) {
    Console.WriteLine("update = " + update);
    Console.WriteLine("populate = " + populate);
    Console.WriteLine("host = " + host);
    Console.WriteLine("query = " + query);
} else {
    Console.WriteLine(parser.GetHelp());
}

In this example, if we're not showing the help screen explicitly, then we execute the primary purpose of the tool. In this case, the tool outputs the result of the parsing flags, but your tools will probably do something more useful than that.

What is more interesting is the cases where we are easily able to handle both unknown commands as well as missing required commands quickly and easily. We can even display a help screen in these cases by simply calling parser.GetHelp().

The help screen provided by the CommandParser uses the argument list you specified to automatically generate help text based on the arguments you have supplied to the parser. This means that when you update your list of supported commands, the help screen will be updated automatically.

Points of Interest

I'm sure there is much that could be done to this to make it more elegant. I am still not overly happy with how argument specification turned out. It works, but I feel that it is a bit clunky and could be better. I'd love to hear any suggestions people might have for this.

History

• V1.0 - Initial release