Options

From NDesk

(Difference between revisions)

Jump to: navigation, search

Revision as of 23:37, 26 January 2008

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

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):

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.

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.

Retrieved from "http://ndesk.org/Options"

 [http://www.ndesk.org/doc/ndesk-options/NDesk.Options/OptionSet.html 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.
+* <i>Boolean</i> options of the form: <tt>-flag</tt>, <tt>--flag</tt>, and <tt>/flag</tt>. Boolean parameters can have a `<tt>+</tt>' or `<tt>-</tt>' appended to explicitly enable or disable the flag (in the same fashion as <tt>mcs -debug+</tt>). For boolean callbacks, the provided value is non-<tt>null</tt> for enabled, and <tt>null</tt> 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.
+* <i>Value</i> options with a required value (append `<tt>=</tt>' to the option name) or an optional value (append `<tt>:</tt>' to the option name). The option value can either be in the current option (<tt>--opt=value</tt>) or in the following parameter (<tt>--opt value</tt>). The actual value is provided as the parameter to the callback delegate, unless it's (1) optional and (2) missing, in which case <tt>null</tt> 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.
+* <i>Bundled</i> parameters which must start with a single `<tt>-</tt>' and consists of only single characters. In this manner, <tt>-abc</tt> would be a shorthand for <tt>-a -b -c</tt>.
-* Option processing is disabled when -- is encountered.
+* Option processing is disabled when <tt>--</tt> is encountered.
 == Documentation ==
 A [http://git.ndesk.org/?p=ndesk-options;a=summary git repository] is available:
-: git-clone git://git.ndesk.org/pub/scm/ndesk-options
+: <tt>git-clone git://git.ndesk.org/pub/scm/ndesk-options</tt>
 == Background ==
 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 <tt>LINQ #define</tt>d: .NET 3.5 is assumed.
-* With LINQ #undefined: .NET 2.0 is assumed.
+* With <tt>LINQ #undef</tt>ined: .NET 2.0 is assumed.
-When LINQ is not defined, the [http://www.ndesk.org/doc/ndesk-options/System/Action`2.html 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.
+When <tt>LINQ</tt> is not defined, the [http://www.ndesk.org/doc/ndesk-options/System/Action`2.html System.Action<T1,T2>] delegate type is present within <tt>NDesk.Options.dll</tt>. Consequently, to prevent ambiguous type errors, you should only use the <tt>LINQ</tt> version on .NET 3.5, and the non-<tt>LINQ</tt> version on .NET 2.0.
 == Distribution ==
-In accordance with the [http://www.mono-project.com/Guidelines:Application_Deployment#Libraries_with_Unstable_APIs Guidelines for Application Deployment], there are pkg-config files to permit simple access to the source or pre-compiled assemblies for re-use.
+In accordance with the [http://www.mono-project.com/Guidelines:Application_Deployment#Libraries_with_Unstable_APIs Guidelines for Application Deployment], there are <tt>pkg-config</tt> 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:
+* Bundle <tt>src/NDesk.Options/NDesk.Options/Options.cs</tt> with your app. You should <tt>#define LINQ</tt> 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
+: <tt>pkg-config --variable=Sources ndesk-options</tt>
-: Options.cs is also present within the .bin.zip file, as ndesk-options-VERSION.bin/lib/ndesk-options/Options.cs.
+: <tt>Options.cs</tt> is also present within the <tt>.bin.zip</tt> file, as <tt>ndesk-options-VERSION.bin/lib/ndesk-options/Options.cs</tt>.
-* Use the .NET 2.0-specific NDesk.Options.dll:
+* Use the .NET 2.0-specific <tt>NDesk.Options.dll</tt>:
-: pkg-config --variable=Libraries ndesk-options
+: <tt>pkg-config --variable=Libraries ndesk-options</tt>
-: NDesk.Options.dll is also present within the .bin.zip file, as ndesk-options-VERSION.bin/lib/net2/NDesk.Options.dll.
+: <tt>NDesk.Options.dll</tt> is also present within the <tt>.bin.zip</tt> file, as <tt>ndesk-options-VERSION.bin/lib/net2/NDesk.Options.dll</tt>.
-* Use the .NET 3.5-specific NDesk.Options.dll:
+* Use the .NET 3.5-specific <tt>NDesk.Options.dll</tt>:
-: pkg-config --variable=Libraries ndesk-options-linq
+: <tt>pkg-config --variable=Libraries ndesk-options-linq</tt>
-: NDesk.Options.dll is also present within the .bin.zip file, as ndesk-options-VERSION.bin/lib/net3.5/NDesk.Options.dll.
+: <tt>NDesk.Options.dll</tt> is also present within the <tt>.bin.zip</tt> file, as <tt>ndesk-options-VERSION.bin/lib/net3.5/NDesk.Options.dll</tt>.