bpiwowar.argparser
Class ArgParser

java.lang.Object
  bpiwowar.argparser.ArgParser

public class ArgParser
extends Object

ArgParser is used to parse the command line arguments for a java application program.

Author:

B. Piwowarski

Nested Class Summary

static interface

ArgParser.TypeCheckerInterface If a handler implements this interface, it can be used to know if the handler can process a given field

Constructor Summary

ArgParser(String synopsisString, boolean defaultHelp)
Creates an ArgParser with a synopsis string.

ArgParser(String synopsisString, Object... objects)
Creates an ArgParser with a synopsis string.

Method Summary

void	activate(String groupId)
void	addOption(bpiwowar.argparser.Option option) Add an option
ArgParser	addOptions(Object object) Add options from an annotated object instance, disregarding the superclasses
void	addOptions(Object object, boolean recursive) Automatically add options for an object
void	addOptions(Object object, boolean recursive, boolean activated, String prefix, String group) Add options for an object
void	addOptions(Object object, Class<?> objectClass, boolean defaultActivated, String prefix, String defaultGroup)
static String	concatenatePrefixes(String... strings) Concatenate a list of string with "-" separator
static void	debug(org.apache.log4j.Logger logger, String format, Object... args)
PrintStream	getDefaultPrintStream() Returns the default print stream used for outputting help and error information.
String	getErrorMessage() Returns the parser's error message.
int	getHelpIndentation() Gets the indentation used by getHelpMessage.
String	getHelpMessage() Returns a string describing the allowed options in detail.
boolean	getHelpOptionsEnabled() Indicates whether or not help options are enabled.
String	getSynopsisString() Returns the synopsis string used by the parser.
void	matchAllArgs(String... args) Matches arguments within an argument list.
String[]	matchAllArgs(String[] args, EnumSet<ArgParserOption> parseFlags) Matches a command line
String[]	matchAllArgs(String[] args, int idx, ArgParserOption... exitFlags)
String[]	matchAllArgs(String[] args, int idx, EnumSet<ArgParserOption> exitFlags) Matches arguments within an argument list and returns those which were not matched.
int	matchArg(String[] args, int idx) Matches one option starting at a specified location in an argument list.
static String[]	prependArgs(File file, String[] args) Reads in a set of strings from a file and prepends them to an argument list.
static String[]	prependArgs(Reader reader, String[] args) Reads in a set of strings from a reader and prepends them to an argument list.
void	printErrorAndExit(String format, Object... args) Prints an error message, along with a pointer to help options, if available, and causes the program to exit with code 1.
void	setDefaultPrintStream(PrintStream stream) Sets the default print stream used for outputting help and error information.
protected void	setError(String msg) Sets the parser's error message.
void	setHelpIndentation(int indent) Sets the indentation used by getHelpMessage.
void	setHelpOptionsEnabled(boolean enable) Enables or disables help options.
void	setSynopsisString(String s) Sets the synopsis string used by the parser.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ArgParser

public ArgParser(String synopsisString,
                 Object... objects)

Creates an ArgParser with a synopsis string.

Parameters:

synopsisString - string that briefly describes program usage, for use by getHelpMessage.

objects - An optional list of objects to parse. It is possible to delay parsing and use addOptions(Object) to add one by one objects

ArgParser

public ArgParser(String synopsisString,
                 boolean defaultHelp)

Creates an ArgParser with a synopsis string. The help options -help and -? are added if defaultHelp is true.

Parameters:

synopsisString - string that briefly describes program usage, for use by getHelpMessage.

defaultHelp - if true, adds the default help options

See Also:

getSynopsisString(), getHelpMessage()

Method Detail

getSynopsisString

public String getSynopsisString()

Returns the synopsis string used by the parser. The synopsis string is a short description of how to invoke the program, and usually looks something like

"java somepackage.SomeClass [options] files ..." </prec>

It is used in help and error messages.

Returns:

synopsis string

See Also:

setSynopsisString(java.lang.String), getHelpMessage()

setSynopsisString

public void setSynopsisString(String s)

