Java Command-Line Interfaces (Part 28): getopt4j

The page for getopt4j describes this as "a library to parse command line arguments according to the GNU style." The page then introduces getopt4j: "The 'getopt4j' library is designed to parse the command line options in the same manner as the C getopt() function in glibc (the GNU C runtime library). It attempts to do this in a simpler, more Java-centric manner than the original product." This post describes use of getopt4j to parse command line options in the same manner as was done for the libraries covered in the earlier 27 posts in this series.

The "definition" stage is accomplished in getopt4j via instances of CLOptionDescriptor as demonstrated in the next code listing (full source code is available on GitHub).

"Definition" Stage with getopt4j

final CLOptionDescriptor fileDescriptor
   = new CLOptionDescriptor("file",
      CLOptionDescriptor.ARGUMENT_REQUIRED,
      'f',
      "Path and name of file.");
final CLOptionDescriptor verboseDescriptor
   = new CLOptionDescriptor("verbose",
      CLOptionDescriptor.ARGUMENT_DISALLOWED,
      'v',
      "Is verbosity enabled?");
final CLOptionDescriptor[] optionsDefinitions
   = new CLOptionDescriptor[]{fileDescriptor, verboseDescriptor};

As shown in the above code, the instances of CLOptionDescriptor are placed in an array to be presented to the getopt4j parser.

The "parsing" stage is achieved in getopt4j via instantiation of the CLArgsParser class. The constructor of that class accepts the command line arguments in the String[] array and the array of CLOptionDescriptor instances representing the options' definitions. This is shown in the next code listing.

"Parsing" Stage with getopt4j

final CLArgsParser parser = new CLArgsParser(arguments, optionsDefinitions);

The "interrogation" stage in getopt4j is accomplished by retrieving a List<CLOption> via invocation of the method getArguments() on the CLArgsParser instance. Each instance of CLOption can be queried by its getId() method to acquire the parsed parameter by its "short" name ('f' or 'v' in this example). Once the appropriate instance of CLOption has been found via its getId() method, that same instance of CLOption will provide the value associated on the command line with that option via a call to the CLOption's method getArgument() method. This "interrogation" process is demonstrated in the next code listing.

"Interrogation" Stage with getopt4j

String filePathAndName = null;
boolean verbose = false;
final List<CLOption> options = parser.getArguments();
for (final CLOption option : options)
{
   switch(option.getId())
   {
      case 'f' :
         filePathAndName = option.getArgument();
         break;
      case 'v' :
         verbose = true;
         break;
   }
}

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

The getopt4j library makes it easy to request usage/help information by passing the array of CLOptionDescriptor instances to the static method CLUtil.describeOptions(CLOptionDescriptor[]). This is demonstrated in the next code listing, a couple of lines of code called when it is detected that the file path/name has not been provided.

"Usage" Statement with getopt4j

if (filePathAndName == null)
{
   out.println("ERROR: The file path/name option is required but was not provided.\n\n"
      + CLUtil.describeOptions(optionsDefinitions));
}

The first of the next two screen snapshots depicts the automatically generated "usage" statement that the code is able to invoke when the required "file option is not specified. The second image depicts various combinations of the "file" and "verbose" long and short option names being used.

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

• getopt4j is open source and released under the Apache License, Version 2.0.
• The getopt4j-1.2.jar JAR file is approximately 16 KB in size.
• The classes in the getopt4j-1.2.jar (June 2016) available on MVN Repository (and Maven Central Repository) are compiled against Java SE 6 ("major version: 50").
• The best examples of how to use getopt4j are provided in the examples directory in the distribution.

The getopt4j library provides GNU C getopt()-like functionality and APIs with Java style.

Additional References

• getopt4j (GitHub)
• getopt4j 1.2 (Maven / MVN Repository)
• getopt4j Examples
• Examples of GNU C getopt()