当前页面: 在线文档首页 > NetBeans API Javadoc (Current Development Version)

Option (Command Line Parsing API) - NetBeans API Javadoc (Current Development Version)

Overview  Package   Class  Use  Tree  Deprecated  Index  Help		org.netbeans.modules.sendopts/2 2.0
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

org.netbeans.spi.sendopts
Class Option

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.

An option can have letter short version, long name. It can accept arguments, one argument or an array of additional arguments.

---

Field Summary
static char	NO_SHORT_NAME           Constant that represents no short name indicator.

 

Method Summary
static Option	additionalArguments(char shortName, String longName)           Creates an option that can accept additional arguments.
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 shortDescription(org.netbeans.spi.sendopts.Option, java.lang.String, java.lang.String) and 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 shortDescription(org.netbeans.spi.sendopts.Option, java.lang.String, java.lang.String) and 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 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 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 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 (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 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 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 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 defaultArguments() option, but also appropriate 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.

---

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

---

Overview  Package   Class  Use  Tree  Deprecated  Index  Help		org.netbeans.modules.sendopts/2 2.0
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

Built on May 28 2007.  |  Portions Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.