Monday, October 2, 2017

Java Command-Line Interfaces (Part 18): JCLAP

Giles Winstanley's JCLAP (Java Command-Line Argument Parser) is the eighteenth library covered in this series of posts on Java-based command line processing libraries. This post's examples are based on JCLAP 1.4, which requires Java 8. The main JCLAP page states, "JCLAP helps Java developers to create simple-to-use command-line interfaces for their applications."

The "definition" stage is accomplished with JCLAP via invocation of "addXXXXXOption" methods on the CLAParser object. This post's example, as was the case for examples in the earlier posts in this series, defines two command line options, one for file path and name and one for enabling verbosity. The next code listing demonstrates how to use JCLAP to define these two command line options (full code listing is available on GitHub).

"Definition" Stage with JCLAP

final CLAParser parser = new CLAParser();
final Option<String> fileNameOption
   = parser.addStringOption("f", "file", "Path/name of the file.", 1, 1);
final Option<Boolean> verbosityOption
   = parser.addBooleanOption("v", "verbose", "Verbosity enabled?");

The code listing just shown demonstrates that JCLAP supports long and short argument names, the ability to provide a description, and the ability to designate the minimum and maximum number of occurrences of each argument.

The "parsing" stage is implemented via JCLAP with a single invocation of the method CLAParser.parse(String[]), though that method does throw the checked exception OptionException.

"Parsing" Stage with JCLAP

parser.parse(arguments);

The "interrogation" stage is implemented in JCLAP in different ways, but the approach I use here is to use one of the overloaded CLAParser.getOptionValue() methods.

"Interrogation" Stage with JCLAP

out.println("File path/name is " + parser.getOptionValue(fileNameOption));
out.println("Verbosity is " + (parser.getOptionValue(verbosityOption) != null));

JCLAP also supports automatic usage statement creation. The next code listing demonstrates invoking one of the overloaded CLAParser.printUsage() methods in the block associated with catching the checked OptionException.

Automatic Usage Statement with JCLAP

catch (OptionException optionException)
{
   out.println("Exception: " + optionException);
   parser.printUsage(out, true);
}

The two screen snapshots that follow depict the code examples in action. The first screen snapshot shows the JCLAP-generated usage statement when no arguments are provided. The second image shows the "happy path" applying the long and short flag names for the two arguments.

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

  • JCLAP is open source with a "BSD-style licence" described on the project page.
  • The jclap-1.4.jar JAR file is approximately 46 KB in size and has no third-party library dependencies.
  • Different versions of JCLAP are designed for different versions of Java.
  • JCLAP's author has offered potential support and bug fixes as requested by e-mail.
  • JCLAP provides some support for internationalization and localization.

JCLAP (Java Command-Line Argument Parser) is a small library with commercial-friendly license that has been updated in recent years to use Java 8 features. JCLAP's author has written on the project's main page that "JCLAP is by no means unique, and many similar utilities are available both for free and commercially." The author further explains that "So many similar solutions now exist that it seems redundant to have yet another, but having already created JCLAP it seems beneficial to make it publicly available."

Additional References

No comments: