schallm / commandline

Command Line Parser Library

Command Line Parser Library 1.9.62.1 rc1 for CLR.

The Command Line Parser Library offers to CLR applications a clean and concise API for manipulating command line arguments and related tasks defining switches, options and verb commands. It allows you to display an help screen with an high degree of customization and a simple way to report syntax errors to the end user. Everything that is boring and repetitive to be programmed stands up on library shoulders, letting developers concentrate on core logic. This library provides hassle free command line parsing with a constantly updated API since 2005.

Compatibility:

• .NET Framework 3.5+
• Mono 2.1+ Profile

At glance:

• One line parsing using default singleton: CommandLine.Parser.Default.ParseArguments(...).
• One line help screen generator: HelpText.AutoBuild(...).
• Map command line arguments to IList<string>, arrays, enum or standard scalar types.
• Plug-In friendly architecture as explained here.
• Define verb commands as git commit -a.
• Create parser instance using lambda expressions with fluent builder.
• Most of features applies with a CoC philosophy.

To install:

• NuGet way (latest stable): Install-Package CommandLineParser
• NuGet way (latest version): Install-Package CommandLineParser -pre
• XCOPY way: cp CommandLine/src/libcmdline/*.cs To/Your/Project/Dir

To build:

You can use still use MonoDevelop or Visual Studio, but the project can aslo be built using Ruby Rake with a script that depends on Albacore.

$ gem install albacore
$ git clone https://github.com/gsscoder/commandline.git CommandLine
$ cd CommandLine
$ rake

To start:

• CSharp Template
• VB.NET Template

Public API:

Latest changes are recorded from Version 1.9.4.91, please refer to this document.

Verb Commands:

Since introduction of verb commands is a very new feature, templates and sample application are not updated to illustrate it. Please refer this wiki section and unit tests code to learn how to define, how to respond and how they relate to help subsystem. Give a look also at this blog article.

Notes:

The project is and well suited to be included in your application. If you don't merge it to your project tree, you must reference CommandLine.dll and import CommandLine and CommandLine.Text namespaces (or install via NuGet). The help text builder and its support types lives in CommandLine.Text namespace that is loosely coupled with the parser. However is good to know that HelpText class will avoid a lot of repetitive coding.

Define a class to receive parsed values:

class Options {
  [Option('r', "read", Required = true,
    HelpText = "Input file to be processed.")]
  public string InputFile { get; set; }
    
  // omitting long name, default --verbose
  [Option(DefaultValue = true,
    HelpText = "Prints all messages to standard output.")]
  public bool Verbose { get; set; }

  [ParserState]
  public IParserState LastParserState { get; set; }

  [HelpOption]
  public string GetUsage() {
    return HelpText.AutoBuild(this,
      (HelpText current) => HelpText.DefaultParsingErrorsHandler(this, current));
  }
}

Consume them:

static void Main(string[] args) {
  var options = new Options();
  if (CommandLine.Parser.Default.ParseArguments(args, options)) {
    // Values are available here
    if (options.Verbose) Console.WriteLine("Filename: {0}", options.InputFile);
  }
}

Acknowledgements:

Thanks to JetBrains for providing an open source license for ReSharper. Main Contributors (alphabetical order):

• Alexander Fast (@mizipzor)
• Dan Nemec (@nemec)
• Kevin Moore (@gimmemoore)
• Steven Evans

Resources for newcomers:

• CodePlex
• Quickstart
• Wiki
• GNU getopt

Latest Changes:

• Implemented enhancement of issue #57 suggested by @bluesan.
• Fixed issue #6.
• Heavy refactoring on Public API (see this this document and ChangeLog).

Contacts:

Giacomo Stelluti Scala

• gsscoder AT gmail DOT com
• Blog
• Twitter