Represents information about an option.
|
Instances of NDesk.Options.Option are created via the various NDesk.Options.OptionSetAdd overloads, such as:
You can also add custom NDesk.Options.Option subclasses to an NDesk.Options.OptionSet via the OptionSet.Add(Option) method.
Inheritors of this type must override the abstract method Option.OnParseComplete(OptionContext), which is (indirectly) invoked from within OptionSet.Parse(string, OptionContext) when an option matching one of the prototype aliases is encountered.
See Also: Inherited members from object.
Creates and initializes a new instance of the NDesk.Options.Option class. |
Creates and initializes a new instance of the NDesk.Options.Option class. |
Description [read-only] | string . A string containing documentation for this option. |
MaxValueCount [read-only] | int . A int containing the maximum number of values this NDesk.Options.Option accepts. |
OptionValueType [read-only] | NDesk.Options.OptionValueType . An NDesk.Options.OptionValueType instance specifying whether this NDesk.Options.Option takes a value, and if so, whether it's required or optional. |
Prototype [read-only] | string . The NDesk.Options.Option prototype, containing option name aliases and the option value requirements. |
GetNames
() Retrieves all name aliases that make up
Option.Prototype. |
|
GetValueSeparators
()
Retreives all value separators, strings which are used to split an
argument into one or more values for the this
NDesk.Options.Option.
|
|
Invoke
(NDesk.Options.OptionContext)
Invokes
Option.OnParseComplete(OptionContext)
then clears out c.
|
|
override |
ToString
()
Returns Option.Prototype.
|
abstract |
OnParseComplete
(NDesk.Options.OptionContext)
Perform an action when an option is parsed.
|
static |
Parse<T>
(string, NDesk.Options.OptionContext)
Converts the stringvalue
into an object of type T.
|
Creates and initializes a new instance of the NDesk.Options.Option class.
Type | Condition |
---|---|
ArgumentException |
prototype is the empty string "". -or- prototype contains an empty alias, such as a||b. -or- Conflicting NDesk.Options.OptionValueType values were found within prototype. |
ArgumentNullException | prototype is null. |
This constructor initializes the Option.Prototype property of the new instance using prototype, the Option.Description property of the new instance using description. and initializes the Option.MaxValueCount property of the new instance to 1.
This is equivalent to calling the Option(string, string, int) constructor as with Option(prototype, description, 1).
Creates and initializes a new instance of the NDesk.Options.Option class.
Type | Condition |
---|---|
ArgumentException |
prototype is the empty string "". -or- prototype contains an empty alias, such as a||b. -or- Conflicting NDesk.Options.OptionValueType values were found within prototype. -or- maxValueCount is 0 and prototype specified an NDesk.Options.OptionValueType value of OptionValueType.Optional or OptionValueType.Required. -or- maxValueCount is greater than 1 and prototype specified an NDesk.Options.OptionValueType value of OptionValueType.None. -or- prototype contains a separator list and maxValueCount is 0 or 1. -or- prototype contains a badly formatted separator list, such as {{, }}, {{}, etc. |
ArgumentNullException | prototype is null. |
This constructor initializes the Option.Prototype property of the new instance using prototype, the Option.Description property of the new instance using description. and initializes the Option.MaxValueCount property of the new instance using maxValueCount.
prototype is a |-separated list of option names. It should be listed in shortest-to-longest order, e.g. h|help. prototype may contain a NDesk.Options.OptionValueType specifier following one of the |-separated entries, and a value separator list following the NDesk.Options.OptionValueType specifier.
The Option.OptionValueType property is initialized based on whether a = or : follows one of the aliases within prototype. = specifies a OptionValueType.Required value, while : specifies an OptionValueType.Optional value. If neither = nor : is not specified, then OptionValueType.None is used. The value specifier may be used anywhere within prototype, so n|name=, n=|name and n=|name= are equivalent, but you cannot mix types; n:|name= is invalid.
Multiple values may be bundled together, such as -opt key=value. The value separator list specifies which characters can be used to split the value argument to generate separate values. The value separator list is available when maxValueCount is greater than 1, and and an NDesk.Options.OptionValueType was specified. The value separator list follows the = or : and is one of the following:
A sequence of character enclosed by { and }. Multiple such sequences may be specified by listing the {...} sequence multiple times.
The sequence {} requires that each value be a different argument, and no argument splitting will be performed. This sequence has no effect if other separators are also listed (as separate arguments are always permitted for OptionValueType.Required values).
If the separator list is not provided, then =: is the default separator list.
For example, the prototype "A:+-*/" would permit any of `+', `-', `*', or `/' to be used to split an argument into values, so -A:5/2 would generate the sequence of values 5 and 2 for the option -A. Furthermore, the prototype "A={-->}{=>}" would permit either the string --> or the string => to be used, so -A A->B C woud parse A->B as one value and C as the other value, while -A A-->B C would parse A as one value and B as the other value while C would be unhandled (unless the option required 3 values, in which case C would be the 3rd value).
A string containing documentation for this option.
Retrieves all name aliases that make up Option.Prototype.
Retreives all value separators, strings which are used to split an argument into one or more values for the this NDesk.Options.Option.
Value separators may be provided within Option.Prototype only if:
See the Option(string, string, int) constructor for more information.
Invokes Option.OnParseComplete(OptionContext) then clears out c.
This method is invoked from within OptionSet.Parse(string, OptionContext) when an option with a name from Option.GetNames is encountered and matches the required number of values governed by Option.OptionValueType and Option.MaxValueCount.
This method invokes Option.OnParseComplete(OptionContext), passing along c unchanged, and then sets the OptionContext.Option and OptionContext.OptionName properties to null, and OptionValueCollection.Clears out OptionContext.OptionValues.
A int containing the maximum number of values this NDesk.Options.Option accepts.
Perform an action when an option is parsed.
This method must be overridden by all subclasses, within which the subclass can perform some custom per-option processing.
This method is invoked from within OptionSet.Parse(string, OptionContext) when an option with a name from Option.GetNames is encountered and matches the required number of values governed by Option.OptionValueType and Option.MaxValueCount.
The following example has a custom NDesk.Options.Option subclass which overrides Option.OnParseComplete(OptionContext):
C# Example |
// Case-Insensitive and Concatenating OptionSet using System; using System.Collections.Generic; using NDesk.Options; class DemoOptionSet : OptionSet { protected override void InsertItem (int index, Option item) { if (item.Prototype.ToLower () != item.Prototype) throw new ArgumentException ("prototypes must be lower-case!"); base.InsertItem (index, item); } protected override OptionContext CreateOptionContext () { return new OptionContext (this); } protected override bool Parse (string option, OptionContext c) { string f, n, s, v; bool haveParts = GetOptionParts (option, out f, out n, out s, out v); Option nextOption = null; string newOption = option; if (haveParts) { nextOption = GetOptionForName (n.ToLower ()); newOption = f + n.ToLower () + (v != null ? s + v : ""); } if (c.Option != null) { // Prevent --a --b if (c.Option != null && haveParts) { if (nextOption == null) { // ignore } else throw new OptionException ( string.Format ("Found option `{0}' as value for option `{1}'.", option, c.OptionName), c.OptionName); } // have a option w/ required value; try to concat values. if (AppendValue (option, c)) { if (!option.EndsWith ("\\") && c.Option.MaxValueCount == c.OptionValues.Count) { c.Option.Invoke (c); } return true; } else base.Parse (newOption, c); } if (!haveParts || v == null) { // Not an option; let base handle as a non-option argument. return base.Parse (newOption, c); } if (nextOption.OptionValueType != OptionValueType.None && v.EndsWith ("\\")) { c.Option = nextOption; c.OptionValues.Add (v); c.OptionName = f + n; return true; } return base.Parse (newOption, c); } private bool AppendValue (string value, OptionContext c) { bool added = false; string[] seps = c.Option.GetValueSeparators (); foreach (var o in seps.Length != 0 ? value.Split (seps, StringSplitOptions.None) : new string[]{value}) { int idx = c.OptionValues.Count-1; if (idx == -1 || !c.OptionValues [idx].EndsWith ("\\")) { c.OptionValues.Add (o); added = true; } else { c.OptionValues [idx] += value; added = true; } } return added; } } class Demo { public static void Main (string[] args) { List<string> names = new List<string> (); Dictionary<string,string> map = new Dictionary<string,string> (); int repeat = 1; OptionSet p = new DemoOptionSet () { { "n|name=", v => names.Add (v) }, { "r|repeat:", (int v) => repeat = v }, { "m|map=", (k,v) => map.Add (k, v) }, }; List<string> extra; try { extra = p.Parse (args); } catch (OptionException e) { Console.Write ("subclass: "); Console.WriteLine (e.Message); return; } string message; if (extra.Count > 0) { message = string.Join (" ", extra.ToArray ()); } else { message = "Hello {0}!"; } foreach (string name in names) { for (int i = 0; i < repeat; ++i) Console.WriteLine (message, name); } List<string> keys = new List<string>(map.Keys); keys.Sort (); foreach (string key in keys) { Console.WriteLine ("Key: {0}={1}", key, map [key]); } } } |
See NDesk.Options.OptionSet for more on this example.
An NDesk.Options.OptionValueType instance specifying whether this NDesk.Options.Option takes a value, and if so, whether it's required or optional.
Converts the stringvalue into an object of type T.
Type | Condition |
---|---|
NDesk.Options.OptionException | If value is not null and System.ComponentModel.TypeConverter.ConvertFromString generated an exception while trying to convert value. |
The NDesk.Options.Option prototype, containing option name aliases and the option value requirements.
The prototype contains a |-separated list of all option name aliases and a value specifier of = for required values and : for optional values; if neither = nor : is present, no value is taken.
If a value specifier is present, then a value separator list may also be present after the value specifier.
Returns Option.Prototype.