Tuesday, October 24, 2017

Java Command-Line Interfaces (Part 27): cli-parser

CLI Parser, originally hosted on and now archived on Google Code, is now available on GitHub. The archive Google Code project page describes CLI Parser as a "very simple to use, very small dependency" that uses annotations to "make very succinct main methods that don't need to know how to parse command line arguments with either fields, properties, or method based injection." The current GitHub project page describes CLI Parser as "a tiny ..., super easy to use library for parsing various kinds of command line arguments or property lists."

CLI Parser expects the "definition" stage to be implemented via the @Argument annotation. This is demonstrated in the next code listing, which provides a simple example defining "file" and "verbose" options as has been done in previous posts in this series. The complete code listing is available on GitHub.

"Definition" Stage with CLI Parser

@Argument(alias="f", description="Path/name of the file", required=true)
private String file;

@Argument(alias="v", description="Verbosity enabled?")
private boolean verbose;

The code shown above defines two options. Each option can be specified with a name matching the field name (file or verbose) or with the specified alias (f or v). With CLI Parser, either case (full field name or alias) is expressed on the command-line with a single hyphen. As shown in the code example, an option can be specified as "required" and description text can be provided to be used in help/usage statements.

The "parsing" stage is accomplished in CLI Parser via static functions on its Args class. In this case, I'm using the Args.parseOrExit(Class, String[]) function as shown in the next code listing.

"Parsing" Stage with CLI Parser

final List<String> unparsed = Args.parseOrExit(instance, arguments);

The "interrogation" stage is accomplished by accessing the fields annotated with @Argument as demonstrated in the next code listing.

"Interrogation" Stage with CLI Parser

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

The "definition" code defined the "file" option as "required." If this option is not specified on the command line, CLI Parser automatically prints out a usage statement using the "description" values provided in the respective @Argument annotations. This is shown in the next screen snapshot, which is followed by another screen snapshot indicating combinations of the -file/-f and -verbose/-v options.

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

  • CLI Parser is open source and available under the Apache License, Version 2.
  • CLI Parser is a small, lightweight library with the cli-parser-1.1.2.jar being approximately 15 KB and having no third-party dependencies.

CLI Parser is, as advertised, a "tiny" and "super easy to use library for parsing various kinds of command line arguments." It's liberal open source Apache license makes it easy for most organizations to acquire and use it.

Additional References

No comments: