snaq.util.jclap
Class CLAParser

java.lang.Object
  extended by snaq.util.jclap.CLAParser

public final class CLAParser
extends java.lang.Object

Utility class to provide support for command-line options parsing. Has support for POSIX-style short-form (e.g. -v) and GNU-style long-form (e.g. --verbose) options (short-form is mandatory, long-form optional). Option processing can be explicitly terminated by the argument "--", to allow (non-option) arguments to be specified.

As already mentioned, all options must have at least a short name, and may also have a long name, which is optional but strongly encouraged. An option that requires no value is considered a boolean/flag. Options that require values have the value specified immediately after the option name on the command-line. For example, an option to display a help message might be specified with the short name ? and the long name help (abbreviated to [-?,--help] in the usage message). An option for a size value might be specified as [-s,--size] and require a value parameter, which may be specified in any of these forms:

Combining these the command-line may look like these examples, depending how the application has been configured:

     java AppName [-?,--help] [--size <integer>]
     java AppName -w,--width <integer> -h,--height <integer> [-?]
 
where options in [brackets] are optional, and others are mandatory.

Here are some of the useful features of JCLAP compared to some other parsers:

Automatic usage printing can be accessed via the printUsage(...) method, allowing printing to a specified PrintStream in either long or short versions. The options are printed in the same order in which they were added to the CLAParser instance. The command used to launch the application can either be user-specified, or can be deduced automatically if required. An additional usage suffix string can also be specified if required, allowing use of non-option arguments.

Internationalization support is included for a few locales (en/fr/de/es/pt), and may be extended in future. If required users may author their own locale property files to reference.

For an example of how to use the CLAParser class, visit the website.

Author:
Giles Winstanley
See Also:
JCLAP website

Constructor Summary
CLAParser()
          Creates a new CLAParser instance, using the default locale.
 
Method Summary
 Option<java.lang.Boolean> addBooleanOption(java.lang.String shortName)
          Convenience method to add an Option of type Boolean (single value allowed).
 Option<java.lang.Boolean> addBooleanOption(java.lang.String shortName, boolean allowMany)
          Convenience method to add an Option of type Boolean.
 Option<java.lang.Boolean> addBooleanOption(java.lang.String shortName, java.lang.String longName, java.lang.String description)
          Convenience method to add an Option of type Boolean (single value allowed).
 Option<java.lang.Boolean> addBooleanOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, boolean allowMany)
          Convenience method to add an Option of type Boolean.
 Option<java.lang.Boolean> addBooleanOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, int minCount, int maxCount)
          Convenience method to add an Option of type Boolean.
 Option<java.lang.Double> addDoubleOption(java.lang.String shortName, boolean mandatory, boolean allowMany)
          Convenience method to add an Option of type Double.
 Option<java.lang.Double> addDoubleOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, boolean mandatory, boolean allowMany)
          Convenience method to add an Option of type Double.
 Option<java.lang.Integer> addEnumIntegerOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, boolean mandatory, boolean allowMany, int[] allowedValues)
          Convenience method to add an Option of enumerated Integer type.
 Option<java.lang.Integer> addEnumIntegerOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, int[] allowedValues)
          Convenience method to add an Option of enumerated Integer type (single value allowed, non-mandatory).
 Option<java.lang.String> addEnumStringOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, boolean mandatory, boolean allowMany, java.lang.String[] allowedValues)
          Convenience method to add an Option of enumerated String type (case-insensitive string matching).
 Option<java.lang.String> addEnumStringOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, boolean mandatory, boolean allowMany, java.lang.String[] allowedValues, boolean ignoreCase)
          Convenience method to add an Option of enumerated String type.
 Option<java.lang.String> addEnumStringOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, java.lang.String[] allowedValues)
          Convenience method to add an Option of enumerated String type (single value allowed, non-mandatory).
 Option<java.lang.String> addFileExistingOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, boolean mandatory, boolean allowMany)
          Convenience method to add an Option of type String which refers to an existing file (which is not a folder).
 Option<java.lang.String> addFileExistingOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, int minCount, int maxCount)
          Convenience method to add an Option of type String which refers to an existing file (which is not a folder).
 Option<java.lang.String> addFileNewOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, boolean mandatory, boolean allowMany)
          Convenience method to add an Option of type String which refers to a new or existing file/folder.
 Option<java.lang.String> addFileOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, boolean mandatory, boolean allowMany)
          Convenience method to add an Option of type String which refers to a file/folder.
 Option<java.lang.Float> addFloatOption(java.lang.String shortName, boolean mandatory, boolean allowMany)
          Convenience method to add an Option of type Float.
 Option<java.lang.Float> addFloatOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, boolean mandatory, boolean allowMany)
          Convenience method to add an Option of type Float.
 Option<java.lang.String> addFolderExistingOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, boolean mandatory, boolean allowMany)
          Convenience method to add an Option of type String which refers to an existing folder.
 Option<java.lang.String> addFolderExistingOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, int minCount, int maxCount)
          Convenience method to add an Option of type String which refers to an existing folder.
 Option<java.lang.Integer> addIntegerOption(java.lang.String shortName, boolean mandatory, boolean allowMany)
          Convenience method to add an Option of type Integer.
 Option<java.lang.Integer> addIntegerOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, boolean mandatory, boolean allowMany)
          Convenience method to add an Option of type Integer.
 Option<java.lang.Long> addLongOption(java.lang.String shortName, boolean mandatory, boolean allowMany)
          Convenience method to add an Option of type Long.
 Option<java.lang.Long> addLongOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, boolean mandatory, boolean allowMany)
          Convenience method to add an Option of type Long.
