name.kevinlocke.ultragetopt
Class UltraGetopt

java.lang.Object
  extended by name.kevinlocke.ultragetopt.UltraGetopt

public class UltraGetopt
extends java.lang.Object

Main class of the UltraGetopt system. This class serves as the frontend and the workhorse for command-line processing. In order to process command-line arguments, instantiate this class with the desired options then call the getOptions, getOptionsOrdered, and/or getNonOptionArguments methods to determine which options were encountered. For more detailed documentation and example use cases, see the name.kevinlocke.ultragetopt package documentation.

Version:
0.7.0
Author:
Kevin Locke <kwl7@cornell.edu>

Nested Class Summary
static class UltraGetopt.Behavior
          Different behavior options for UltraGetopt.
 
Constructor Summary
UltraGetopt(java.lang.String[] args, CommandLineOption[] options)
          Creates an instance of UltraGetopt with the default set of options for the platform on which the program is running.
UltraGetopt(java.lang.String[] args, CommandLineOption[] options, java.util.EnumSet<UltraGetopt.Behavior> behavior)
          Creates an instance of UltraGetopt with a chosen compatibility behavior.
UltraGetopt(java.lang.String[] args, CommandLineOption[] options, java.util.EnumSet<UltraGetopt.Behavior> behavior, java.lang.String[] shortleaders, java.lang.String[] longleaders, java.lang.String[] assigners, GetoptErrorFormatter formatter)
          Creates an instance of UltraGetopt with customized behavior based on the specified arguments.
UltraGetopt(java.lang.String programname, java.lang.String[] args, CommandLineOption[] options)
          Creates an instance of UltraGetopt with the default set of options for the platform on which the program is running.
UltraGetopt(java.lang.String programname, java.lang.String[] args, CommandLineOption[] options, java.util.EnumSet<UltraGetopt.Behavior> behavior)
          Creates an instance of UltraGetopt with a chosen compatibility behavior and program name.
 
Method Summary
static java.lang.String[] getDefaultAssigners()
          Gets the default assigner strings for this OS.
static java.util.EnumSet<UltraGetopt.Behavior> getDefaultBehavior()
          Gets the default behavior for this OS.
static GetoptErrorFormatter getDefaultErrorFormatter(java.lang.String programname)
          Gets the default error formatter for this OS.
static java.lang.String[] getDefaultLongLeaders()
          Gets the default long-option leader strings for this OS.
static java.lang.String[] getDefaultShortLeaders()
          Gets the default short-option leader strings for this OS.
 java.util.List<java.lang.String> getNonOptionArguments()
          Gets all non-option arguments
 java.util.Map<CommandLineOption,java.lang.String> getOptions()
          Gets all options present on the command-line and their associated arguments (null for options without values).
 java.util.Properties getOptionsAsProperties(java.util.Properties defaults)
          Gets all command-line options as a set of properties.
 java.util.Map<java.lang.String,java.lang.String> getOptionsByName()
          Gets all command-line options as a map from the long option name to the argument option.
 java.util.List<OptionArgumentPair> getOptionsOrdered()
          Gets all command-line options as a list, in the order that they appeared on the command-line.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

UltraGetopt

public UltraGetopt(java.lang.String[] args,
                   CommandLineOption[] options)
            throws UnrecognizedOptionException,
                   ExtraArgumentException,
                   MissingArgumentException,
                   AmbiguousOptionException,
                   InvalidOptionException
Creates an instance of UltraGetopt with the default set of options for the platform on which the program is running. The constructor will automatically choose the MS-DOS compatibility mode for programs running on Windows or DOS, the BSD compatibility mode for BSD, the GNU compatibility mode for Linux and Hurd, Darwin for MacOS, and POSIX for all other systems. It will attempt to guess the program invocation name, based on the name of the class at the top of the call stack. In the process of parsing the command line options, the optionEncountered method of each option will be invoked as it is processed.

Parameters:
args - The command-line arguments to process
options - The command-line options accepted
Throws:
AmbiguousOptionException - if Behavior.PARTIAL_MATCHING and/or Behavior.LONG_OPT_ADJACENT_ARG were specified and an option could not be unambiguously matched against an accepted argument
ExtraArgumentException - if an option which does not accept an argument was given one (either adjacently or by an assigner)
InvalidOptionException - if optionEncountered finds the option to be invalid
MissingArgumentException - if an option which requires an argument is encountered without an argument
UnrecognizedOptionException - if an option is encountered which is not on the list of options accepted and Behavior.NONOPTION_AS_ARGUMENT was not specified
See Also:
CommandLineOption.optionEncountered(String)

UltraGetopt

public UltraGetopt(java.lang.String programname,
                   java.lang.String[] args,
                   CommandLineOption[] options)
            throws UnrecognizedOptionException,
                   ExtraArgumentException,
                   MissingArgumentException,
                   AmbiguousOptionException,
                   InvalidOptionException
