The Parsing Process

You have learned to define the type that will contain the results of the command line parsing. All that remains is to invoke the parser correctly.
The type that deals with the parsing is CommandLine.CommandLineParser.

C#:

namespace CommandLine
{
    public class CommandLineParser : ICommandLineParser
    {
        public CommandLineParser();
		
        public CommandLineParser(CommandLineParserSettings settings);
		
        public virtual bool ParseArguments(string[] args, object options);
		
        public virtual bool ParseArguments(string[] args, object options, TextWriter helpWriter);
    }
}

CommandLineParser implements ICommandLineParser interface; this was done to give the possibility to implement variants of the parser (by you or future version of the project).
So it's preferable to build the instance on a interface variable.

C#:

ICommandLineParser parser = new CommandLineParser();

Besides the default constructor (without parameters) there is one that accepts the CommandLineParserSettings type.

C#:

namespace CommandLine
{
    public sealed class CommandLineParserSettings
    {
        public CommandLineParserSettings();
        //
        // constructors with different combinations of parameters
        //

        public bool CaseSensitive { set; }

        public TextWriter HelpWriter { set; }

        public bool MutuallyExclusive { set; }
}
  1. The CaseSensitive property controls the kind of string comparison performed by parser; as default is set to true. This means that if you have an option defined as -i/--input (all lowercase) you have to type the option name(s) strictly in lowercase.
  2. The HelpWriter property is null by default. That means that in no case the parser would write on a System.IO.TextWriter the help screen defined by the HelpOption attribute.
  3. The MutuallyExclusive property controls mutually exclusive options. This feature is disabled by default, that is set to false. This feature will be discussed later, but for now you can refer the page of the first release that implemented it: 1.5.96.199 beta 2.

Now you can build the parser instance passing to its constructor the settings instance.

C#:

var settings = new CommandLineParserSettings();
settings.CaseSensitive = false;
settings.HelpWriter = Console.Error;
ICommandLineParser parser = new CommandLineParser(settings);

For brevity you can use a suitable constructor without explicitly using an instance variable.

C#:

ICommandLineParser parser = new CommandLineParser(new CommandLineParserSettings(Console.Error));

Or you can use object initializers.

C#:

ICommandLineParser parser = new CommandLineParser(
    new CommandLineParserSettings { MutuallyExclusive = true, HelpWriter = Console.Error });

At last you can invoke the method that performs the actual work of parsing.

C#:

static void Main(string[] args)
{
    var options = new Options;
    //
    // create parser (with settings) here, see above
    //
    bool success = parser.ParseArguments(args, options)
    if (success)
    {
	    DoWhateverYouWantWith(options);
    }
    else
    {
	    // manage the failure here
    }
}

As you have seen above there is an overload of ParseArguments(...) that takes a System.IO.TextWriter parameter. This overload was designed before CommandLineParserSettings, so I suggest to call it if you build a parser instance without settings.

C#:

var options = new Options();
ICommandLineParser parser = new CommandLineParser();
if (parser.ParseArguments(args, options, Console.Error))
{
    // do something with options instance ...
}
else
    Environment.Exit(1);

Singleton

In author experience the most frequently used settings are caseSensitive = false, mutuallyExclusive = false and helpWriter = Console.Error. If this is also your case, you can use the prebuilt singleton.

C#:

if (CommandLineParser.Default.ParseArguments(args, options))
{
  // manage options here
}

And you're done. This also reduces code and improves its readability.

Last edited May 15, 2012 at 8:28 AM by gsscoder, version 19

Comments

rjrizzuto Mar 1 at 8:40 PM 
Ugh, I never saw your response till now. The link to the sample is no longer valid, do you have an updated link?

gsscoder May 14, 2012 at 8:54 PM 
See the sample (https://github.com/gsscoder/commandline/blob/master/src/sample/Program.cs) and how it manages parsing errors. The library API is very easy to learn, just look at the sample code! If not sufficient, read all docs... If even not, write me!

rjrizzuto May 9, 2012 at 5:13 PM 
Is there some way to which of the following caused parser.ParseArguments to return false:

- invalid command line - parser error
- user specified --help

The reason I ask it that I want to log an event for the former, but not the latter.