<T> Option<T>
addOption(Option<T> opt)
          Adds the specified Option to the list of those to be parsed from the command-line arguments.
 Option<java.lang.String> addStringOption(java.lang.String shortName, boolean mandatory, boolean allowMany)
          Convenience method to add an Option of type String (no long name, no description).
 Option<java.lang.String> addStringOption(java.lang.String shortName, java.lang.String longName, java.lang.String description)
          Convenience method to add an Option of type String (single value allowed, non-mandatory).
 Option<java.lang.String> addStringOption(java.lang.String shortName, java.lang.String longName, java.lang.String description, boolean mandatory, boolean allowMany)
          Convenience method to add an Option of type String.
 java.lang.Boolean getBooleanOptionValue(java.lang.String optionName)
          Convenience method to return the parsed value of the named option, or false if the option was not set.
 java.lang.Boolean getBooleanOptionValue(java.lang.String optionName, java.lang.Boolean def)
          Convenience method to return the parsed value of the named option, or the specified default value if the option was not set.
 java.util.List<java.lang.Boolean> getBooleanOptionValues(java.lang.String optionName)
          Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.
 java.lang.Double getDoubleOptionValue(java.lang.String optionName, java.lang.Double def)
          Convenience method to return the parsed value of the named option, or the specified default value if the option was not set.
 java.util.List<java.lang.Double> getDoubleOptionValues(java.lang.String optionName)
          Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.
 java.lang.Float getFloatOptionValue(java.lang.String optionName, java.lang.Float def)
          Convenience method to return the parsed value of the named option, or the specified default value if the option was not set.
 java.util.List<java.lang.Float> getFloatOptionValues(java.lang.String optionName)
          Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.
 java.lang.Integer getIntegerOptionValue(java.lang.String optionName, java.lang.Integer def)
          Convenience method to return the parsed value of the named option, or the specified default value if the option was not set.
 java.util.List<java.lang.Integer> getIntegerOptionValues(java.lang.String optionName)
          Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.
 java.lang.Long getLongOptionValue(java.lang.String optionName, java.lang.Long def)
          Convenience method to return the parsed value of the named option, or the specified default value if the option was not set.
 java.util.List<java.lang.Long> getLongOptionValues(java.lang.String optionName)
          Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.
 java.util.List<java.lang.String> getNonOptionArguments()
          Returns a list of the non-option command-line arguments.
<T> Option<T>
getOption(java.lang.String optionName, java.lang.Class<T> type)
          Returns the Option with the specified name (either short or long).
 java.util.List<Option> getOptions()
          Returns all the Option instances registered with the parser.
<T> T
getOptionValue(Option<T> opt)
          Convenience method to return the parsed value of the specified option, or null if the option was not set.
<T> T
getOptionValue(Option<T> opt, T def)
          Convenience method to return the parsed value of the specified option, or the specified default value if the option was not set.
