Java Command-Line Interfaces (Part 26): CmdOption

I became aware of the twenty-sixth featured Java-based library in this series on parsing command line arguments because of a Tweet. CmdOption is described on its main GitHub page as "a simple annotation-driven command line parser toolkit for Java 5+ applications that is configured through annotations." The project's subtitle is, "Command line parsing has never been easier."

The annotation @CmdOption is used to annotate fields (or methods) that will contain the parsed command-line arguments. In other words, it is with the @CmdOption annotation that the "definition" stage is accomplished with CmdOption. This is shown in the next code listing.

"Definition" Stage with CmdOption

@CmdOption(names={"--file","-f"}, description="File Path/Name", minCount=1, args={"filePathAndName"})
private String file;

@CmdOption(names={"--verbose","-v"}, description="Is verbosity enabled?", maxCount=0)
private boolean verbose;

As with other posts in this series, the examples used in this post are of options specifying file path and name and a verbosity level. The full source code listing for the example code listings in this post is available on GitHub. As the above code listing shows, the "long" (with double hyphen) and "short" (with single hyphen) option names can be specified with the @CmdOption annotation's names element. The minCount element is used to specify that a particular option must have an argument passed to it and the args element lists the string reference to the argument of an option that will be rendered in the help/usage display. The maxCount element is set to 0 for the verbosity option because no arguments should be provided for that option (presence of -v or --verbose is enough).

The "parsing" stage is accomplished in CmdOption by passing an instance of the class with @CmdOption-annotated fields (or methods) to the constructor of the CmdOption's CmdlineParser class and then passing the String[] representing the command-line arguments to the parse(String[]) method of that instantiated CmdlineParser class.

"Parsing" Stage with CmdOption

final Main instance = new Main();
final CmdlineParser parser = new CmdlineParser(instance);
parser.parse(arguments);

The "interrogation" stage in CmdOption consists simply of accessing the @CmdOption-annotated fields (or methods) on the instance of their containing class that was passed to the CmdlineParser constructor.

"Interrogation" Stage in CmdOption

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

CmdOption provides mechanisms to make generation of "help" or "usage" statements easier. If the @CmdOption annotation includes the element isHelp=true, CmdOption won't validate the command-line arguments when the option associated with isHelp=true is specified on the command line. This prevents error messages about missing required options or arguments from being displayed and then the method CmdlineParser.usage() can be invoked to have CmdOption print out usage/help information. A portion of code demonstrating this is shown next.

"Help" with CmdOption

@CmdOption(names={"--help","-h"}, description = "Display this help message", isHelp=true)
private boolean help;

// ...

if (instance.help)
{
   parser.usage(out);
}

The following three screen snapshots show the above code in action and using CmdOption. The first image depicts two error messages, one when no options are specified (-f/--file is required) and one when the "file" option is specified without an argument. The second image depicts the combinations of short and long option names. The third image shows the usage that is printed when the -h or --help option is specified.

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

• CmdOption is open source and released under the Apache License, Version 2.0.
• The de.tototec.cmdoption-0.5.0.jar is approximately 82 KB in size and requires no third-party dependencies.
• CmdOption 0.5.0 is compiled with "major version: 49", meaning that it's compatible with J2SE 5 applications. Although there are multiple libraries covered in this series that have similar annotations to CmdOption's, this ability to work with an older version of Java may be a differentiator in some cases.
• CmdOption is still being supported; the version covered in this post (0.5.0) was updated earlier this month (9 October 2017).

CmdOption is an easy-to-use library for parsing command-line options in Java. It comes with a liberal open source license and has received recent updates.

Additional References

• CmdOption (GitHub)
• CmdOption on Maven Central Repository
• CmdOption on MVNRepository
• @ToToTec and @TobiasRoeser on Twitter