Options

From NDesk

NDesk.Options is a callback-based program option parser for C#.

Contents 1 NDesk.Options Releases 2 Features 3 Documentation 4 Development 5 Background 6 Variations 7 Distribution

NDesk.Options Releases

NDesk.Options has had the following releases (in reverse chronological order):

• NDesk.Options 0.1.0 (ZIP) (RPM)
  • Release Notes
• Original Options.cs Prototype
  • Announcement

Features

OptionSet currently supports:

• Boolean options of the form: -flag, --flag, and /flag. Boolean parameters can have a `+' or `-' appended to explicitly enable or disable the flag (in the same fashion as mcs -debug+). For boolean callbacks, the provided value is non-null for enabled, and null for disabled.
• Value options with a required value (append `=' to the option name) or an optional value (append `:' to the option name). The option value can either be in the current option (--opt=value) or in the following parameter (--opt value). The actual value is provided as the parameter to the callback delegate, unless it's (1) optional and (2) missing, in which case null is passed.
• Bundled parameters which must start with a single `-' and consists of only single characters. In this manner, -abc would be a shorthand for -a -b -c.
• Option processing is disabled when -- is encountered.

The OptionSet is currently UNSTABLE. Please provide any feedback on the API and design of the library.

For now, NDesk.Options.dll is intended to be used as a private assembly. DO NOT install it into the GAC.

Documentation

Class Documentation.

Development

A git repository is available:

git-clone git://git.ndesk.org/pub/scm/ndesk-options

Background

I had been doing a lot of work on monodocer, and the warning about Mono.GetOptions being obsolete was getting annoying. So after killing an afternoon coming up with a similar reflection-based alternative, it dawned on me that (1) any such alternative would not be "simple", and (2) using such a library would have a high code overhead. After thinking back on the previous option parsing libraries I've used, I remembered Perl's Getopt::Long library, which permits short and concise declarations of the options a program supports.

The result: a cunning use of C# 3.0 collection initializers and lambda delegates:

   string data = null;
   bool help   = false;
   int verbose = 0;

   var p = new OptionSet () {
   	{ "file=",      v => data = v },
   	{ "v|verbose",  v => { ++verbose } },
   	{ "h|?|help",   v => help = v != null },
   };
   List<string> extra = p.Parse (args);

C# 3.0 features are not required, and OptionSet can be used with C# 2.0:

   string data = null;
   bool help   = false;
   int verbose = 0;

   OptionSet p = new OptionSet ()
     .Add ("v|verbose", delegate (string v) { if (v != null) ++verbose; })
     .Add ("h|?|help",  delegate (string v) { show_help = v != null; })
     .Add ("n|name=",   delegate (string v) { names.Add (v); });
   List<string> extra = p.Parse (args);

The documentation has more examples.

Variations

In order to cut down on the number of unique types (and the combinatorial explosion that produces when trying to mix-and-match delegate types), NDesk.Options "uses" some .NET 3.5 types.

Normally, this would prevent .NET 2.0 support.

So to support both .NET 2.0 and .NET 3.5, NDesk.Options can be built in two separate ways:

• With LINQ #defined: .NET 3.5 is assumed.
• With LINQ #undefined: .NET 2.0 is assumed.

When LINQ is not defined, the System.Action<T1,T2> delegate type is present within NDesk.Options.dll. Consequently, to prevent ambiguous type errors, you should only use the LINQ version on .NET 3.5, and the non-LINQ version on .NET 2.0.

Distribution

In accordance with the Guidelines for Application Deployment, there are pkg-config files to permit simple access to the source or pre-compiled assemblies for re-use.

There are three ways to use NDesk.Options:

• Bundle src/NDesk.Options/NDesk.Options/Options.cs with your app. You should #define LINQ as appropriate, depending on whether you target .NET 2.0 or .NET 3.5 (as described above). Source is readily obtained via:

pkg-config --variable=Sources ndesk-options

Options.cs is also present within the .bin.zip file, as ndesk-options-VERSION.bin/lib/ndesk-options/Options.cs.

• Use the .NET 2.0-specific NDesk.Options.dll:

pkg-config --variable=Libraries ndesk-options

NDesk.Options.dll is also present within the .bin.zip file, as ndesk-options-VERSION.bin/lib/net2/NDesk.Options.dll.

• Use the .NET 3.5-specific NDesk.Options.dll:

pkg-config --variable=Libraries ndesk-options-linq

NDesk.Options.dll is also present within the .bin.zip file, as ndesk-options-VERSION.bin/lib/net3.5/NDesk.Options.dll.