<T> T
getOptionValue(java.lang.String optionName, java.lang.Class<T> type)
          Convenience method to return the parsed value of the named option, or null if the option was not set, equivalent to getOptionValue(optionName, type, null).
<T> T
getOptionValue(java.lang.String optionName, java.lang.Class<T> type, T def)
          Convenience method to return the parsed value of the named option, or the specified default value if the option was not set.
<T> java.util.List<T>
getOptionValues(Option<T> opt)
          Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.
<T> java.util.List<T>
getOptionValues(java.lang.String optionName, java.lang.Class<T> type)
          Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.
 java.lang.String getStringOptionValue(java.lang.String optionName, java.lang.String def)
          Convenience method to return the parsed value of the named option, or the specified default value if the option was not set.
 java.util.List<java.lang.String> getStringOptionValues(java.lang.String optionName)
          Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.
 void parse(java.lang.String[] args)
          Extract the option-mapped and unmapped arguments from the given array of command-line arguments, using the specified locale.
 boolean parsedSolitaryHyphen()
          Returns whether a single - argument was found.
 void parseOrig(java.lang.String[] args)
          Extract the option-mapped and unmapped arguments from the given array of command-line arguments, using the specified locale.
 void printUsage(java.io.PrintStream ps, boolean longUsage)
          Prints the command-line usage message to the specified PrintStream, making a guess at the application launch command.
 void printUsage(java.io.PrintStream ps, boolean longUsage, java.lang.String suffixArgs)
          Prints the command-line usage message to the specified PrintStream.
 void printUsage(java.io.PrintStream ps, boolean longUsage, java.lang.String appString, java.lang.String suffixArgs)
          Prints the command-line usage message to the specified PrintStream.
 void setHidden(java.lang.String optionName)
          Hides the specified Option from being printed in the usage message.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CLAParser

public CLAParser()
Creates a new CLAParser instance, using the default locale.

Method Detail

parsedSolitaryHyphen

public boolean parsedSolitaryHyphen()
Returns whether a single - argument was found. This is typically used to specify that an application should read from STDIN or write to STDOUT. The argument is written to the non-option arguments, so this can be tested independently, but this is just a convenience method to do the same.


addOption

public <T> Option<T> addOption(Option<T> opt)
Adds the specified Option to the list of those to be parsed from the command-line arguments.

Type Parameters:
T - the return type of the option
Parameters:
opt - Option instance to add
Returns:
the Option instance that was added
Throws:
java.lang.IllegalArgumentException - if either short/long name of the specified Option is already in use

setHidden

public void setHidden(java.lang.String optionName)
               throws OptionException
Hides the specified Option from being printed in the usage message.

Parameters:
optionName - short/long name of option to "hide"
Throws:
OptionException - if the specified option can't be found

addBooleanOption

public Option<java.lang.Boolean> addBooleanOption(java.lang.String shortName,
                                                  java.lang.String longName,
                                                  java.lang.String description,
                                                  int minCount,
                                                  int maxCount)
Convenience method to add an Option of type Boolean.

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
minCount - minimum number of occurrences required for this option
maxCount - maximum number of occurrences required for this option
Returns:
the new Option instance

addBooleanOption

public Option<java.lang.Boolean> addBooleanOption(java.lang.String shortName,
                                                  java.lang.String longName,
                                                  java.lang.String description,
                                                  boolean allowMany)
Convenience method to add an Option of type Boolean.

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
allowMany - whether this option can take more than one value (i.e. be specified more than once)
Returns:
the new Option instance

addBooleanOption

public Option<java.lang.Boolean> addBooleanOption(java.lang.String shortName,
                                                  java.lang.String longName,
                                                  java.lang.String description)
Convenience method to add an Option of type Boolean (single value allowed).

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
Returns:
the new Option instance

addBooleanOption

public Option<java.lang.Boolean> addBooleanOption(java.lang.String shortName,
                                                  boolean allowMany)
Convenience method to add an Option of type Boolean.

Parameters:
shortName - short name of the option
allowMany - whether this option can take more than one value (i.e. be specified more than once)
Returns:
the new Option instance

addBooleanOption

public Option<java.lang.Boolean> addBooleanOption(java.lang.String shortName)
Convenience method to add an Option of type Boolean (single value allowed).

Parameters:
shortName - short name of the option
Returns:
the new Option instance

