Apache Commons CLI 1.4 （命令行选项解析工具）的简单使用

Commons CLI简介

Apache Commons CLI库提供了一个API，用于解析传递给程序的命令行选项。它还能够打印详细说明命令行工具可用选项的帮助消息。

Commons CLI显示的典型帮助消息如下所示：

usage: ls
 -A,--almost-all          do not list implied . and ..
 -a,--all                 do not hide entries starting with .
 -B,--ignore-backups      do not list implied entried ending with ~
 -b,--escape              print octal escapes for nongraphic characters
    --block-size <SIZE>   use SIZE-byte blocks
 -c                       with -lt: sort by, and show, ctime (time of last
                          modification of file status information) with
                          -l:show ctime and sort by name otherwise: sort
                          by ctime
 -C                       list entries by columns

命令行处理有三个阶段。它们是Definition，Parsing，Interrogation。以下部分将依次讨论这些阶段，并讨论如何使用CLI实现它们。

Definition Stage(定义阶段)

每个命令行必须定义将用于定义应用程序接口的选项集。

CLI使用 Options类作为 Option实例的容器 。在CLI中有两种方法可以创建 Option。其中一个是通过构造函数，另一个是通过Options中定义的工厂方法 。

该使用方案文档提供了示例如何创建一个选项对象，还提供了一些真实的例子。

定义阶段的结果是Options 实例。

Parsing Stage(解析阶段)

解析阶段是处理通过命令行传递到应用程序的文本的位置。根据解析器实现定义的规则处理文本。

在 CommandLineParser上定义 的parse方法 接受一个Options 实例和一个String []参数，并返回一个 CommandLine。

解析阶段的结果是CommandLine 实例。

Interrogation Stage(询问阶段)

询问阶段是应用程序查询 CommandLine以根据布尔选项决定要执行的执行分支并使用选项值来提供应用程序数据的位置。

此阶段在用户代码中实现。CommandLine上的访问器方法为用户代码提供了询问功能。

询问阶段的结果是用户代码完全了解在命令行上提供的所有文本，并根据解析器和选项 规则进行处理。

使用场景

布尔选项

布尔选项通过选项的存在在命令行上表示，即如果找到选项，则选项值为true，否则值为false。

该DateApp工具打印当前日期到标准输出。如果存在-t选项，则还会打印当前时间。

Option help = new Option( "help", "print this message" );
Option projecthelp = new Option( "projecthelp", "print project help information" );

创建选项

Option必须添加到一个创建的Options对象上

// create Options object
Options options = new Options();

// add t option
options.addOption("t", false, "display current time");

该addOption方法有三个参数。第一个参数是表示选项的，类型为java.lang.String。第二个参数是一个boolean，指定选项是否有传递参数。第三个参数是选项的描述。此描述将用于应用程序的使用文本中。

解析命令行参数

CommandLineParser 的parser方法用于解析命令行参数。CommandLineParser接口可能有多种实现，推荐的是 DefaultParser。

CommandLineParser parser = new DefaultParser();
CommandLine cmd = parser.parse( options, args);

现在我们检查参数t选项是否存在。为此我们将使用hasOption方法检测到参数存在返回true，否则返回false

if(cmd.hasOption("t")) {
    // print the date and time
}
else {
    // print the date
}

国际时间

InternationalDateApp工具扩展了 DateApp通过提供打印的日期和时间，在任何一个国家在世界上的能力效用。为方便起见，引入了新的命令行选项c

// add c option
options.addOption("c", true, "country code");

第二个参数是true。这指定 c选项需要参数值。如果在命令行上指定了必需的选项参数值，则返回该值，否则返回null。

检索参数值

CommandLine 的getOptionValue方法用于检索选项的参数值。

// get c option value
String countryCode = cmd.getOptionValue("c");

if(countryCode == null) {
    // print default date
}
else {
    // print date for country specified by countryCode
}

参数选项

参数选项使用OptionBuilder创建。

Option logfile   = OptionBuilder.withArgName( "file" )
                                .hasArg()
                                .withDescription(  "use given file for log" )
                                .create( "logfile" );

用法/帮助

CLI还提供自动生成使用和帮助信息的方法。这是通过HelpFormatter 类实现的 。

//自动生成帮助语句
HelpFormatter formatter = new HelpFormatter（）; 
formatter.printHelp（“ant”，options）;

如果还需要打印用法语句，则调用formatter.printHelp（“ant”，options，true） 将生成使用情况声明以及帮助信息。

更多使用场景见：http://commons.apache.org/proper/commons-cli/usage.html

选项属性

以下是每个选项具有的属性 。所有这些都可以使用访问器或使用OptionBuilder中定义的方法进行设置

Name	Type	Description
opt	java.lang.String	Option的标识字符串
longOpt	java.lang.String	别名和更具描述性的标识字符串
description	java.lang.String	选项功能的描述
required	boolean	一个标志，指出该选项是否必须出现在命令行中。
arg	boolean	一个标志，说明该选项是否参与
args	boolean	一个标志，说明该选项是否需要多个参数
optionalArg	boolean	一个标志，指出该选项的参数是否是可选的
argName	java.lang.String	用法语句的参数值的名称
valueSeparator	char	用于拆分参数字符串的字符值，与multipArgs一起使用，例如，如果分隔符为’，’，且参数字符串为’a，b，c’，则有三个参数值，‘a’，'b ‘和’c’。
type	java.lang.Object	参数的类型
value	java.lang.String	option的value值
values	java.lang.String[]	option的多个value值

API文档

http://commons.apache.org/proper/commons-cli/javadocs/api-release/index.html

参考文档

http://commons.apache.org/proper/commons-cli/index.html