Roadmap

v1.1

New improved parsing engine

A number of different improvement have been made to the parsing engine.

Support collections

Many arguments can now be collected as part of a list. Types supported are string, int, double and bool

For example arguments such as

--filenames C:\file1.txt C:\file2.txt C:\file3.txt

can be parsed to a list using

static void Main(string[] args)
{
   var parser = new FluentCommandLineParser();

   var filenames = new List<string>();

   parser.Setup<List<string>>("f", "filenames")
         .Callback(items => filenames = items);

   parser.Parse(args);

   Console.WriteLine("Input file names:");

   foreach (var filename in filenames)
   {
      Console.WriteLine(filename);
   }
}

output:

Input file names
C:\file1.txt
C:\file2.txt
C:\file3.txt

Combined short options

Options x, y and z can be combined which applies any specified argument to them all.

-xyz value

static void Main(string[] args)
{
   var parser = new FluentCommandLineParser();

   string xVal = null;
   string yVal = null;
   string zVal = null;

   parser.Setup<string>("x").Callback(x => xVal = x);
   parser.Setup<string>("y").Callback(y => yVal = y);
   parser.Setup<string>("z").Callback(z => zVal = z);
   
   parser.Parse(args);

   Console.WriteLine("x is " + xVal);
   Console.WriteLine("y is " + yVal);
   Console.WriteLine("z is " + zVal);
}

output:

x is value
y is value
z is value

As such -xyz value can be described as shorthand for

-x value -y value -z value

More commonly this feature is used to handle multiple boolean options

-xyz enable option x, y and z

-xyz+ enable option x, y and z

-xyz- disable option x, y and z

Setup Help & Empty Arguments

static void Main(string[] args)
{
   var parser = new FluentCommandLineParser();

   parser.SetupHelp("h", "help", "?")
         .Callback(text => Console.WriteLine(text);

   var result = parser.Parse(args);
   
   if(result.HelpCalled)
   {
      // help
   }

   if(result.EmptyArgs)
   {
      // empty
   }
}

The following are available from the .SetupHelp() method to define its behaviour:

.Callback<string>(text => Console.WriteLine(text)) Specified the delegate to be invoked with any setup options formatted for the console.

.Callback(() => Environment.Exit(1)) Specified the delegate to be invoked without any arguments. This can be in addition to the delegate with arguments and in this case is always called last.

.WithCustomFormatter(new CustomOptionFormatter()) Specifies a custom formatter to use.

.UseForEmptyArgs() Specifies that empty arguments should be handled the same way as the setup help arguments; that is for example, if empty arguments are provided then the same help text can be printed to the console.

Parser Error Handling

To determine if any errors occurred during the parsing process use the HasErrors bool property on the result object.

var p = new FluentCommandLineParser();

p.Setup<int>("n", "number")
 .Callback(n => Console.WriteLine(n.ToString()));

p.Setup<string>("f", "filename")
 .Callback(f => Console.WriteLine(f)));
 .Required();

var result = p.Parse(args);

if(result.HasErrors)
{
  Console.WriteLine(result.FormattedError);
}

Option Parse Error

This error occurs when a the argument value could not be parsed into the correct type for the Option.

For example specifying a string argument for the number Option which is an integer...

example.exe --number "one"`

...would generate the following error message in the console:

Option '--number' parse error: could not parse 'one' to 'System.Int32'

Expected Option Not Found Error

This error occurs when a required option does not exist in the specified arguments.

In the code example above the filename Option is explicitly required, therefore if it is not specified in the arguments the following error message would be generated for the console:

Option 'f:filename' parse error: Option is required but was not specified.

Error messages are generated by the ICommandLineParserErrorFormatter.

Functional Changes (!)

Some functional changes have been made which may impact existing behaviour.

• Short options must be exactly a single character. Attempting to define anything else will result in an error. This change was made to allow combining short options.
• Short options are defined using the - prefix only. Other prefixes such as -- and / denote long options and thus have different behaviour in the parser (does not attempt to combined options).
• String arguments that contain whitespace but are not wrapped in double quotes cannot be parsed and are returned as errors from the parse operation.

--filename "C:\My Documents\file1.txt" is valid (filename with whitespace wrapped in double quotes)

--filename C:\My Documents\file1.txt is NOT valid (filename with whitespace NOT wrapped in double quotes)

--filename C:\DirWithNoWhiteSpace\file1.txt is valid (filename without whitespace not wrapped in double quotes)

Breaking Api Changes (!!)

Changes have been kept to a minimal with the following changes made:

• The CommandLineOptionFormatter.ShowHeader property is no longer public and therefore not settable. The header will always be unseen by default. If you would like a header to be displayed you should instead use the new WithHeader(string) method when setting up the help. e.g.

.SetupHelp("?").WithHeader("text to display at the top")

• Although not visible to through the main Api, the internals have been modified to provide more extendable behaviour.
• The parser.CreateShowUsageText() method has been dropped to simplify the Api. You can either use the .SetupHelp() method to get the usage text or use the OptionFormatter property on the parser itself.