Use Commons CLI to parse program arguments. Populate an Options
object to configure command-line
parsing. Pass the Options
class and a
String[]
of arguments to a CommandLineParser
, which parses and returns a
CommandLine
object capturing the
supplied options and parameters.
For the purposes of this recipe, assume that you are attempting to
parse a command line with three optional arguments: -h
,
-v
, and -f
<filename>
. -h
prints
out a simple help message with usage information and available
command-line options, -v
runs the
program with verbose logging, and -f
sends the output of the application to a file. To parse this command
line, your main( )
method would
resemble the following code:
import org.apache.commons.cli.CommandLineParser; import org.apache.commons.cli.BasicParser; import org.apache.commons.cli.Options; import org.apache.commons.cli.CommandLine; public static void main(String[] args) throws Exception { // Create a Parser CommandLineParser parser = new BasicParser( ); Options options = new Options( ); options.addOption("h", "help", false, "Print this usage information"); options.addOption("v", "verbose", false, "Print out VERBOSE information" ); options.addOption("f", "file", true, "File to save program output to"); // Parse the program arguments CommandLine commandLine = parser.parse( options, args ); // Set the appropriate variables based on supplied options boolean verbose = false; String file = ""; if( commandLine.hasOption('h') ) { System.out.println( "Help Message") System.exit(0); } if( commandLine.hasOption('v') ) { verbose = true; } if( commandLine.hasOption('f') ) { file = commandLine.getOptionValue('f'); } }
The Options
object tells the
CommandLineParser
to expect three arguments: -h
, -v
, and
-f
. The first argument to options.addOption( )
is the short name or
abbreviation of the option, and the second argument is the long name of
the argument. When the long name of an option is specified, either may
be used as program arguments. For example, a command line specifying
short-name arguments, -h
-v
-f
test.xml
, is equivalent to a command
line specifying long-name arguments, --help
--version
--file
test.xml
, and both short- and long-name
arguments may be mixed in the same command line. The third argument to
options.addOption()
specifies whether the option takes a parameter; in the
previous example, only the file option expects a parameter. The fourth
parameter is a String
containing a
description of the option for a user.
An Options
object may be
configured using the options.addOption(
)
, or an Option
object can
be created and added to the Options
object. The following code is equivalent to the call to options.addOption( )
in the previous example,
which adds the help option:
Option helpOption = new Option("h", "Prints this usage information"); helpOption.setLongOpt( "help" ); options.addOption( helpOption );
Both the Options
object and the
args String[]
are passed to parser.parse( )
, which returns a CommandLine
object. CommandLine
captures the supplied program
arguments, and provides access to the supplied options and arguments.
commandLine.hasOption('h')
checks for
the presence of the optional help choice, and commandLine.getOptionValue('f')
retrieves the
filename argument for the file option.
In this recipe, BasicParser
, an implementation of CommandLineParser
, is used to parse command
lines. This implementation allows for mixed short- and long-name
options: -f
test.xml
--help
. If you are developing an application
that needs to parse arguments using POSIX Conventions, use org.apache.commons.cli.PosixParser
instead of
BasicParser
. If you need to parse
arguments using the less strict GNU conventions, use the org.apache.commons.cli.GNUParser
.
For background about the differences between POSIX and GNU standards, see Section 4.6 of the "GNU Coding Standards" (http://www.gnu.org/prep/standards_18.html). For information about POSIX syntax guidelines, see Section 12.2, "Utility Syntax Guidelines" of "The Single UNIX Specification Version 3" (http://www.unix-systems.org/online.html), also known as IEEE Standard 1003.1 and ISO/IEC 9945.