addIntegerOption

public Option<java.lang.Integer> addIntegerOption(java.lang.String shortName,
                                                  java.lang.String longName,
                                                  java.lang.String description,
                                                  boolean mandatory,
                                                  boolean allowMany)
Convenience method to add an Option of type Integer.

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
Returns:
the new Option instance

addIntegerOption

public Option<java.lang.Integer> addIntegerOption(java.lang.String shortName,
                                                  boolean mandatory,
                                                  boolean allowMany)
Convenience method to add an Option of type Integer.

Parameters:
shortName - short name of the option
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
Returns:
the new Option instance

addLongOption

public Option<java.lang.Long> addLongOption(java.lang.String shortName,
                                            java.lang.String longName,
                                            java.lang.String description,
                                            boolean mandatory,
                                            boolean allowMany)
Convenience method to add an Option of type Long.

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
Returns:
the new Option instance

addLongOption

public Option<java.lang.Long> addLongOption(java.lang.String shortName,
                                            boolean mandatory,
                                            boolean allowMany)
Convenience method to add an Option of type Long.

Parameters:
shortName - short name of the option
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
Returns:
the new Option instance

addDoubleOption

public Option<java.lang.Double> addDoubleOption(java.lang.String shortName,
                                                java.lang.String longName,
                                                java.lang.String description,
                                                boolean mandatory,
                                                boolean allowMany)
Convenience method to add an Option of type Double.

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
Returns:
the new Option instance

addDoubleOption

public Option<java.lang.Double> addDoubleOption(java.lang.String shortName,
                                                boolean mandatory,
                                                boolean allowMany)
Convenience method to add an Option of type Double.

Parameters:
shortName - short name of the option
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
Returns:
the new Option instance

addFloatOption

public Option<java.lang.Float> addFloatOption(java.lang.String shortName,
                                              java.lang.String longName,
                                              java.lang.String description,
                                              boolean mandatory,
                                              boolean allowMany)
Convenience method to add an Option of type Float.

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
Returns:
the new Option instance

addFloatOption

public Option<java.lang.Float> addFloatOption(java.lang.String shortName,
                                              boolean mandatory,
                                              boolean allowMany)
Convenience method to add an Option of type Float.

Parameters:
shortName - short name of the option
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
Returns:
the new Option instance

addStringOption

public Option<java.lang.String> addStringOption(java.lang.String shortName,
                                                java.lang.String longName,
                                                java.lang.String description,
                                                boolean mandatory,
                                                boolean allowMany)
Convenience method to add an Option of type String.

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
Returns:
the new Option instance

addStringOption

public Option<java.lang.String> addStringOption(java.lang.String shortName,
                                                java.lang.String longName,
                                                java.lang.String description)
Convenience method to add an Option of type String (single value allowed, non-mandatory).

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
Returns:
the new Option instance

addStringOption

public Option<java.lang.String> addStringOption(java.lang.String shortName,
                                                boolean mandatory,
                                                boolean allowMany)
Convenience method to add an Option of type String (no long name, no description).

Parameters:
shortName - short name of the option
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
Returns:
the new Option instance

addFileOption

public Option<java.lang.String> addFileOption(java.lang.String shortName,
                                              java.lang.String longName,
                                              java.lang.String description,
                                              boolean mandatory,
                                              boolean allowMany)
Convenience method to add an Option of type String which refers to a file/folder. For example, use this method to:

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
Returns:
the new Option instance

addFileNewOption

public Option<java.lang.String> addFileNewOption(java.lang.String shortName,
                                                 java.lang.String longName,
                                                 java.lang.String description,
                                                 boolean mandatory,
                                                 boolean allowMany)
Convenience method to add an Option of type String which refers to a new or existing file/folder.

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
Returns:
the new Option instance

addFileExistingOption

public Option<java.lang.String> addFileExistingOption(java.lang.String shortName,
                                                      java.lang.String longName,
                                                      java.lang.String description,
                                                      int minCount,
                                                      int maxCount)
Convenience method to add an Option of type String which refers to an existing file (which is not a folder). For example, use this method to:

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
minCount - minimum number of occurrences required for this option
maxCount - maximum number of occurrences required for this option
Returns:
the new Option instance

addFileExistingOption

