snaq.util.jclap

Class CLAParser

java.lang.Object

snaq.util.jclap.CLAParser

public final class CLAParser
extends 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.

All options must have at least a short name, and may also have a long name (recommended). 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:

• -s 123
• -s=123
• -s:123
• /s 123
• /s=123
• /s:123
• --size 123
• --size=123
• --size:123

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 features of JCLAP:

• Option short names are mandatory, and long names optional (as per POSIX standard, but retaining GNU enhancements).
• Uses a single internally-typed OptionException type for signalling parsing/retrieval problems.
• Supports enumerated option types (String, Integer).
• Supports filtered string option types.
• Supports file/folder option types (using filtered-string feature).
• Supports single-hyphen specification for reading from STDIN.
• Support for automatic usage printing (both long & short styles).
• Basic internationalization support.

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

Constructors

Constructor and Description
CLAParser() Creates a new CLAParser instance, using the default locale.

Method Summary

Modifier and Type	Method and Description
Option<Boolean>	addBooleanOption(String shortName) Convenience method to add an Option of type Boolean (single value allowed).
Option<Boolean>	addBooleanOption(String shortName, boolean allowMany) Convenience method to add an Option of type Boolean.
Option<Boolean>	addBooleanOption(String shortName, int maxCount) Convenience method to add an Option of type Boolean.
Option<Boolean>	addBooleanOption(String shortName, String longName, String description) Convenience method to add an Option of type Boolean (single value allowed).
Option<Boolean>	addBooleanOption(String shortName, String longName, String description, boolean allowMany) Convenience method to add an Option of type Boolean.
Option<Boolean>	addBooleanOption(String shortName, String longName, String description, int maxCount) Convenience method to add an Option of type Boolean.
Option<Boolean>	addBooleanOption(String shortName, String longName, String description, int minCount, int maxCount) Convenience method to add an Option of type Boolean.
Option<Double>	addDoubleOption(String shortName, boolean mandatory, boolean allowMany) Convenience method to add an Option of type Double.
Option<Double>	addDoubleOption(String shortName, int minCount, int maxCount) Convenience method to add an Option of type Double.
Option<Double>	addDoubleOption(String shortName, String longName, String description, boolean mandatory, boolean allowMany) Convenience method to add an Option of type Double.
Option<Double>	addDoubleOption(String shortName, String longName, String description, int minCount, int maxCount) Convenience method to add an Option of type Double.
Option<Integer>	addEnumIntegerOption(String shortName, String longName, String description, boolean mandatory, boolean allowMany, int[] allowedValues) Convenience method to add an Option of enumerated Integer type.
Option<Integer>	addEnumIntegerOption(String shortName, String longName, String description, int[] allowedValues) Convenience method to add an Option of enumerated Integer type (single value allowed, non-mandatory).
Option<String>	addEnumStringOption(String shortName, String longName, String description, boolean mandatory, boolean allowMany, String[] allowedValues) Convenience method to add an Option of enumerated String type (case-insensitive string matching).
Option<String>	addEnumStringOption(String shortName, String longName, String description, boolean mandatory, boolean allowMany, String[] allowedValues, boolean ignoreCase) Convenience method to add an Option of enumerated String type.
Option<String>	addEnumStringOption(String shortName, String longName, String description, int minCount, int maxCount, String[] allowedValues, boolean ignoreCase) Convenience method to add an Option of enumerated String type.
Option<String>	addEnumStringOption(String shortName, String longName, String description, String[] allowedValues) Convenience method to add an Option of enumerated String type (single value allowed, non-mandatory).
Option<String>	addFileExistingOption(String shortName, String longName, 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<String>	addFileExistingOption(String shortName, String longName, 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<String>	addFileNewOption(String shortName, String longName, 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<String>	addFileOption(String shortName, String longName, String description, boolean mandatory, boolean allowMany) Convenience method to add an Option of type String which refers to a file/folder.
Option<Float>	addFloatOption(String shortName, boolean mandatory, boolean allowMany) Convenience method to add an Option of type Float.
Option<Float>	addFloatOption(String shortName, int minCount, int maxCount) Convenience method to add an Option of type Float.
Option<Float>	addFloatOption(String shortName, String longName, String description, boolean mandatory, boolean allowMany) Convenience method to add an Option of type Float.
Option<Float>	addFloatOption(String shortName, String longName, String description, int minCount, int maxCount) Convenience method to add an Option of type Float.
Option<String>	addFolderExistingOption(String shortName, String longName, String description, boolean mandatory, boolean allowMany) Convenience method to add an Option of type String which refers to an existing folder.
Option<String>	addFolderExistingOption(String shortName, String longName, String description, int minCount, int maxCount) Convenience method to add an Option of type String which refers to an existing folder.
Option<Integer>	addIntegerOption(String shortName, boolean mandatory, boolean allowMany) Convenience method to add an Option of type Integer.
Option<Integer>	addIntegerOption(String shortName, int minCount, int maxCount) Convenience method to add an Option of type Integer.
Option<Integer>	addIntegerOption(String shortName, String longName, String description, boolean mandatory, boolean allowMany) Convenience method to add an Option of type Integer.
Option<Integer>	addIntegerOption(String shortName, String longName, String description, int minCount, int maxCount) Convenience method to add an Option of type Integer.
Option<LocalDate>	addLocalDateOption(String shortName, boolean mandatory, boolean allowMany) Convenience method to add an Option of type LocalDate (no long name, no description).
Option<LocalDate>	addLocalDateOption(String shortName, int minCount, int maxCount) Convenience method to add an Option of type LocalDate (no long name, no description).
Option<LocalDate>	addLocalDateOption(String shortName, String longName, String description) Convenience method to add an Option of type LocalDate (single value allowed, non-mandatory).
Option<LocalDate>	addLocalDateOption(String shortName, String longName, String description, boolean mandatory, boolean allowMany) Convenience method to add an Option of type LocalDate.
Option<LocalDate>	addLocalDateOption(String shortName, String longName, String description, int minCount, int maxCount) Convenience method to add an Option of type LocalDate.
Option<Long>	addLongOption(String shortName, boolean mandatory, boolean allowMany) Convenience method to add an Option of type Long.
Option<Long>	addLongOption(String shortName, int minCount, int maxCount) Convenience method to add an Option of type Long.
Option<Long>	addLongOption(String shortName, String longName, String description, boolean mandatory, boolean allowMany) Convenience method to add an Option of type Long.
Option<Long>	addLongOption(String shortName, String longName, String description, int minCount, int maxCount) 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<String>	addStringOption(String shortName, boolean mandatory, boolean allowMany) Convenience method to add an Option of type String (no long name, no description).
Option<String>	addStringOption(String shortName, int minCount, int maxCount) Convenience method to add an Option of type String (no long name, no description).
Option<String>	addStringOption(String shortName, String longName, String description) Convenience method to add an Option of type String (single value allowed, non-mandatory).
Option<String>	addStringOption(String shortName, String longName, String description, boolean mandatory, boolean allowMany) Convenience method to add an Option of type String.
Option<String>	addStringOption(String shortName, String longName, String description, int minCount, int maxCount) Convenience method to add an Option of type String.
Boolean	getBooleanOptionValue(String optionName) Convenience method to return the parsed value of the named option, or false if the option was not set.
Boolean	getBooleanOptionValue(String optionName, Boolean def) Convenience method to return the parsed value of the named option, or the specified default value if the option was not set.
List<Boolean>	getBooleanOptionValues(String optionName) Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.
Double	getDoubleOptionValue(String optionName) Convenience method to return the parsed value of the named option, or null if the option was not set.
Double	getDoubleOptionValue(String optionName, Double def) Convenience method to return the parsed value of the named option, or the specified default value if the option was not set.
List<Double>	getDoubleOptionValues(String optionName) Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.
File	getFileOptionValue(String optionName) Convenience method to return the parsed value of the named option, or null if the option was not set.
File	getFileOptionValue(String optionName, File def) Convenience method to return the parsed value of the named option, or the specified default value if the option was not set.
List<File>	getFileOptionValues(String optionName) Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.
Float	getFloatOptionValue(String optionName) Convenience method to return the parsed value of the named option, or null if the option was not set.
Float	getFloatOptionValue(String optionName, Float def) Convenience method to return the parsed value of the named option, or the specified default value if the option was not set.
List<Float>	getFloatOptionValues(String optionName) Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.
Integer	getIntegerOptionValue(String optionName) Convenience method to return the parsed value of the named option, or null if the option was not set.
Integer	getIntegerOptionValue(String optionName, Integer def) Convenience method to return the parsed value of the named option, or the specified default value if the option was not set.
List<Integer>	getIntegerOptionValues(String optionName) Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.
LocalDate	getLocalDateOptionValue(String optionName) Convenience method to return the parsed value of the named option, or null if the option was not set.
LocalDate	getLocalDateOptionValue(String optionName, LocalDate def) Convenience method to return the parsed value of the named option, or the specified default value if the option was not set.
List<LocalDate>	getLocalDateOptionValues(String optionName) Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.
Long	getLongOptionValue(String optionName) Convenience method to return the parsed value of the named option, or null if the option was not set.
Long	getLongOptionValue(String optionName, Long def) Convenience method to return the parsed value of the named option, or the specified default value if the option was not set.
List<Long>	getLongOptionValues(String optionName) Returns a list of all the parsed values for the specified option, or an empty list if the option was not set.
List<String>	getNonOptionArguments() Returns a list of the non-option command-line arguments.
<T> Option<T>	getOption(String optionName, Class<T> type) Returns the Option with the specified name (either short or long).
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(String optionName, 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(String optionName, 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> 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> List<T>	getOptionValues(String optionName, 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.
String	getStringOptionValue(String optionName) Convenience method to return the parsed value of the named option, or null if the option was not set.
String	getStringOptionValue(String optionName, String def) Convenience method to return the parsed value of the named option, or the specified default value if the option was not set.
List<String>	getStringOptionValues(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(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(String[] args) Extract the option-mapped and unmapped arguments from the given array of command-line arguments, using the specified locale.
void	printUsage(PrintStream ps, boolean longUsage) Prints the command-line usage message to the specified PrintStream, making a guess at the application launch command.
void	printUsage(PrintStream ps, boolean longUsage, String suffixArgs) Prints the command-line usage message to the specified PrintStream.
void	printUsage(PrintStream ps, boolean longUsage, String appString, String suffixArgs) Prints the command-line usage message to the specified PrintStream.
void	setHidden(String optionName) Hides the specified Option from being printed in the usage message.

Methods inherited from class java.lang.Object

clone, equals, finalize, 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.

Returns:

true if solitary hyphen was parsed, false otherwise

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:

IllegalArgumentException - if either short/long name of the specified Option is already in use

setHidden

public void setHidden(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<Boolean> addBooleanOption(String shortName,
                                        String longName,
                                        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<Boolean> addBooleanOption(String shortName,
                                        String longName,
                                        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<Boolean> addBooleanOption(String shortName,
                                        String longName,
                                        String description,
                                        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)

maxCount - maximum number of occurrences required for this option

Returns:

the new Option instance

addBooleanOption

public Option<Boolean> addBooleanOption(String shortName,
                                        String longName,
                                        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<Boolean> addBooleanOption(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<Boolean> addBooleanOption(String shortName,
                                        int maxCount)

Convenience method to add an Option of type Boolean.

Parameters:

shortName - short name of the option

maxCount - maximum number of occurrences required for this option

Returns:

the new Option instance

addBooleanOption

public Option<Boolean> addBooleanOption(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<Integer> addIntegerOption(String shortName,
                                        String longName,
                                        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<Integer> addIntegerOption(String shortName,
                                        String longName,
                                        String description,
                                        int minCount,
                                        int maxCount)

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)

minCount - minimum number of occurrences required for this option

maxCount - maximum number of occurrences required for this option

Returns:

the new Option instance

addIntegerOption

public Option<Integer> addIntegerOption(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

addIntegerOption

public Option<Integer> addIntegerOption(String shortName,
                                        int minCount,
                                        int maxCount)

Convenience method to add an Option of type Integer.

Parameters:

shortName - short name of the option

minCount - minimum number of occurrences required for this option

maxCount - maximum number of occurrences required for this option

Returns:

the new Option instance

addLongOption

public Option<Long> addLongOption(String shortName,
                                  String longName,
                                  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<Long> addLongOption(String shortName,
                                  String longName,
                                  String description,
                                  int minCount,
                                  int maxCount)

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)

minCount - minimum number of occurrences required for this option

maxCount - maximum number of occurrences required for this option

Returns:

the new Option instance

addLongOption

public Option<Long> addLongOption(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

addLongOption

public Option<Long> addLongOption(String shortName,
                                  int minCount,
                                  int maxCount)

Convenience method to add an Option of type Long.

Parameters:

shortName - short name of the option

minCount - minimum number of occurrences required for this option

maxCount - maximum number of occurrences required for this option

Returns:

the new Option instance

addDoubleOption

public Option<Double> addDoubleOption(String shortName,
                                      String longName,
                                      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<Double> addDoubleOption(String shortName,
                                      String longName,
                                      String description,
                                      int minCount,
                                      int maxCount)

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)

minCount - minimum number of occurrences required for this option

maxCount - maximum number of occurrences required for this option

Returns:

the new Option instance

addDoubleOption

public Option<Double> addDoubleOption(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

addDoubleOption

public Option<Double> addDoubleOption(String shortName,
                                      int minCount,
                                      int maxCount)

Convenience method to add an Option of type Double.

Parameters:

shortName - short name of the option

minCount - minimum number of occurrences required for this option

maxCount - maximum number of occurrences required for this option

Returns:

the new Option instance

addFloatOption

public Option<Float> addFloatOption(String shortName,
                                    String longName,
                                    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<Float> addFloatOption(String shortName,
                                    String longName,
                                    String description,
                                    int minCount,
                                    int maxCount)

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)

minCount - minimum number of occurrences required for this option

maxCount - maximum number of occurrences required for this option

Returns:

the new Option instance

addFloatOption

public Option<Float> addFloatOption(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

addFloatOption

public Option<Float> addFloatOption(String shortName,
                                    int minCount,
                                    int maxCount)

Convenience method to add an Option of type Float.

Parameters:

shortName - short name of the option

minCount - minimum number of occurrences required for this option

maxCount - maximum number of occurrences required for this option

Returns:

the new Option instance

addStringOption

public Option<String> addStringOption(String shortName,
                                      String longName,
                                      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<String> addStringOption(String shortName,
                                      String longName,
                                      String description,
                                      int minCount,
                                      int maxCount)

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)

minCount - minimum number of occurrences required for this option

maxCount - maximum number of occurrences required for this option

Returns:

the new Option instance

addStringOption

public Option<String> addStringOption(String shortName,
                                      String longName,
                                      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<String> addStringOption(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

addStringOption

public Option<String> addStringOption(String shortName,
                                      int minCount,
                                      int maxCount)

Convenience method to add an Option of type String (no long name, no description).

Parameters:

shortName - short name of the option

minCount - minimum number of occurrences required for this option

maxCount - maximum number of occurrences required for this option

Returns:

the new Option instance

addFileOption

public Option<String> addFileOption(String shortName,
                                    String longName,
                                    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:

• Allow specification of a existing or new 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

addFileNewOption

public Option<String> addFileNewOption(String shortName,
                                       String longName,
                                       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<String> addFileExistingOption(String shortName,
                                            String longName,
                                            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:

• Enforce specification of an existing file (which is not a folder)

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<String> addFileExistingOption(String shortName,
                                            String longName,
                                            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:

• Enforce specification of an existing file (which is not a 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

addFolderExistingOption

public Option<String> addFolderExistingOption(String shortName,
                                              String longName,
                                              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<String> addFolderExistingOption(String shortName,
                                              String longName,
                                              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<String> addEnumStringOption(String shortName,
                                          String longName,
                                          String description,
                                          boolean mandatory,
                                          boolean allowMany,
                                          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<String> addEnumStringOption(String shortName,
                                          String longName,
                                          String description,
                                          int minCount,
                                          int maxCount,
                                          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)

minCount - minimum number of occurrences required for this option

maxCount - maximum number of occurrences required for this option

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<String> addEnumStringOption(String shortName,
                                          String longName,
                                          String description,
                                          boolean mandatory,
                                          boolean allowMany,
                                          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<String> addEnumStringOption(String shortName,
                                          String longName,
                                          String description,
                                          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<Integer> addEnumIntegerOption(String shortName,
                                            String longName,
                                            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<Integer> addEnumIntegerOption(String shortName,
                                            String longName,
                                            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

addLocalDateOption

public Option<LocalDate> addLocalDateOption(String shortName,
                                            String longName,
                                            String description,
                                            boolean mandatory,
                                            boolean allowMany)

Convenience method to add an Option of type LocalDate.

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

addLocalDateOption

public Option<LocalDate> addLocalDateOption(String shortName,
                                            String longName,
                                            String description,
                                            int minCount,
                                            int maxCount)

Convenience method to add an Option of type LocalDate.

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

addLocalDateOption

public Option<LocalDate> addLocalDateOption(String shortName,
                                            String longName,
                                            String description)

Convenience method to add an Option of type LocalDate (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

addLocalDateOption

public Option<LocalDate> addLocalDateOption(String shortName,
                                            boolean mandatory,
                                            boolean allowMany)

Convenience method to add an Option of type LocalDate (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

addLocalDateOption

public Option<LocalDate> addLocalDateOption(String shortName,
                                            int minCount,
                                            int maxCount)

Convenience method to add an Option of type LocalDate (no long name, no description).

Parameters:

shortName - short name of the option

minCount - minimum number of occurrences required for this option

maxCount - maximum number of occurrences required for this option

Returns:

the new Option instance

getOption

public <T> Option<T> getOption(String optionName,
                               Class<T> type)
                        throws OptionException

Returns the Option with the specified name (either short or long).

Type Parameters:

T - the return type of the option

Parameters:

optionName - option name for which to get value (either short/long)

type - class type for option value compatability check

Returns:

Option instance

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getOptions

public final List<Option> getOptions()

Returns all the Option instances registered with the parser.

Returns:

list of options

getOptionValues

public <T> 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> List<T> getOptionValues(String optionName,
                                   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.

Type Parameters:

T - the return type of the option

Parameters:

optionName - option name for which to get value (either short/long)

type - class type for option value compatability check

Returns:

list of option values

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

Returns:

option 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

Returns:

option value

Throws:

OptionException - if opt is null, cannot be found, or is of the wrong type

getOptionValue

public <T> T getOptionValue(String optionName,
                            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.

Type Parameters:

T - the return type of the option

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

Returns:

option value, or default value if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getOptionValue

public <T> T getOptionValue(String optionName,
                            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.

Type Parameters:

T - the return type of the option

Parameters:

optionName - name of the option

type - class type for option value compatability check

Returns:

option value

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getBooleanOptionValues

public List<Boolean> getBooleanOptionValues(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

Returns:

list of option values

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getBooleanOptionValue

public Boolean getBooleanOptionValue(String optionName,
                                     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

Returns:

option value, or default value if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getBooleanOptionValue

public Boolean getBooleanOptionValue(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. NOTE: this method operates slightly differently compared to the other getXOptionValue(String) methods, in that when the option is not defined, it returned Boolean.FALSE instead of null.

Parameters:

optionName - name of the option

Returns:

option value, or null if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getIntegerOptionValues

public List<Integer> getIntegerOptionValues(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

Returns:

list of option values

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getIntegerOptionValue

public Integer getIntegerOptionValue(String optionName,
                                     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

Returns:

option value, or default value if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getIntegerOptionValue

public Integer getIntegerOptionValue(String optionName)
                              throws OptionException

Convenience method to return the parsed value of the named option, or null 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

Returns:

option value, or null if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getLongOptionValues

public List<Long> getLongOptionValues(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

Returns:

list of option values

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getLongOptionValue

public Long getLongOptionValue(String optionName,
                               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

Returns:

option value, or default value if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getLongOptionValue

public Long getLongOptionValue(String optionName)
                        throws OptionException

Convenience method to return the parsed value of the named option, or null 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

Returns:

option value, or null if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getDoubleOptionValues

public List<Double> getDoubleOptionValues(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

Returns:

list of option values

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getDoubleOptionValue

public Double getDoubleOptionValue(String optionName,
                                   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

Returns:

option value, or default value if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getDoubleOptionValue

public Double getDoubleOptionValue(String optionName)
                            throws OptionException

Convenience method to return the parsed value of the named option, or null 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

Returns:

option value, or null if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getFloatOptionValues

public List<Float> getFloatOptionValues(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

Returns:

list of option values

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getFloatOptionValue

public Float getFloatOptionValue(String optionName,
                                 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

Returns:

option value, or default value if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getFloatOptionValue

public Float getFloatOptionValue(String optionName)
                          throws OptionException

Convenience method to return the parsed value of the named option, or null 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

Returns:

option value, or null if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getStringOptionValues

public List<String> getStringOptionValues(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

Returns:

list of option values

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getStringOptionValue

public String getStringOptionValue(String optionName,
                                   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

Returns:

option value, or default value if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getStringOptionValue

public String getStringOptionValue(String optionName)
                            throws OptionException

Convenience method to return the parsed value of the named option, or null 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

Returns:

option value, or null if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getLocalDateOptionValues

public List<LocalDate> getLocalDateOptionValues(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

Returns:

list of option values

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getLocalDateOptionValue

public LocalDate getLocalDateOptionValue(String optionName,
                                         LocalDate 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

Returns:

option value, or default value if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getLocalDateOptionValue

public LocalDate getLocalDateOptionValue(String optionName)
                                  throws OptionException

Convenience method to return the parsed value of the named option, or null 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

Returns:

option value, or null if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getFileOptionValues

public List<File> getFileOptionValues(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

Returns:

list of option values

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getFileOptionValue

public File getFileOptionValue(String optionName,
                               File 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

Returns:

option value, or default value if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getFileOptionValue

public File getFileOptionValue(String optionName)
                        throws OptionException

Convenience method to return the parsed value of the named option, or null 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

Returns:

option value, or null if option is unset

Throws:

OptionException - if optionName is null, cannot be found, or is of the wrong type

getNonOptionArguments

public List<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(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(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(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(PrintStream ps,
                       boolean longUsage,
                       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(PrintStream ps,
                       boolean longUsage,
                       String appString,
                       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