Creates an instance of UltraGetopt with the default set of options for the platform on which the program is running. The constructor will automatically choose the MS-DOS compatibility mode for programs running on Windows or DOS, the BSD compatibility mode for BSD, the GNU compatibility mode for Linux and Hurd, Darwin for MacOS, and POSIX for all other systems. In the process of parsing the command line options, the optionEncountered method of each option will be invoked as it is processed.

Parameters:
programname - the name of the program, for use in exception mesages
args - the command-line arguments to process
options - the command-line options accepted
Throws:
AmbiguousOptionException - if Behavior.PARTIAL_MATCHING and/or Behavior.LONG_OPT_ADJACENT_ARG were specified and an option could not be unambiguously matched against an accepted argument
ExtraArgumentException - if an option which does not accept an argument was given one (either adjacently or by an assigner)
InvalidOptionException - if optionEncountered finds the option to be invalid
MissingArgumentException - if an option which requires an argument is encountered without an argument
UnrecognizedOptionException - if an option is encountered which is not on the list of options accepted and Behavior.NONOPTION_AS_ARGUMENT was not specified
See Also:
CommandLineOption.optionEncountered(String)

UltraGetopt

public UltraGetopt(java.lang.String[] args,
                   CommandLineOption[] options,
                   java.util.EnumSet<UltraGetopt.Behavior> behavior)
            throws UnrecognizedOptionException,
                   ExtraArgumentException,
                   MissingArgumentException,
                   AmbiguousOptionException,
                   InvalidOptionException
Creates an instance of UltraGetopt with a chosen compatibility behavior. In the process of parsing the command line options, the optionEncountered method of each option will be invoked as it is processed.

Parameters:
args - The command-line arguments to process
options - The command-line arguments accepted
behavior - Behavior options for this instance. If behavior is null the behaviors will be set based on the conventions of the operating system it is running on.
Throws:
AmbiguousOptionException - if Behavior.PARTIAL_MATCHING and/or Behavior.LONG_OPT_ADJACENT_ARG were specified and an option could not be unambiguously matched against an accepted argument
ExtraArgumentException - if an option which does not accept an argument was given one (either adjacently or by an assigner)
InvalidOptionException - if optionEncountered finds the option to be invalid
MissingArgumentException - if an option which requires an argument is encountered without an argument
UnrecognizedOptionException - if an option is encountered which is not on the list of options accepted and Behavior.NONOPTION_AS_ARGUMENT was not specified
See Also:
CommandLineOption.optionEncountered(String)

UltraGetopt

public UltraGetopt(java.lang.String programname,
                   java.lang.String[] args,
                   CommandLineOption[] options,
                   java.util.EnumSet<UltraGetopt.Behavior> behavior)
            throws UnrecognizedOptionException,
                   ExtraArgumentException,
                   MissingArgumentException,
                   AmbiguousOptionException,
                   InvalidOptionException
Creates an instance of UltraGetopt with a chosen compatibility behavior and program name. In the process of parsing the command line options, the optionEncountered method of each option will be invoked as it is processed.

Parameters:
programname - the name of the program, for use in exception mesages
args - The command-line arguments to process
options - The command-line arguments accepted
behavior - Behavior options for this instance. If behavior is null the behaviors will be set based on the conventions of the operating system it is running on.
Throws:
AmbiguousOptionException - if Behavior.PARTIAL_MATCHING and/or Behavior.LONG_OPT_ADJACENT_ARG were specified and an option could not be unambiguously matched against an accepted argument
ExtraArgumentException - if an option which does not accept an argument was given one (either adjacently or by an assigner)
InvalidOptionException - if optionEncountered finds the option to be invalid
MissingArgumentException - if an option which requires an argument is encountered without an argument
UnrecognizedOptionException - if an option is encountered which is not on the list of options accepted and Behavior.NONOPTION_AS_ARGUMENT was not specified
See Also:
CommandLineOption.optionEncountered(String)

UltraGetopt

public UltraGetopt(java.lang.String[] args,
                   CommandLineOption[] options,
                   java.util.EnumSet<UltraGetopt.Behavior> behavior,
                   java.lang.String[] shortleaders,
                   java.lang.String[] longleaders,
                   java.lang.String[] assigners,
                   GetoptErrorFormatter formatter)
            throws UnrecognizedOptionException,
                   ExtraArgumentException,
                   MissingArgumentException,
                   AmbiguousOptionException,
                   InvalidOptionException
Creates an instance of UltraGetopt with customized behavior based on the specified arguments. In the process of parsing the command line options, the optionEncountered method of each option will be invoked as it is processed.

