Options

From NDesk

(Difference between revisions)

Jump to: navigation, search

Current revision

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

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

[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"

 NDesk.Options has had the following releases (in reverse chronological order):
-* [http://www.ndesk.org/archive/ndesk-options-0.1.0.tar.gz NDesk.Options 0.1.0] [http://www.ndesk.org/archive/ndesk-options-0.1.0.bin.zip (ZIP)] [http://www.ndesk.org/archive/ndesk-options-0.1.0-1.noarch.rpm (RPM)]
+* [http://www.ndesk.org/archive/ndesk-options/ndesk-options-0.2.1.tar.gz NDesk.Options 0.2.1] [http://www.ndesk.org/archive/ndesk-options/ndesk-options-0.2.1.bin.zip (ZIP)] [http://www.ndesk.org/archive/ndesk-options/ndesk-options-0.2.1-1.noarch.rpm (RPM)]
-** [http://www.jprl.com:8080/~jon/Blog/archive/development/ndesk.options/Jan-27.html Release Notes]
+** [http://www.jprl.com/Blog/archive/development/ndesk.options/2008/Oct-20.html Release Notes]
+* [http://www.ndesk.org/archive/ndesk-options/ndesk-options-0.2.0.tar.gz NDesk.Options 0.2.0] [http://www.ndesk.org/archive/ndesk-options/ndesk-options-0.2.0.bin.zip (ZIP)] [http://www.ndesk.org/archive/ndesk-options/ndesk-options-0.2.0-1.noarch.rpm (RPM)]
+** [http://www.jprl.com/Blog/archive/development/ndesk.options/2008/Feb-14.html Release Notes]
+* [http://www.ndesk.org/archive/ndesk-options/ndesk-options-0.1.0.tar.gz NDesk.Options 0.1.0] [http://www.ndesk.org/archive/ndesk-options/ndesk-options-0.1.0.bin.zip (ZIP)] [http://www.ndesk.org/archive/ndesk-options/ndesk-options-0.1.0-1.noarch.rpm (RPM)]
+** [http://www.jprl.com/Blog/archive/development/ndesk.options/2008/Jan-27.html Release Notes]
 * [http://www.jprl.com/Blog/archive/development/mono/2008/Options.v1.cs Original Options.cs Prototype]
 ** [http://www.jprl.com/Blog/archive/development/mono/2008/Jan-07.html Announcement]
 * <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.
 * <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.
-* <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>.
+* <i>Bundled</i> parameters which must start with a single `<tt>-</tt>' 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, <tt>-abc</tt> would be a shorthand for <tt>-a -b -c</tt>, and <tt>-cvffile</tt> would be shorthand for <tt>-c -v -f=file</tt> (in the same manner as <b>tar</b>(1)).
 * Option processing is disabled when <tt>--</tt> is encountered.
+The <tt>NDesk.Options.dll</tt> assembly is currently <i>UNSTABLE</i>.  Please provide any feedback on the API and design of the library.
+For now, <tt>NDesk.Options.dll</tt> is intended to be used as a private assembly.  DO NOT install it into the GAC.
 == Documentation ==
 [http://www.ndesk.org/doc/ndesk-options Class Documentation.]
+== License ==
+NDesk.Options is released under the [http://www.opensource.org/licenses/mit-license.php MIT/X11 license].
 == Development ==
-A [http://git.ndesk.org/?p=ndesk-options;a=summary git repository] is available:
+A [http://gitweb.ndesk.org/?p=ndesk-options;a=summary git repository] is available:
 : <tt>git-clone git://git.ndesk.org/pub/scm/ndesk-options</tt>
     List<string> extra = p.Parse (args);
-The [http://www.ndesk.org/doc/ndesk-options documentation] [http://www.ndesk.org/doc/ndesk-options/NDesk.Options/OptionSet.html has] [http://www.ndesk.org/doc/ndesk-options/NDesk.Options/OptionSet.html#C:NDesk.Options.OptionSet(System.Converter{System.String,System.String}) more] [http://www.ndesk.org/doc/ndesk-options/NDesk.Options/OptionSet.html#M:NDesk.Options.OptionSet.Add%60%601(System.String,System.String,System.Action{%60%600,NDesk.Options.OptionContext}) examples].
+The [http://www.ndesk.org/doc/ndesk-options documentation] [http://www.ndesk.org/doc/ndesk-options/NDesk.Options/OptionSet.html has] [http://www.ndesk.org/doc/ndesk-options/NDesk.Options/OptionSet.html#C:NDesk.Options.OptionSet(System.Converter{System.String,System.String}) more] [http://www.ndesk.org/doc/ndesk-options/NDesk.Options/OptionSet.html#M:NDesk.Options.OptionSet.WriteOptionDescriptions(System.IO.TextWriter) 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 <tt>LINQ #define</tt>d: .NET 3.5 is assumed.
-* With <tt>LINQ #undef</tt>ined: .NET 2.0 is assumed.
-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 <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:
+There are two ways to use NDesk.Options:
-* 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:
+* Bundle <tt>src/NDesk.Options/NDesk.Options/Options.cs</tt> with your app.  Source is readily obtained via:
 : <tt>pkg-config --variable=Sources ndesk-options</tt>
 : <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 <tt>NDesk.Options.dll</tt>:
+* Use the prebuilt <tt>NDesk.Options.dll</tt>:
 : <tt>pkg-config --variable=Libraries ndesk-options</tt>
-: <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>.
+: <tt>NDesk.Options.dll</tt> is also present within the <tt>.bin.zip</tt> file, as <tt>ndesk-options-VERSION.bin/lib/ndesk-options/NDesk.Options.dll</tt>.
-* Use the .NET 3.5-specific <tt>NDesk.Options.dll</tt>:
-: <tt>pkg-config --variable=Libraries ndesk-options-linq</tt>
-: <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>.