public Option<java.lang.String> addFileExistingOption(java.lang.String shortName,
                                                      java.lang.String longName,
                                                      java.lang.String description,
                                                      boolean mandatory,
                                                      boolean allowMany)
Convenience method to add an Option of type String which refers to an existing file (which is not a folder). For example, use this method to:

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
Returns:
the new Option instance

addFolderExistingOption

public Option<java.lang.String> addFolderExistingOption(java.lang.String shortName,
                                                        java.lang.String longName,
                                                        java.lang.String description,
                                                        int minCount,
                                                        int maxCount)
Convenience method to add an Option of type String which refers to an existing folder. For example, use this method to enforce specification of an existing folder. To allow specification of a new folder (one that does not yet exist), use the addFileOption() method instead.

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
minCount - minimum number of occurrences required for this option
maxCount - maximum number of occurrences required for this option
Returns:
the new Option instance

addFolderExistingOption

public Option<java.lang.String> addFolderExistingOption(java.lang.String shortName,
                                                        java.lang.String longName,
                                                        java.lang.String description,
                                                        boolean mandatory,
                                                        boolean allowMany)
Convenience method to add an Option of type String which refers to an existing folder. For example, use this method to enforce specification of an existing folder. To allow specification of a new folder (one that does not yet exist), use the addFileOption() method instead.

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
Returns:
the new Option instance

addEnumStringOption

public Option<java.lang.String> addEnumStringOption(java.lang.String shortName,
                                                    java.lang.String longName,
                                                    java.lang.String description,
                                                    boolean mandatory,
                                                    boolean allowMany,
                                                    java.lang.String[] allowedValues,
                                                    boolean ignoreCase)
Convenience method to add an Option of enumerated String type.

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
allowedValues - array of string values allowed by this enumerated option
ignoreCase - whether to ignore the case of string values
Returns:
the new Option instance

addEnumStringOption

public Option<java.lang.String> addEnumStringOption(java.lang.String shortName,
                                                    java.lang.String longName,
                                                    java.lang.String description,
                                                    boolean mandatory,
                                                    boolean allowMany,
                                                    java.lang.String[] allowedValues)
Convenience method to add an Option of enumerated String type (case-insensitive string matching).

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
allowedValues - array of string values allowed by this enumerated option
Returns:
the new Option instance

addEnumStringOption

public Option<java.lang.String> addEnumStringOption(java.lang.String shortName,
                                                    java.lang.String longName,
                                                    java.lang.String description,
                                                    java.lang.String[] allowedValues)
Convenience method to add an Option of enumerated String type (single value allowed, non-mandatory).

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
allowedValues - array of string values allowed by this enumerated option
Returns:
the new Option instance

addEnumIntegerOption

public Option<java.lang.Integer> addEnumIntegerOption(java.lang.String shortName,
                                                      java.lang.String longName,
                                                      java.lang.String description,
                                                      boolean mandatory,
                                                      boolean allowMany,
                                                      int[] allowedValues)
Convenience method to add an Option of enumerated Integer type.

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
mandatory - whether this option must be specified
allowMany - whether this option can take more than one value (i.e. be specified more than once)
allowedValues - array of string values allowed by this enumerated option
Returns:
the new Option instance

addEnumIntegerOption

public Option<java.lang.Integer> addEnumIntegerOption(java.lang.String shortName,
                                                      java.lang.String longName,
                                                      java.lang.String description,
                                                      int[] allowedValues)
Convenience method to add an Option of enumerated Integer type (single value allowed, non-mandatory).

Parameters:
shortName - short name of the option
longName - long name of the option
description - helpful description of the option (printed for usage message)
allowedValues - array of string values allowed by this enumerated option
Returns:
the new Option instance

getOption

public <T> Option<T> getOption(java.lang.String optionName,
                               java.lang.Class<T> type)
                    throws OptionException
Returns the Option with the specified name (either short or long).

Parameters:
optionName - option name for which to get value (either short/long)
type - class type for option value compatability check
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getOptions

public final java.util.List<Option> getOptions()
                                        throws OptionException
Returns all the Option instances registered with the parser.

Throws:
OptionException

getOptionValues

public <T> java.util.List<T> getOptionValues(Option<T> opt)
                                  throws OptionException
Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.