Sets the synopsis string used by the parser.

Parameters:

s - The new synopsis string

See Also:

getSynopsisString(), getHelpMessage()

getHelpOptionsEnabled

public boolean getHelpOptionsEnabled()

Indicates whether or not help options are enabled.

Returns:

true if help options are enabled

See Also:

setHelpOptionsEnabled(boolean), addOption(bpiwowar.argparser.Option)

setHelpOptionsEnabled

public void setHelpOptionsEnabled(boolean enable)

Enables or disables help options. Help options are those associated with a conversion code of %h. If help options are enabled, and a help option is matched, then the string produced by getHelpMessage is printed to the default print stream and the program exits with code 0. Otherwise, arguments which match help options are ignored.

Parameters:

enable - enables help options if true.

See Also:

getHelpOptionsEnabled(), addOption(bpiwowar.argparser.Option), setDefaultPrintStream(java.io.PrintStream)

getDefaultPrintStream

public PrintStream getDefaultPrintStream()

Returns the default print stream used for outputting help and error information.

Returns:

default print stream

See Also:

setDefaultPrintStream(java.io.PrintStream)

setDefaultPrintStream

public void setDefaultPrintStream(PrintStream stream)

Sets the default print stream used for outputting help and error information.

Parameters:

stream - new default print stream

See Also:

getDefaultPrintStream()

getHelpIndentation

public int getHelpIndentation()

Gets the indentation used by getHelpMessage.

Returns:

number of indentation columns

See Also:

setHelpIndentation(int), getHelpMessage()

setHelpIndentation

public void setHelpIndentation(int indent)

Sets the indentation used by getHelpMessage. This is the number of columns that an option's help information is indented. If the option's name and value information can fit within this number of columns, then all information about the option is placed on one line. Otherwise, the indented help information is placed on a separate line.

Parameters:

indent - number of indentation columns

See Also:

getHelpIndentation(), getHelpMessage()

addOptions

public void addOptions(Object object,
                       boolean recursive)
                throws InvalidHolderException

Automatically add options for an object

Parameters:

object - The object instance to analyse

recursive - If true, explores the super classes of this object, and the members annotated ArgumentClass

Throws:

InvalidHolderException - If an error occurs while reading the object annotations

addOptions

public void addOptions(Object object,
                       boolean recursive,
                       boolean activated,
                       String prefix,
                       String group)
                throws InvalidHolderException

Add options for an object

Parameters:

object - The object to analyse

recursive - Should we analyse the ancestors of this object

activated -

prefix -

group -

Throws:

InvalidHolderException

addOptions

public ArgParser addOptions(Object object)
                     throws InvalidHolderException

Add options from an annotated object instance, disregarding the superclasses

Parameters:

object - The object to explore

Throws:

InvalidHolderException - if there is an error while parsing annotations

addOption

public void addOption(bpiwowar.argparser.Option option)

Add an option

Parameters:

option - The option to add

addOptions

public void addOptions(Object object,
                       Class<?> objectClass,
                       boolean defaultActivated,
                       String prefix,
                       String defaultGroup)
                throws InvalidHolderException

Throws:

InvalidHolderException

concatenatePrefixes

public static String concatenatePrefixes(String... strings)

Concatenate a list of string with "-" separator

Parameters:

strings - An array of strings

Returns:

The concatenation (or null if empty)

prependArgs

public static String[] prependArgs(Reader reader,
                                   String[] args)
                            throws IOException

Reads in a set of strings from a reader and prepends them to an argument list. Strings are delimited by either whitespace or double quotes ". The character # acts as a comment character, causing input to the end of the current line to be ignored.

Parameters:

reader - Reader from which to read the strings

args - Initial set of argument values. Can be specified as null.

Throws:

IOException - if an error occured while reading.

prependArgs

public static String[] prependArgs(File file,
                                   String[] args)
                            throws IOException

Reads in a set of strings from a file and prepends them to an argument list. Strings are delimited by either whitespace or double quotes ". The character # acts as a comment character, causing input to the end of the current line to be ignored.

