Monday, October 16, 2017

Java Command-Line Interfaces (Part 24): MarkUtils-CLI

The first post in this series on parsing command line arguments in Java featured the Apache Commons CLI library. This is one of the oldest and likely one of the most commonly used of the Java-based command-line parsing libraries covered in this series. Apache Commons CLI does show its age, especially when contrasted with some of the more modern Java-based command-line processing libraries. Mark A. Ziesemer's "CLI library wrapper on Apache Commons CLI," called MarkUtils-CLI, was designed to "modernize" Apache Commons CLI and is the subject of this blog post.

In the blog post "MarkUtils-CLI: Annotations (and more) for Apache Commons CLI," Ziesemer writes:

I feel that the Apache Commons CLI project is selling themselves short. I've found it to be a very comprehensive, well-designed library for effectively parsing the command-line. The only shortcoming I've observed is that the project was developed before Java 5 - and annotations - were available. As such, the library doesn't offer support for any features that annotations have to offer.

Introducing the latest addition to MarkUtils: MarkUtils-CLI is a library that provides an effective bridge between Apache Commons CLI and Java annotations - without replacing the mature Commons CLI library.

This post uses examples similar to those used in earlier posts in this series ("file" and "verbose" command line options) to illustrate how MarkUtils-CLI wraps Apache Commons CLI and allows for definition of options via annotations and provides typed options. In this post, MarkUtils-CLI's CliRunner is used for its convenience. The full source code listing for these examples is available on GitHub.

The "definition" stage with MarkUtils-CLI is where @Parameter annotations are applied as shown in the next code listing.

"Definition" Stage with MarkUtils-CLI

@Parameter(name="f", longName="file", description="Path/name of file", required=true)
public String file;

@Parameter(name="v", longName="verbose", description="Verbosity enabled or not", argCount=0)
public boolean verbose;

