Java Command-Line Interfaces (Part 19): jClap

The focus of this nineteenth post in this series on parsing command line arguments from Java code is jClap (Java Command Line Argument Parser), which should not be confused with the library called JCLAP that was the focus of my previous post in this series. The previous post covered JCLAP 1.4 by Giles Winstanley (snaq.net) whereas this post covers jClap 2.0 by Jan So (extreme_logic).

The "definition" stage is implemented jClap by instantiating an instance of com.extremelogic.common.jclap.Argument and invoking one of the overloaded methods with names addArgument or addBooleanArgument. This is demonstrated in the next code listing (full code in available on GitHub).

"Definition" Stage with jClap

final Argument argument = new Argument(arguments);
argument.addArgument("file", "Path/name of file", true, 1);
argument.addBooleanArgument("verbose", "Enables verbosity", false);

The previous code listing demonstrates providing of long argument names, argument descriptions, whether the argument is required or not, and the number of values expected for the argument. As far as I can tell, there's no way to add a short name (single hyphen and single character) for arguments.

The "parsing" stage is achieved via jClap through invocation of the processArguments() method on the instance of Argument defined in the "definition" stage. This is a single-line call, but does throw the checked exception ArgumentException. This single-line parsing is shown in the next code listing.

"Parsing" Stage with jClap

argument.processArguments();

The "interrogration" stage is achieved with jClap via invocation of the getArgument methods on the instance of Argument that was defined in the "definition" stage. This is demonstrated in the next code listing.

"Interrogation" Stage with jClap

out.println("File path/name is '" + argument.getArgument("file") + "'.");
out.println("Verbosity is set to " + argument.getArgument("verbose"));

jClap also makes it easy to have usage written to standard output by invoking the method displayOptions on the Argument instance that was used throughout this example. This is demonstrated in the next code listing which shows catching and "handling" the checked exception ArgumentException.

"Usage" in jClap

catch (final ArgumentException argumentException)
{
   out.println(
        "ERROR: Exception encountered while processing command-line arguments - "
      + argumentException);
   argument.displayOptions();
}

Screen snapshots demonstrate the code covered in this post applying jClap to command line processing. The first image depicts the handling of the checked exception ArgumentException when the required --file argument has not been specified and also depicts the usage statement provided by jClap. The second image depicts normal command line processing of the arguments.

There are characteristics of jClap to consider when selecting a framework or library to help with command-line parsing in Java.

• jClap is open source with an Apache License Version 2.0.
• The commons-jClap-2.0.0.jar JAR is approximately 15 KB in size and has no third-party library dependencies.
• It appears to me that jClap only supports "long" argument names with double hyphens.
• The jClap JAR contains class files compiled with Java SE 6 (Major Version 50) and so should work with Java applications running on a version as old as Java SE 6.
• All arguments are retrieved from the instance of Argument as Strings (there is no typing of arguments).
• The jClap JAR also includes a "sample" application (SampleArguments.class) that IDE decompilers (such as IntelliJ IDEA's built-in decompiler and Eclipse's Enhanced Class Decompiler) can decompile to see the type of source code one can write to use jClap.

jClap is a small and easy-to-use library for processing command line arguments from Java that can be used with Java applications running on versions of Java as old as Java SE 6. The library supports long argument names only and returns arguments' values as String type in all cases.

Additional Resources

• jClap 2.0
• Extreme Logic Facebook Page