Option (Command Line Parsing API)

java.lang.Object
- org.netbeans.spi.sendopts.Option

```
public final class Option
extends Object
```
Represents possible option that can appear on CommandLine and contains factory methods to create them. Consider using Arg annotation instead.
An option can have letter short version, long name. It can accept arguments, one argument or an array of additional arguments.

Field Summary

Fields
Modifier and Type Field and Description

static char NO_SHORT_NAME
Constant that represents no short name indicator.

Fields
Modifier and Type	Field and Description
`static char`	`NO_SHORT_NAME` Constant that represents no short name indicator.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static Option`	`additionalArguments(char shortName, String longName)` Creates an option that can accept additional arguments.
`static Option`	`always()` Creates an option that is always present.
`static Option`	`defaultArguments()` Creates a default option that accepts additional arguments not claimed by any other option.
`static Option`	`displayName(Option option, String bundleName, String key)` Associates a name with given option.
`boolean`	`equals(Object o)` Options with the same functionality, regardless of their descriptions `Option.shortDescription(org.netbeans.spi.sendopts.Option, java.lang.String, java.lang.String)` and `Option.displayName(org.netbeans.spi.sendopts.Option, java.lang.String, java.lang.String)` are always the same.
`int`	`hashCode()`
`static Option`	`optionalArgument(char shortName, String longName)` Factory method for option that may, but does not need to have an argument.
`static Option`	`requiredArgument(char shortName, String longName)` Factory method for option has to be followed by one argument.
`static Option`	`shortDescription(Option option, String bundleName, String key)` Associates a short textual description with given option.
`String`	`toString()` Programmatic textual representation of the option.
`static Option`	`withoutArgument(char shortName, String longName)` Factory method that creates an option without any arguments.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - NO_SHORT_NAME
```
public static final char NO_SHORT_NAME
```
    Constant that represents no short name indicator.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - toString
```
public String toString()
```
    Programmatic textual representation of the option. Format is subject to change in future.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    textual description of the option
  - equals
```
public boolean equals(Object o)
```
    Options with the same functionality, regardless of their descriptions Option.shortDescription(org.netbeans.spi.sendopts.Option, java.lang.String, java.lang.String) and Option.displayName(org.netbeans.spi.sendopts.Option, java.lang.String, java.lang.String) are always the same.
    
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - withoutArgument
```
public static Option withoutArgument(char shortName,
                                     String longName)
```
    Factory method that creates an option without any arguments. For example to create an option that handles --help or -h one can create it using:
```
 Option helpOption = Option.withoutArgument('h', "help");
```
    and inside of the OptionProcessor declaring this option use:
```
   protected void process(Env env, Map<Option,String[]> values) throws CommandException {
     if (values.containsKey(helpOption)) {
       printHelp(env.getErrorStream());
     }
   }
```
    The values.get(helpOption) is always null to signal that this options does not have any associated value.
    Parameters:
    
    shortName - character code or Option.NO_SHORT_NAME
    
    longName - long name or null
    
    Returns:
    
    option representing the created definition
  - optionalArgument
```
public static Option optionalArgument(char shortName,
                                      String longName)
```
    Factory method for option that may, but does not need to have an argument. For example to have option that increments by one or by specified number one could write:
```
 Option incrementOption = Option.optionalArgument('i', "increment");
```
    and inside of the OptionProcessor declaring this option use:
```
   public void process(Env env, Map<Option,String[]> values) throws CommandException {
     if (values.containsKey(incrementOption)) {
       String[] inc = values.get(incrementOption);
       int increment = inc == null ? 1 : Integer.parseInt(inc[0]);
       // do what is necessary
     }
   }
```
    The values map always contains the incrementOption if it appeared on the command line. If it had associated value, then the map.get(incrementOption) returns array of length one, with item on position 0 being the value of the option. However if the option appeared without argument, then the value associated with the option is null.
    If registered into to system using OptionProcessor then users could use command lines like -i=5 or --increment=5 to increase the value by five or just -i and --increment to increment by default - e.g. one.
    Parameters:
    
    shortName - the character to be used as a shortname or Option.NO_SHORT_NAME
    
    longName - the long name or null
  - requiredArgument
```
public static Option requiredArgument(char shortName,
                                      String longName)
```
    Factory method for option has to be followed by one argument. For example to have option that opens a file one could write:
```
 Option openOption = Option.optionalArgument('o', "open");
```
    and inside of the OptionProcessor declaring this option use:
```
   public void process(Env env, Map<Option,String[]> values) throws CommandException {
     if (values.containsKey(openOption)) {
       String fileName = values.get(openOption)[0];
       File file = new File(Env.getCurrentDirectory(), fileName);
       // do what is necessary
     }
   }