Parameters:

file - File to be read

args - Initial set of argument values. Can be specified as null.

Throws:

IOException - if an error occured while reading the file.

setError

protected void setError(String msg)

Sets the parser's error message.

Parameters:

s - Error message

printErrorAndExit

public void printErrorAndExit(String format,
                              Object... args)

Prints an error message, along with a pointer to help options, if available, and causes the program to exit with code 1.

matchAllArgs

public void matchAllArgs(String... args)
                  throws ArgParserException

Matches arguments within an argument list.

In the event of an erroneous or unmatched argument, the method prints a message and exits the program with code 1.

If help options are enabled and one of the arguments matches a help option, then the result of getHelpMessage is printed to the default print stream and the program exits with code 0. If help options are not enabled, they are ignored.

Parameters:

args - argument list

Throws:

ArgParserException

See Also:

getDefaultPrintStream()

matchAllArgs

public String[] matchAllArgs(String[] args,
                             EnumSet<ArgParserOption> parseFlags)
                      throws ArgParserException

Matches a command line

Parameters:

args -

parseFlags -

Returns:

Throws:

ArgParserException

matchAllArgs

public String[] matchAllArgs(String[] args,
                             int idx,
                             ArgParserOption... exitFlags)
                      throws ArgParserException

Throws:

ArgParserException

matchAllArgs

public String[] matchAllArgs(String[] args,
                             int idx,
                             EnumSet<ArgParserOption> exitFlags)
                      throws ArgParserException

Matches arguments within an argument list and returns those which were not matched. The matching starts at a location in args specified by idx, and unmatched arguments are returned in a String array.

In the event of an erroneous argument, the method either prints a message and exits the program (if #EXIT_ON_ERROR is set in exitFlags) or terminates the matching and creates a error message that can be retrieved by getErrorMessage().

In the event of an umatched argument, the method will print a message and exit if #EXIT_ON_UNMATCHED is set in errorFlags. Otherwise, the unmatched argument will be appended to the returned array of unmatched values, and the matching will continue at the next location.

If help options are enabled and one of the arguments matches a help option, then the result of getHelpMessage is printed to the the default print stream and the program exits with code 0. If help options are not enabled, then they will not be matched.

Parameters:

args - argument list

idx - starting location in list

exitFlags - conditions causing the program to exit. Should be an or-ed combination of #ParseFlag.EXIT_ON_ERROR, #ParseFlag.STOP_FIRST_UNMATCHED or #ParseFlag.EXIT_ON_UNMATCHED.

Returns:

array of arguments that were not matched, or null if all arguments were successfully matched

Throws:

ArgParserException

StringScanException

See Also:

ArgParserOption, getErrorMessage(), getDefaultPrintStream()

debug

public static void debug(org.apache.log4j.Logger logger,
                         String format,
                         Object... args)

matchArg

public int matchArg(String[] args,
                    int idx)
             throws ArgParserException

Matches one option starting at a specified location in an argument list. The method returns the location in the list where the next match should begin.

In the event of an erroneous argument, the method throws an ArgParseException with an appropriate error message. This error message can also be retrieved using getErrorMessage.

In the event of an umatched argument, the method will return idx

If help options are enabled and the argument matches a help option, then the result of getHelpMessage is printed to the the default print stream and the program exits with code 0. If help options are not enabled, then they are ignored.

Parameters:

args - argument list

idx - location in list where match should start

Returns:

location in list where next match should start

Throws:

ArgParserException

StringScanException

See Also:

setDefaultPrintStream(java.io.PrintStream), getHelpOptionsEnabled(), getErrorMessage(), ArgParser#getUnmatchedArgument

getHelpMessage

public String getHelpMessage()

Returns a string describing the allowed options in detail.

Returns:

help information string.

getErrorMessage

public String getErrorMessage()

Returns the parser's error message. This is automatically set whenever an error is encountered in matchArg or matchAllArgs, and is automatically set to null at the beginning of these methods.

Returns:

error message

activate

public void activate(String groupId)