ABOUT
JargX is a library that provides an oject-oriented API to parse command line parameters in Java applications. So what makes JargX different from other such libraries? Simplicity and power. JargX was designed with two key goals: 1) to require minimal client code; and 2) to encapsulate the enforcement of command line usage rules. JargX will transparently take care of required arguments, default argument values, argument type constraints, and generating a usage message to print for users. In addition, it is an extensible framework that can be customized to add additional functionality.
DOWNLOAD AND INSTALLATION
JargX can be downloaded from SourceForge.net at the JargX project homepage: http://jargx.sourceforge.net. It requires the Java 2 Platform, Standard Edition (J2SE) v1.2 or later runtime environment, available at: http://java.sun.com/j2se. JargX comes packaged as a single jar file that should be placed on the classpath of the application that needs to use it.
HOW IT WORKS
The core of JargX is the ArgumentHandler interface. The client code instantiates an ArgumentHandler implementation for each application argument. JargX provides handler implementations for common argument types (Strings, boolean flags, ints, longs, floats, and doubles) and structures (String pairs and String lists). Custom ArgumentHandler implementations can easily be written to handle additional argument constructs as desired.
Next, the client code registers each ArgumentHandler with an ArgumentParser. The parser iterates through its registered handlers, passing each one the list of arguments. Each handler may consume one or more arguments from the beginning of the list, and the parser will remove those arguments and start a new iteration with the remaining list. If a problem is encountered during the process, the client code can ask the parser to print a usage message that is generated automatically from the information contained in the handlers.
Given its ease of use, JargX is best explained through an example:
public static void main(String[] args) {
// First, we need to instantiate an argument parser.
ArgumentParser parser = new ArgumentParser();
// Next, we will instantiate a handler and register it with the parser
// for each argument that may appear on the command line of this
// imaginary application:
// Let's create a boolean arg that will activate verbose mode (-v).
// The BooleanHandler's constructor requires a flag string that will
// activate the handler and a string to be used when printing the usage
// message for this arg. A boolean arg value defaults to false unless
// its flag is found.
BooleanHandler verboseArg = new BooleanHandler("-v",
"activates verbose mode");
parser.addHandler(verboseArg);
// Next, let's create a help arg (-help). A HelpHandler is a special
// type of boolean handler that does nothing unless its flag is found,
// in which case it throws a HelpRequestedException. Its constructor
// requires a flag string and a string to be used when printing the
// usage message for this arg.
HelpHandler helpArg = new HelpHandler("-help", "prints help message");
parser.addHandler(helpArg);
// Now, we'll create a host port arg (-p). We can specify that this
// arg must be an int by using an IntegerHandler. Type constrained
// handlers also exist for long, double, and float. An
// ArgumentException will be thrown by the handler if the user
// enters an arg that cannot be parsed into the specified type. The
// constructor for each of these handlers requires a flag string and a
// string to be used when printing the usage message for this arg.
// Each handler also provides a constructor with a third boolean
// parameter that can be set to true to make the arg required. The
// parser will then throw an ArgumentException if the arg is not
// specified by the user. Alternatively, each handler also provides a
// constructor with a third parameter that specifies a default value to
// use if the arg is not specified by the user. We will make the port
// arg required in this example.
IntegerHandler portArg = new IntegerHandler("-p", "host port", true);
parser.addHandler(portArg);
// Then, we'll create an output file arg of type string (-f). Since we
// don't need to do any type conversion, we'll just use a StringHandler
// which has no type constraints. Instead of making this arg required,
// we'll use the StringHandler constructor with a third string
// parameter to specify a default value of "output.txt" to use if the
// user does not specify this arg.
StringHandler outputArg = new StringHandler("-f",
"destination file for program output", "output.txt");
parser.addHandler(outputArg);
// Next, let's create a required IP address range arg (-ip). A
// PairHandler can be used to process an arg that consists of a flag
// followed by two string values. The constructor requires a flag
// string and a string to be used when printing the usage message for
// this arg. As above, other constructors are provided to make the arg
// required or to specify a default pair of values.
PairHandler ipRangeArg = new PairHandler("-ip", "ip range", true);
parser.addHandler(ipRangeArg);
// Last, a ListHandler can process an arg that is a list of one or more
// string values. The arg can either be specifed to have a flag or it
// can just parse everything on the command line that wasn't consumed
// by the other handlers. See the ListHandler API docs for more info
// on the list arg options that are available.
// Now we invoke the parser. For this application, if any unhandled
// args are encountered, an ArgumentException will be thrown. If the
// ArgumentParser had been constructed with a boolean option of true,
// then extra args would be allowed and returned as an array by the
// parse() method. For this example, the variable "args" is assumed to
// contain the String array passed to main(). Let's say the user
// entered the following string as the command line arguments to the
// application (note that the order of the arguments does not matter to
// the JargX parser):
// -p 1002 -ip 192.168.0.1 192.168.0.255 -v
try {
parser.parse(args);
} catch (ArgumentException ae) {
// There was a usage error or help was requested. Print the usage
// message and abort.
parser.printUsage();
System.exit( -1);
}
// We can now extract the command line values from each handler. At
// this point, the application can be confident that all usage rules
// were obeyed. The value that would be returned by each handler in
// this example is shown as a comment to the right of each line.
boolean verbose = verboseArg.getValue(); // true
int port = portArg.getValue().intValue(); // 1002
String output = outputArg.getValue(); // output.txt (the default)
String ipRangeStart = ipRangeArg.getValue1(); // 192.168.0.1
String ipRangeEnd = ipRangeArg.getValue2(); // 192.168.0.255
}
CREATING NEW HANDLERS
Developers can easily create additional ArgumentHandler implementations to provide specialized support for other arguments or constructs by implementing the ArgumentHandler interface. See the API docs for more information.