Parameters:
args - the command-line arguments to process
options - the command-line options accepted
behavior - the behavior options for this instance
shortleaders - the option leader strings accepted for short-options (e.g. "-" to support options of the form -h)
longleaders - the option leader strings accepted for long-options (e.g. "--" to support options of the form --help)
assigners - the option assigner strings accepted (e.g. "=" to support options of the form --help=foo)
formatter - the class to handle formatting of error messages
Throws:
AmbiguousOptionException - if Behavior.PARTIAL_MATCHING and/or Behavior.LONG_OPT_ADJACENT_ARG were specified and an option could not be unambiguously matched against an accepted argument
ExtraArgumentException - if an option which does not accept an argument was given one (either adjacently or by an assigner)
InvalidOptionException - if optionEncountered finds the option to be invalid
MissingArgumentException - if an option which requires an argument is encountered without an argument
UnrecognizedOptionException - if an option is encountered which is not on the list of options accepted and Behavior.NONOPTION_AS_ARGUMENT was not specified
See Also:
CommandLineOption.optionEncountered(String)
Method Detail

getDefaultAssigners

public static java.lang.String[] getDefaultAssigners()
Gets the default assigner strings for this OS.

Returns:
The default assigner strings for this OS

getDefaultShortLeaders

public static java.lang.String[] getDefaultShortLeaders()
Gets the default short-option leader strings for this OS.

Returns:
the default long-option leader strings for this OS

getDefaultLongLeaders

public static java.lang.String[] getDefaultLongLeaders()
Gets the default long-option leader strings for this OS.

Returns:
the default long-option leader strings for this OS

getDefaultBehavior

public static java.util.EnumSet<UltraGetopt.Behavior> getDefaultBehavior()
Gets the default behavior for this OS.

Returns:
The default behavior for this OS

getDefaultErrorFormatter

public static GetoptErrorFormatter getDefaultErrorFormatter(java.lang.String programname)
Gets the default error formatter for this OS.

Parameters:
programname - the name of this program to report in error messages
Returns:
The default error formatter for this OS

getOptions

public java.util.Map<CommandLineOption,java.lang.String> getOptions()
Gets all options present on the command-line and their associated arguments (null for options without values). Note: Use the containsKey method to determine if the option was encountered. Note: If an option appears twice on the command-line, it will only appear once in this map. Use getOptionsOrdered to get all occurrances of each option.

Returns:
Mapping from command line options to their arguments
See Also:
getOptionsAsProperties(Properties), getOptionsByName(), getOptionsOrdered(), Map.containsKey(Object)

getOptionsOrdered

public java.util.List<OptionArgumentPair> getOptionsOrdered()
                                                     throws UnrecognizedOptionException,
                                                            ExtraArgumentException,
                                                            MissingArgumentException,
                                                            AmbiguousOptionException
Gets all command-line options as a list, in the order that they appeared on the command-line.

Returns:
List of all option-argument pairs encountered
Throws:
AmbiguousOptionException - if Behavior.PARTIAL_MATCHING and/or Behavior.LONG_OPT_ADJACENT_ARG were specified and an option could not be unambiguously matched against an accepted argument
ExtraArgumentException - if an option which does not accept an argument was given one (either adjacently or by an assigner)
MissingArgumentException - if an option which requires an argument is encountered without an argument
UnrecognizedOptionException - if an option is encountered which is not on the list of options accepted and Behavior.NONOPTION_AS_ARGUMENT was not specified

getOptionsByName

public java.util.Map<java.lang.String,java.lang.String> getOptionsByName()
Gets all command-line options as a map from the long option name to the argument option. For options which do not have a long option name, they will be mapped from the short-option name to their argument.

Returns:
Mapping from the long option name to the option argument for all options encountered

getOptionsAsProperties

public java.util.Properties getOptionsAsProperties(java.util.Properties defaults)
Gets all command-line options as a set of properties. This method is similar to getOptions except that it will use the long-option name for each option (or the short-option letter for options without long variants) as the property name and assign the option argument as the property value.

Parameters:
defaults - The default set of properties, or null for none
Returns:
Set of properties mapping long option names to their arguments
See Also:
Properties

getNonOptionArguments

public java.util.List<java.lang.String> getNonOptionArguments()
Gets all non-option arguments

Returns:
list of all non-option arguments in the order in which they appeared on the command-line
Throws:
AmbiguousOptionException - if Behavior.PARTIAL_MATCHING and/or Behavior.LONG_OPT_ADJACENT_ARG were specified and an option could not be unambiguously matched against an accepted argument
ExtraArgumentException - if an option which does not accept an argument was given one (either adjacently or by an assigner)
MissingArgumentException - if an option which requires an argument is encountered without an argument
UnrecognizedOptionException - if an option is encountered which is not on the list of options accepted and Behavior.NONOPTION_AS_ARGUMENT was not specified