Options
From NDesk
Revision as of 21:54, 14 February 2008 (edit) JonPryor (Talk | contribs) ← Previous diff |
Current revision (21:25, 4 February 2009) (edit) (undo) Alp (Talk | contribs) (s/git/gitweb) |
||
(5 intermediate revisions not shown.) | |||
Line 5: | Line 5: | ||
NDesk.Options has had the following releases (in reverse chronological order): | NDesk.Options has had the following releases (in reverse chronological order): | ||
+ | * [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/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.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.jprl.com/Blog/archive/development/ndesk.options/2008/Feb-14.html Release Notes] | ||
Line 18: | Line 20: | ||
* <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>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>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. | * Option processing is disabled when <tt>--</tt> is encountered. | ||
Line 28: | Line 30: | ||
[http://www.ndesk.org/doc/ndesk-options Class 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 == | == 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> | : <tt>git-clone git://git.ndesk.org/pub/scm/ndesk-options</tt> | ||
Line 64: | Line 70: | ||
List<string> extra = p.Parse (args); | 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 == | == Distribution == | ||
Line 83: | Line 76: | ||
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. | 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>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>. | : <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>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>. | + |
Current revision
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):
- NDesk.Options 0.2.1 (ZIP) (RPM)
- NDesk.Options 0.2.0 (ZIP) (RPM)
- NDesk.Options 0.1.0 (ZIP) (RPM)
- Original Options.cs Prototype
[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
[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.