Main Page Options

From NDesk

Jump to: navigation, search

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

Contents

[edit] NDesk.Options Releases

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

[edit] 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 a sequence of (optional) boolean options followed by an (optional) value-using option followed by the options's vlaue. In this manner, -abc would be a shorthand for -a -b -c, and -cvffile would be shorthand for -c -v -f=file (in the same manner as tar(1)).
  • Option processing is disabled when -- is encountered.

The NDesk.Options.dll assembly 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.

[edit] Documentation

Class Documentation.

[edit] License

NDesk.Options is released under the MIT/X11 license.

[edit] Development

A git repository is available:

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

[edit] 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.

[edit] 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 two ways to use NDesk.Options:

  • Bundle src/NDesk.Options/NDesk.Options/Options.cs with your app. 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 prebuilt 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/ndesk-options/NDesk.Options.dll.
Retrieved from "http://ndesk.org/Options"