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
COPYRIGHTfile 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
.javasource code files,.classcompiled 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
SimpleExamplesource 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
| Published on Java Code Geeks with permission by Dustin Marx, partner at our JCG program. See the original article here: Java Command-Line Interfaces (Part 22): argparser Opinions expressed by Java Code Geeks contributors are their own. |