Type Parameters:
T - the return type of the option
Parameters:
opt - option for which to get values
Returns:
A list of all the parsed values for the specified option, or an empty list if the option was not set.
Throws:
OptionException - if opt is null, cannot be found, or is of the wrong type

getOptionValues

public <T> java.util.List<T> getOptionValues(java.lang.String optionName,
                                             java.lang.Class<T> type)
                                  throws OptionException
Returns a list of all the parsed values for the specified option, or an empty list if the option was not set. This method performs type-checking of the Option.

Parameters:
optionName - option name for which to get value (either short/long)
type - class type for option value compatability check
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getOptionValue

public <T> T getOptionValue(Option<T> opt)
                 throws OptionException
Convenience method to return the parsed value of the specified option, or null if the option was not set. This method is only usable with options that cannot take multiple values.

Type Parameters:
T - the return type of the option
Parameters:
opt - option for which to get value
Throws:
OptionException - if opt is null, cannot be found, or is of the wrong type

getOptionValue

public <T> T getOptionValue(Option<T> opt,
                            T def)
                 throws OptionException
Convenience method to return the parsed value of the specified option, or the specified default value if the option was not set. This method is only usable with options that cannot take multiple values.

Type Parameters:
T - the return type of the option
Parameters:
opt - option for which to get value
def - default value to use if the option was not set
Throws:
OptionException - if opt is null, cannot be found, or is of the wrong type

getOptionValue

public <T> T getOptionValue(java.lang.String optionName,
                            java.lang.Class<T> type,
                            T def)
                 throws OptionException
Convenience method to return the parsed value of the named option, or the specified default value if the option was not set. This method should only be used with typed options that cannot take multiple values.

Parameters:
optionName - name of the option
type - class type for option value compatability check
def - default value to use if the option was not set
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getOptionValue

public <T> T getOptionValue(java.lang.String optionName,
                            java.lang.Class<T> type)
                 throws OptionException
Convenience method to return the parsed value of the named option, or null if the option was not set, equivalent to getOptionValue(optionName, type, null). This method should only be used with typed options that cannot take multiple values.

Parameters:
optionName - name of the option
type - class type for option value compatability check
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getBooleanOptionValues

public java.util.List<java.lang.Boolean> getBooleanOptionValues(java.lang.String optionName)
                                                         throws OptionException
Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.

Parameters:
optionName - name of the option
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getBooleanOptionValue

public java.lang.Boolean getBooleanOptionValue(java.lang.String optionName,
                                               java.lang.Boolean def)
                                        throws OptionException
Convenience method to return the parsed value of the named option, or the specified default value if the option was not set. This method should only be used with options that cannot take multiple values.

Parameters:
optionName - name of the option
def - default value to use if the option was not set
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getBooleanOptionValue

public java.lang.Boolean getBooleanOptionValue(java.lang.String optionName)
                                        throws OptionException
Convenience method to return the parsed value of the named option, or false if the option was not set. This method should only be used with options that cannot take multiple values.

Parameters:
optionName - name of the option
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getIntegerOptionValues

public java.util.List<java.lang.Integer> getIntegerOptionValues(java.lang.String optionName)
                                                         throws OptionException
Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.

Parameters:
optionName - name of the option
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getIntegerOptionValue

public java.lang.Integer getIntegerOptionValue(java.lang.String optionName,
                                               java.lang.Integer def)
                                        throws OptionException
Convenience method to return the parsed value of the named option, or the specified default value if the option was not set. This method should only be used with options that cannot take multiple values.

Parameters:
optionName - name of the option
def - default value to use if the option was not set
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getLongOptionValues

public java.util.List<java.lang.Long> getLongOptionValues(java.lang.String optionName)
                                                   throws OptionException
Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.

Parameters:
optionName - name of the option
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getLongOptionValue

public java.lang.Long getLongOptionValue(java.lang.String optionName,
                                         java.lang.Long def)
                                  throws OptionException
Convenience method to return the parsed value of the named option, or the specified default value if the option was not set. This method should only be used with options that cannot take multiple values.

Parameters:
optionName - name of the option
def - default value to use if the option was not set
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getDoubleOptionValues

public java.util.List<java.lang.Double> getDoubleOptionValues(java.lang.String optionName)
                                                       throws OptionException
Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.

