com.codetaco.argument.annotation

Annotation Type Arg

@Retention(value=RUNTIME)
 @Target(value=FIELD)
 @Repeatable(value=Args.class)
public @interface Arg

"argument" is a full featured command line argument processor for Java. Essentially, it allows your program to get run-time direction from the user as they execute it on the command line. (Example: yourProgram --tail) This assumes that you have written a program called yourProgram and that it will need to do something special if the user also enters the --tail argument. "argument" is a library that makes handling this type of command line interaction very easy to implement. All parsers are equipped with a few basic arguments; --help, -?, -!, and @(filename).

In the main method in your program, or somewhere similar,

 public static void main (final String[] args) {
     MyProgram instance = new MyProgram();
 

and process the command line arguments into the instance variables of your program.

 CmdLine.load(instance, args);
 

Decorate your instance variables with this @Arg annotation to tell the parser what to do. Maybe something like this (to follow on the --tail example) in the MyProgram class.

 @Arg
 private boolean tail;
 

You can decorate instance variables of many types (including all primitives) and also those of any POJO as long as the POJO is decorated with the @Arg annotation. Arrays and java.util.List of these same types are also valid. For instance, you may want to allow the user of your program to specify multiple files for processing

 @Arg
 private File[] inputFiles;
 

Then the user could enter this on the command line and the inputFiles instance variable would contain the File objects.

 >myProgram --inputFiles oneFile.txt anotherFile.txt
 

Author:

Chris DeGreef fedupforone@gmail.com

See Also:

Boolean, Byte, Character, String, Integer, Long, Float, Double, File, Date, Calendar, Pattern, WildFiles, Equ

Field Summary

Fields

Modifier and Type	Fields and Description
static String	SELF_REFERENCING_ARGNAME

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	allowCamelCaps Indicates that the user can specify the argument on the command-line using the Camel Caps version of the long name.
boolean	allowMetaphone Indicates that the user can specify the argument on the command-line with misspellings as long as it evaluates to the Metaphone equivalent of the long name.
boolean	caseSensitive Indicates that all values associated with this argument are case sensitive.
String[]	defaultValues Indicates the default value(s) for this argument.
String[]	excludeArgs Indicates the arguments from a pojo that should be excluded from the parser.
String	factoryArgName Indicates the argument from an embedded parser that is to be used as a String parameter to the factory method.
String	factoryMethod Indicates the factory method to be used when creating an instance of this embedded parser.
String	format Indicates the date format for types of Date.
String	help Indicates the message that will be included in the usage for this argument.
String	inEnum Indicates an enum, implying a list of values that will be allowed for this argument.
String[]	inList Indicates a list of values that will be allowed for this argument.
String	instanceClass Indicates the class that will be used to create an object for this argument.
String	longName Indicates the single word, long name of this argument.
String	matches Indicates a verification pattern to be run against the user input before it will be accepted.
int	multimax Indicates the maximum allowed number of values that will be accepted for this argument.
int	multimin Indicates the minimum allowed number of values that will be accepted for this argument.
boolean	positional Indicates that a name is not allowed for this argument.
String[]	range Indicates a criteria to be applied to the user's input.
boolean	required Indicates that this argument is required - the user must provide the argument.
char	shortName Indicates the single character, short name of this argument.
int	uniqueId Indicates a non-used integer value that will be kept with the argument in internal memory.
String	variable Indicates that a variable in the complex class of the previous @Arg annotation (without the variable parameter) is to be annotated.

Field Detail

SELF_REFERENCING_ARGNAME

public static final String SELF_REFERENCING_ARGNAME

Element Detail

allowCamelCaps

public abstract boolean allowCamelCaps

Indicates that the user can specify the argument on the command-line using the Camel Caps version of the long name.

Default:

false

allowMetaphone

public abstract boolean allowMetaphone

Indicates that the user can specify the argument on the command-line with misspellings as long as it evaluates to the Metaphone equivalent of the long name.

Default:

false

caseSensitive

public abstract boolean caseSensitive

Indicates that all values associated with this argument are case sensitive. The default for this is false meaning that all alpha characters are converted to lowercase. If upper case is needed then make this true.

Default:

false

defaultValues

public abstract String[] defaultValues

Indicates the default value(s) for this argument. All entries are of the String type and will be internally converted to the proper type when needed.

Default:

{}

excludeArgs

public abstract String[] excludeArgs

Indicates the arguments from a pojo that should be excluded from the parser.

Default:

{}

factoryArgName

public abstract String factoryArgName

Indicates the argument from an embedded parser that is to be used as a String parameter to the factory method. If this is not specified then the factory method will be called without an argument. Use the argument variable name (like "type") for this value.

Default:

""

factoryMethod

public abstract String factoryMethod

Indicates the factory method to be used when creating an instance of this embedded parser. It should be specified as package.class.method. If an inner class is involved then use package.class$innerClass.method

Default:

""

format

public abstract String format

Indicates the date format for types of Date. User entry for this argument will be parsed with this date. Use the SimpleDateFormat parameters.

Default:

""

help

public abstract String help

Indicates the message that will be included in the usage for this argument.

Default:

""

inEnum

public abstract String inEnum

Indicates an enum, implying a list of values that will be allowed for this argument. They will be internally converted to a list of Strings for a criteria.

Default:

""

inList

public abstract String[] inList

Indicates a list of values that will be allowed for this argument. They are to be entered as an array of Strings that will be internally converted to the proper type when needed.

Default:

{}

instanceClass

public abstract String instanceClass

Indicates the class that will be used to create an object for this argument. This is needed when an abstract class, maybe even Object is used as the variable type. This parameter allows the specification of the actual instance class that should be used to create the instance. An example:

 @Arg(instanceClass = "com.codetaco.argument.VariableTest$MyGroup")
 private Object testObjectGroup;
 

Default:

""

longName

public abstract String longName

Indicates the single word, long name of this argument. The command-line use of this is a double dash (--) followed immediately by this word, or more precisely, the unique beginning of this word relative to all other arguments at this level of the parser.

The default for the long name is the actual name of the variable. In the example below it would not be necessary to specify the long name for the confirm variable since that is the default.

If you prefer not to have a long name at all then set this value to be an empty string.

Examples:

 @Arg(longName = 'confirm')
 private boolean confirm;

 @Arg(longName = 'file')
 private File inputFile;
 

With the user then running the program as...

 >myProgram --file aFile.txt --confirm
 

Default:

""

matches

public abstract String matches

Indicates a verification pattern to be run against the user input before it will be accepted. It must match the entire input. Use Pattern to write the value for this parameter. This pattern will be applied to the toString() result on the user input. This typically only makes sense on a type of String.

Default:

""

multimax

public abstract int multimax

Indicates the maximum allowed number of values that will be accepted for this argument. Useful when the type of the variable is an array or a List. The default for the parameter is the max integer.

Default:

0

multimin

public abstract int multimin

Indicates the minimum allowed number of values that will be accepted for this argument. Useful when the type of the variable is an array or a List. The default for the parameter is 0.

Default:

0

positional

public abstract boolean positional

Indicates that a name is not allowed for this argument. The user input is for this parameter is determined based on the order of the input. A way to think about this is that all of the named arguments are extracted from the user's input, and what is left is then assigned to the positional parameters. A common use for this is file name input to your program.

Default:

false

range

public abstract String[] range

Indicates a criteria to be applied to the user's input. This is an array of two values; the first one being the minimum and the second the maximum, they are inclusive. The second value is optional meaning that there is no maximum associated. A typical use might to allow only positive values for an integer; range = {"1"}.

Default:

{}

required

public abstract boolean required

Indicates that this argument is required - the user must provide the argument. A not-so-obvious use for this is the create a boolean called confirm and apply the annotation @Arg(required=true}. This will automatically require the user to enter --confirm or the parser will throw an exception.

Default:

false

shortName

public abstract char shortName

Indicates the single character, short name of this argument. The command-line use of this is a single dash (-) followed immediately by this character. This needs to be unique for all arguments at the same level of the parser.

For a boolean type of argument there would be no supplied value after the -c. For any other type of instance variable the value would follow.

Examples:

 @Arg(shortName = 'c')
 private boolean confirm;

 @Arg(shortName = 'f')
 private File inputFile;
 

With the user then running the program as...

 >myProgram -f aFile.txt -c
 

Default:

32

uniqueId

public abstract int uniqueId

Indicates a non-used integer value that will be kept with the argument in internal memory. There is currently no use for this value except the GUI.

Default:

0

variable

public abstract String variable

Indicates that a variable in the complex class of the previous @Arg annotation (without the variable parameter) is to be annotated. This is needed when the embedded complex class source is not to be directly modified by annotations.

Default:

""