This code listing shows how the "short" option name (single hyphen/single character") and "long" option name (double hyphens/word) can be specified as distinct elements of the @Parameter annotation. A "description" element can be used in the "help" created by MarkUtils-CLI and the "required" annotation element allows one to specify a required option. Specifying argCount as zero for "verbose" also indicates to the parser that no arguments are expected for the "verbose" option.

The "parsing" stage can be accomplished in MarkUtils-CLI via the CliRunner and an instance of an Apache Commons CLI CommandLineParser. This is demonstrated in the next code listing where an instance of Apache Commons CLI's DefaultParser is passed to the constructor of the CliRunner along with an instance of the class whose fields are annotated with the @Parameter annotation.

"Parsing" Stage with MarkUtils-CLI

final DefaultParser cmdLineParser = new DefaultParser();
final CliRunner<Main> cliRunner = new CliRunner(cmdLineParser, Main.class);

When using MarkUtils-CLI's CliRunner approach, the "interrogation" stage is accomplished in the call() method of the Callable that is passed to the CliRunner's "run" method. The implementation of the "call()" method is shown in the next code listing and the code that passes the owning Callable to the CliRunner's "run" method is available in the full source code listing on GitHub.

"Interrogation" Stage with MarkUtils-CLI

@Override
public Integer call() throws Exception
{
   out.println("File path/name is '" + file + "' and verbosity is " + verbose);
   return file != null ? 0 : -1;
}

The two screen snapshots that follow demonstrate the examples shown so far. The first image shows the help information generated when the required "file" option is not provided. The second image depicts the behavior of the sample code for various combinations of short name and long name options for "file" and "verbose."

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

  • MarkUtils-CLI is open source and licensed under GNU General Public License version 3.
  • MarkUtils-CLI is available as a separate JAR, but is conceptually part of the greater MarkUtils available at https://java.ziesemer.com/.
    • It seems appropriate that this approach mirrors that of Apache Commons CLI in which the CLI JAR is separate from the other JARs that are available for each library falling under the Apache Commons line.
    • This approach allows more flexibility in terms of what needs to be made available on the runtime classpath as opposed to an approach where all utilities are in a single JAR (such as with CmdLn and the Ostermiller Utilities).
  • The com.ziesemer.utils.cli-2017.05.28.jar JAR is relatively small (approximately 26 KB), but has runtime dependencies on external libraries Apache Commons CLI (expected because MarkUtils-CLI wraps this library) and SLF4J (because SLF4J is a widely used library, this dependency may not be much of an issue for many).
  • MarkUtils-CLI requires Java SE 6.
  • The author of MarkUtils-CLI notified me of the existence of this library and appears to be actively involved in supporting it, something that cannot be said for all the libraries covered in this series. He has stated that he is "committed to responding to and fixing anything that would come across" the MarkUtils-CLI GitHub Issues Tracker. He also pointed out that there are 95 executing unit tests verifying MarkUtils-CLI functionality.

MarkUtils-CLI is a small wrapper for Apache Commons CLI that modernizes the Apache Commons CLI experience through use of annotations and handling of command line options' types. MarkUtils-CLI will most likely appeal to those who are already using Apache Commons CLI and want to enjoy the benefits of easier options definition with annotations and more type safe option parsing. Advantages of this library include current support and thorough unit testing of the library. Issues that may deter some from using this library are its GPL license and its external dependency on SLF4J (assuming the Apache Commons CLI dependency is not an issue as this is advertised as a wrapper for Apache Commons CLI).

Additional References

Saturday, October 14, 2017

Java Command-Line Interfaces (Part 23): Rop

The Rop library is described on its main page as "a lightweight command line option parser written in Java." The "Introduction" to Rop also states, "Rop is designed to be minimal meanwhile convenient, and to cover most usual command line parsing use cases." This post is the twenty-third in this series on parsing command line arguments in Java and focuses on Rop.

Like the twenty-two posts in this series before this one, this post uses examples implementing two command line options, one for file path and name and one for verbosity level. The full code listing the example is available on GitHub.

The "definition" stage is accomplished in Rop via annotations @Command and @Option (both of which are nested within class com.github.ryenus.rop.OptionParser). This is shown in the next code listing.

"Definition" Stage with Rop

/**
 * Demonstrates use of Rop for processing command line
 * parameters in Java.
 */
@Command(name="RopDemo", descriptions="Demonstrates ROP for command line processing.")
public class Main
{
   @Option(opt={"-f", "--file"}, description="Path and name of file.")
   private String file;

   @Option(opt={"-v", "--verbose"}, description="Indicates whether verbosity is enabled or not.")
   private boolean verbose;

The "parsing" stage is accomplished in Rop by instantiating an instance of OptionParser and pass to it the definition of the class whose fields were annotated in the "definition" stage. This is shown in the next code listing.

"Parsing" Stage with Rop

final OptionParser parser = new OptionParser(Main.class);
parser.parse(arguments);

The OptionParser.parse(Class) method implicitly invokes (via reflection) a method with name "run" on the instance provided to the parser when it was constructed. I have implemented this "run" method as shown in the next code listing.

"Interrogation" Stage with Rop (including "run" method)

/**
 * Method called implicitly by Rop parser.
 *
 * @param parser Instance of {@code OptionParser} whose
 *    "parse" method led to my implicit invocation.
 */
private void run(final OptionParser parser)
{
   out.println("File path/name is " + file + " and verbosity is " + verbose);
}

The above code listing's "run" method demonstrates "interrogation" that is accomplished by accessing the @Option-annotated fields that were populated by the OptionParser.parse(String[]) call.

The three screen snapshots that follow demonstrate these "definition", "parsing", and "interrogation" stages accomplished with Rop. The first image indicates the error message that is shown when the required "file" option is not specified. The second image depicts normal behavior of the example that processes combinations of the "file" and "verbose" options' short and long names. The third image depicts Rop's built-in "help" support that is shown when the --help option is specified.

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

  • Rop is open source with an MIT License.
  • Rop, as advertised, is lightweight; the rop-1.1.1.jar is approximately 18 KB in size and requires no third-party dependencies.
  • The classes in the rop-1.1.1.jar have "major version: 51", meaning that Java SE 7 is required if using these compiled classes.

Rop is a lightweight Java-based library for processing command line options that is easy to learn and use.

Additional References

Thursday, October 12, 2017

Java Command-Line Interfaces (Part 22): argparser

John Lloyd's argparser is the library covered in this twenty-second post of the series on Java-based command line argument parsing. The main page for the library provides links to Javadoc-based API documentation, a JAR file, a ZIP file, and a TAR file in addition to a single source code example. The example used in this post is similar to the examples used in the first twenty-one posts in this series and processes file path/name and verbosity options. The full code listing is available on GitHub.

The "definition" stage is accomplished in argparser with instances of "Holder" classes representing the expected options that are passed to the addOption(String,Object) method of an ArgParser instance. This is demonstrated in the next code listing.

"Definition" Stage with argparser

final StringHolder file = new StringHolder();
final BooleanHolder verbose = new BooleanHolder();

final ArgParser parser = new ArgParser("java examples.dustin.commandline.argparser.Main");
parser.addOption ("-f,--file %s #Path and name of file", file);
parser.addOption ("-v,--verbose %v #Verbosity enabled?", verbose);

Many of the libraries covered in this series on parsing command line arguments from Java have option characteristics explicitly spelled out with individual parameters, individual methods, or individual annotation elements. As shown in the code listing, argparser instead has the option's attributes spelled out in a "specification" string that argparser parses.

The "parsing" stage is accomplished in argparser by passing the String[] with command-line arguments to the matchAllArgs(String[]) method of the ArgParser class. This single statement is shown in the next code listing.

"Parsing" Stage with argparser

parser.matchAllArgs(arguments);

The "interrogation" stage is accomplished in argparser by accessing the public field called "value" in the respective "Holder" classes. This is shown in the next code listing.

"Interrogation" Stage with argparser

out.println("File path/name is: " + file.value);
out.println("Verbosity is: " + verbose.value);

The argparser library also provides support for a "help"/"usage" message. This is demonstrated in the next code listing in which usage is written if the "file" option is not specified (if its "value" is null).

"Usage" with argparser

if (file.value == null)
{
   out.println("ERROR: File path/name was not specified! Use -f or --file to specify file path/name.\n"
      + parser.getHelpMessage());
}

The screen snapshots shown next demonstrate the examples covered in this post. The first image shows the "usage" provided by argparser when the required "file" option is not specified. The second image shows use of the long and short option names.

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

  • Arparser is open source. It's not clear to me if it is licensed under any specific license, but there is a COPYRIGHT file included with the JAR that states, "Copyright John E. Lloyd, 2004. All rights reserved. Permission to use, copy, modify and redistribute is granted, provided that this copyright notice is retained and the author is given credit whenever appropriate." There is also a standard disclaimer about the software being distributed "as-is."
  • The argparser.jar is approximately 129 KB in size, but includes .java source code files, .class compiled files, and Javadoc HTML files.
  • The Javadoc for the argparser.ArgParser class is excellent and an example of what I'd love to see routinely in Javadoc for "main" classes of Java-based libraries. This is a good example of how a small open source project can document the project/library once because the class's Javadoc is also used and link to from the project's main page. That class-level Javadoc even includes the SimpleExample source code (which is also in the distributed JAR file) for an example of how to use the class and library.
  • Because argparser is compiled with "major version: 46", it should run with a version of Java as old as JDK 1.2!

The argparser library is small and simple to use. It will probably appeal most to those wanting a small library to accomplish basic command line processing and will especially appeal to anyone who still might happen to be running their Java-based command-line processing code in older versions of JDK. A couple of things that make this library different than many of the others covered in this series are its excellent Javadoc-based API documentation and its string specification approach for option characteristics.

Additional References

Monday, October 9, 2017

Java Command-Line Interfaces (Part 21): Airline 2

The focus of this twenty-first post in this series on parsing command-line arguments in Java is on the Airline 2 library. The GitHub project page for Airline 2 describes the library, "Airline is a Java library providing an annotation-based framework for parsing command line interfaces." The page goes onto state that Airline "supports both simple single commands through to complex git style interfaces with groups." The page also defines Airline 2's relationship with the original Airline library: "This is a substantially rewritten fork of the original airline library." It is specifically Airline 2.3.0 that is featured in this post.

The examples in this post will be similar to those demonstrated in earlier posts in this series on alternative libraries for parsing command line arguments from Java. As such, the options supported in these examples will be specification of a file's path and name and specification of whether or not verbosity should be enabled. The full code listing for the examples shown here is available on GitHub.

The "definition" stage of parsing command-line arguments from Java with Airline 2 is easily accomplished using @Option annotations as shown in the next code listing.

"Definition" Stage with Airline 2

@Option(title="file", name={"-f", "--file"}, description="Path and name of file.")
private String file;

@Option(title="verbose", name={"-v", "--verbose"}, description="Enable or disable verbosity.")
private boolean verbose;

The code for these instances of @Option annotations is fairly self-explanatory. The "name" element of the @Option annotation expects one or more Strings and thus allows multiple flags to be specified for the same option. In this case, I used the same single-hyphen/single-character "short" form and double hyphen/word "long" forms for the options.

The "parsing" stage can be accomplished with Airline 2 using the SingleCommand class and its static singleCommand(Class<C>) method to acquire an instance of SingleCommand and then invoking the parse(String[]) method on that instance. These two statements are demonstrated in the next code listing.

"Parsing" Stage with Airline 2

final SingleCommand<Main> parser = SingleCommand.singleCommand(Main.class);
final Main main = parser.parse(arguments);

The "interrogation" stage in Airline 2 is accomplished by simply accessing the @Option-annotated fields of the instance provided by the SingleCommand.parse(String[]) method. This is demonstrated in the next code listing.

"Interrogation" Stage with Airline 2

if (main.file != null)
{
   out.println("File path/name is '" + main.file + "'.");
   out.println("Verbosity is " + main.verbose);
}
else
{
   out.println("ERROR: File path/name must be provided with -f or --file.");
}

The next two screen snapshots show the examples in action. The first screen snapshot shows the output when no arguments are provided and the second image shows "normal" use of the long and short versions of the two options for specifying file path/name and verbosity.

Airline comes with support for generating usage and help information. Unfortunately, I was not able to get it to work for me because I ran into a compilation error that stated, "class file for com.github.rvesse.airline.io.printers.UsagePrinter not found." I don't see that class in the airline-2.3.0.jar I downloaded.

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

  • Airline 2 is open source and licensed under the Apache License, Version 2.0.
  • Airline 2 is one of the "weightier" libraries covered in this series with the airline-2.3.0.jar being approximately 316 KB in size and having runtime dependencies on Apache Commons Collections, Apache Commons Lang, and javax.inject/javax.inject.
  • Although Airline has been around for a while, Airline 2 is a more recently updated fork of that project.
  • The documentation for basic use of Airline 2 is straightforward and useful, but documentation for many of the features not shown in this post is still under construction with numerous "TODO" statements.

Airline 2 is easy to use for the "single command" style of arguments processing implemented in my examples in these posts. I did not see any method for expressing whether an option is required, but simply checking for null for a required option before proceeding is an easy approach for this. Given its size and dependencies, Airline 2 is probably best suited for those looking to use many of its powerful features not demonstrated in this post. For the simple examples demonstrated in this post and in the other posts in this series, there are lighter libraries with fewer dependencies that work very similarly to Airline 2 in terms of expressing "definition", "parsing", and "interrogation" stages.

Additional References

Wednesday, October 4, 2017

Java Command-Line Interfaces (Part 20): JSAP

JSAP (Java Simple Argument Parser) 2.1 is the focus of this twentieth post in this series on processing command line arguments from Java. The JSAP page describes the library's reason for existence: "I found several parsers on the Internet, all of which handled switches, but none of which had the versatility I wanted in terms of return types and configuration files."

JSAP offers quite a bit of flexibility at the normal cost of some complexity. Fortunately, JSAP provides a class called SimpleJSAP that makes it easier to accomplish simple tasks with JSAP. The JSAP documentation articulates it this way, "If you want to minimize the amount of code handling the command line, JSAP offers a SimpleJSAP that does most of the work for you." The next code listing demonstrates using SimpleJSAP in a single (albeit verbose) statement to define the expected command line options.

"Definition" Stage with JSAP

final SimpleJSAP jsap = new SimpleJSAP(
   "Main Application",
   "Demonstrate JSAP",
   new Parameter[]
      {new FlaggedOption("file", STRING_PARSER, NO_DEFAULT, REQUIRED, 'f', "file", "File path/name."),
       new Switch("verbose", 'v', "verbose", "Requests verbose output." )});

For the above code listing, I used static imports to reduce the verbosity of this "definition" code. These can be seen in the full code listing available on GitHub. The code above defines the two options being used in all of the posts in their series on libraries used to parse command line arguments in Java: file path/name and verbosity. The single characters 'f' and 'v' are the short option names and the long option names follow them in their respective calls (file and verbose). Note that the "definition" of command line arguments can be configured via XML as well, though that is not demonstrated here.

The "parsing" stage is accomplished in JSAP with another single statement in which an invocation of the parse(String[]) method on the instance of SimpleJSAP returns an instance of JSAPResult.

"Parsing" Stage with JSAP

final JSAPResult parsedResult = jsap.parse(arguments);

JSAP's "interrogation" stage is accomplished with calls on the instance of JSAPResult returned by the parse method as demonstrated in the next code listing.

"Interrogation" Stage with JSAP

out.println("File path/name is '" + parsedResult.getString("file") + "'.");
out.println("Verbosity level is " + parsedResult.getBoolean("verbose"));

JSAP will generate automatic usage and help statements. The next code listing demonstrates use of the SimpleJSAP.messagePrinted() method to determine if some time of parsing error occurred and then using the SimpleJSAP.getHelp() message to access the automatically generated "help" message.

"Help" with JSAP

if (jsap.messagePrinted())
{
   out.println(jsap.getHelp());
   System.exit( -1 );
}

The next two screen snapshots demonstrate execution of the code examples shown in this post using JSAP. The first image depicts the usage statement printed when the required -f/--file flag is not provided. The second image depicts normal behavior of the example code based on JSAP.

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

JSAP seems to be one of the more popular of the older Java-based command-line parsing libraries. It's relatively easy to use for basic functionality like that demonstrated in this post, but also offers additional flexibility and customizability for more complex needs.

Additional Resources

Tuesday, October 3, 2017

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

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