Parameters:
optionName - name of the option
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getDoubleOptionValue

public java.lang.Double getDoubleOptionValue(java.lang.String optionName,
                                             java.lang.Double def)
                                      throws OptionException
Convenience method to return the parsed value of the named option, or the specified default value if the option was not set. This method should only be used with options that cannot take multiple values.

Parameters:
optionName - name of the option
def - default value to use if the option was not set
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getFloatOptionValues

public java.util.List<java.lang.Float> getFloatOptionValues(java.lang.String optionName)
                                                     throws OptionException
Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.

Parameters:
optionName - name of the option
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getFloatOptionValue

public java.lang.Float getFloatOptionValue(java.lang.String optionName,
                                           java.lang.Float def)
                                    throws OptionException
Convenience method to return the parsed value of the named option, or the specified default value if the option was not set. This method should only be used with options that cannot take multiple values.

Parameters:
optionName - name of the option
def - default value to use if the option was not set
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getStringOptionValues

public java.util.List<java.lang.String> getStringOptionValues(java.lang.String optionName)
                                                       throws OptionException
Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.

Parameters:
optionName - name of the option
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getStringOptionValue

public java.lang.String getStringOptionValue(java.lang.String optionName,
                                             java.lang.String def)
                                      throws OptionException
Convenience method to return the parsed value of the named option, or the specified default value if the option was not set. This method should only be used with options that cannot take multiple values.

Parameters:
optionName - name of the option
def - default value to use if the option was not set
Throws:
OptionException - if optionName is null, cannot be found, or is of the wrong type

getNonOptionArguments

public java.util.List<java.lang.String> getNonOptionArguments()
Returns a list of the non-option command-line arguments. Note that this list includes all arguments that are not related to options, and as a result may include "orphan" arguments (in between correctly specified options) in addition to the expected arguments that are specified after all the options.

For example:

     java DemoApp -i 10 -f 1.2 foo -s bar fu bar
 

for an application with value-taking options i/f/s, would return [foo,fu,bar] from this method.

Returns:
A list of the command-line string arguments that were not parsed as options.

parseOrig

public void parseOrig(java.lang.String[] args)
               throws OptionException
Extract the option-mapped and unmapped arguments from the given array of command-line arguments, using the specified locale.

Parameters:
args - command-line arguments (as passed into main method)
Throws:
OptionException - if an problem is encountered parsing the specified arguments

parse

public void parse(java.lang.String[] args)
           throws OptionException
Extract the option-mapped and unmapped arguments from the given array of command-line arguments, using the specified locale.

Parameters:
args - command-line arguments (as passed into main method)
Throws:
OptionException - if an problem is encountered parsing the specified arguments

printUsage

public void printUsage(java.io.PrintStream ps,
                       boolean longUsage)
Prints the command-line usage message to the specified PrintStream, making a guess at the application launch command. The usage message is automatically created using the options specified. The usage can be displayed in either short or long versions, although the long version uses the options' description fields, which are not required, but should generally be included if intending to print the long usage.

Parameters:
ps - PrintStream to which to print usage message
longUsage - whether to print long version of usage message (otherwise print short version)

printUsage

public void printUsage(java.io.PrintStream ps,
                       boolean longUsage,
                       java.lang.String suffixArgs)
Prints the command-line usage message to the specified PrintStream. The usage message is automatically created using the options specified. The usage can be displayed in either short or long versions, although the long version uses the options' description fields, which are not required, but should generally be included if intending to print the long usage.

Parameters:
ps - PrintStream to which to print usage message
longUsage - whether to print long version of usage message (otherwise print short version)
suffixArgs - usage suffix string for defining extra arguments

printUsage

public void printUsage(java.io.PrintStream ps,
                       boolean longUsage,
                       java.lang.String appString,
                       java.lang.String suffixArgs)
Prints the command-line usage message to the specified PrintStream. The usage message is automatically created using the options specified. The usage can be displayed in either short or long versions, although the long version uses the options' description fields, which are not required, but should generally be included if intending to print the long usage.

Parameters:
ps - PrintStream to which to print usage message
longUsage - whether to print long version of usage message (otherwise print short version)
appString - usage prefix string describing how application is launched; null specifies to create value automatically (e.g. "java foo.bar.AppName")
suffixArgs - usage suffix string for defining extra arguments