name.kevinlocke.ultragetopt
Class UltraGetopt

java.lang.Object
  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