```
    The values map always contains the openOption if it appeared on the command line. Its value is then always string array of length one and its 0 element contains the argument for the option.
    If registered into to system using OptionProcessor then users could use command lines like -oX.java or --open Y.java to invoke the open functionality.
    Parameters:
    
    shortName - the character to be used as a shortname or Option.NO_SHORT_NAME
    
    longName - the long name or null
  - additionalArguments
```
public static Option additionalArguments(char shortName,
                                         String longName)
```
    Creates an option that can accept additional arguments. For example to have option that opens few files one could write:
```
 Option openOption = Option.additionalArguments('o', "open");
```
    and inside of the OptionProcessor declaring this option use:
```
   public void process(Env env, Map<Option,String[]> values) throws CommandException {
     if (values.containsKey(openOption)) {
       for (String fileName : values.get(openOption)) {
         File file = new File(Env.getCurrentDirectory(), fileName);
         // do what is necessary
       }
     }
   }
```
    The values map always contains the openOption if it appeared on the command line. Its value is then always string array of arbitrary length containing all elements on the command line that were not recognised as options (or their arguments). For example line
```
 X.java -o Y.java Z.txt
```
    will invoke the OptionProcessor with { "X.java", "Y.java", "Z.txt" }.
    Obviously only one such Option.additionalArguments(char, java.lang.String) can be used at once on a command line. If there was not only the open but also edit option taking the additional arguments, then command line like:
```
 --edit X.java --open Y.java Z.txt
```
    would be rejected.
    Parameters:
    
    shortName - the character to be used as a shortname or Option.NO_SHORT_NAME
    
    longName - the long name or null
  - defaultArguments
```
public static Option defaultArguments()
```
    Creates a default option that accepts additional arguments not claimed by any other option. For example to have option that opens few files one could write:
```
 Option openOption = Option.defaultArguments();
```
    and inside of the OptionProcessor declaring this option use:
```
   public void process(Env env, Map<Option,String[]> values) throws CommandException {
     if (values.containsKey(openOption)) {
       for (fileName : values.get(openOption)) {
         File file = new File(Env.getCurrentDirectory(), fileName);
         // do what is necessary
       }
     }
   }
```
    The values map always contains the openOption if there were some arguments on the command line that were not parsed by any other option. Its value is then always string array of arbitrary length containing all elements on the command line that were not recognised as options (or their arguments). For example line
```
 X.java Y.java Z.txt
```
    will invoke the OptionProcessor with { "X.java", "Y.java", "Z.txt" }.
    Obviously only one such Option.defaultArguments() can defined. If there are two, then an error is reported when one tries to parse any command line with arguments not claimed by any other option. That is why it is always good idea to not define just Option.defaultArguments() option, but also appropriate Option.additionalArguments(char, java.lang.String) one:
```
 Option openOption1 = Option.defaultArguments();
 Option openOption2 = Option.additionalArguments('o', "open");
```
    and handle both of them in the OptionProcessor. Then if the command line:
```
 X.java Y.java Z.txt
```
    is rejected due to ambiguities one can use
```
 X.java Y.java --open Z.txt
```
    to invoke the same functionality.
  - always
```
public static Option always()
```
    Creates an option that is always present. This can be useful for processors that want to be notified everytime the command line is successfuly parsed. Option always = Option.always(); and inside of the OptionProcessor declaring this option use:
```
   public void process(Env env, Map<Option,String[]> values) throws CommandException {
     assert values.contains(always);
   }
```
    Returns:
    
    the option that always matches correct command line
    
    Since:
    
    2.1
  - displayName
```
public static Option displayName(Option option,
                                 String bundleName,
                                 String key)
```
    Associates a name with given option. By default the option display name is generated by the infrastructure from the short and long name plus generic description of options arguments, this method allows to completely replace the default behaviour.
    
    Parameters:
    
    option - the option to add description for
    
    bundleName - name of a bundle to create
    
    key - the bundle key to get the message from
    
    Returns:
    
    option with same behaviour as the old one plus with associated display name
  - shortDescription
```
public static Option shortDescription(Option option,
                                      String bundleName,
                                      String key)
```
    Associates a short textual description with given option. This message is going to be printed during CommandLine.usage(java.io.PrintWriter) next to the option name. Usually should be one liner comment.
    
    Parameters:
    
    option - the option to add description for
    
    bundleName - name of a bundle to create
    
    key - the bundle key to get the message from
    
    Returns:
    
    option with same behaviour as the old one plus with associated short description message

Class Option

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NO_SHORT_NAME

Method Detail

toString

equals

hashCode

withoutArgument

optionalArgument

requiredArgument

additionalArguments

defaultArguments

always

displayName

shortDescription