Picocli 2.0:类固醇上的Groovy脚本
Picocli 2.0增加了对其他JVM语言(尤其是Groovy)的支持。 当Groovy语言具有CliBuilder类的内置CLI支持时,为什么要使用picocli?
您可能会喜欢picocli的使用帮助,默认情况下会显示ANSI 颜色和样式 。 您可能喜欢的另一个功能是命令行TAB自动补全 。 最后,还有很多较小的功能,例如您的脚本需要零行的命令行解析代码,picocli的子命令支持,选项和位置参数的类型转换以及解析器跟踪等。
例
让我们看一个例子。 下面的checksum.groovy
脚本采用一个或多个文件参数,并为每个文件打印出一个校验和和文件名。 默认情况下,“校验和”算法为MD5,但用户可以指定其他MessageDigest算法。 用户可以使用-h
或--help
选项来请求使用帮助。
@Grab('info.picocli:picocli:2.0.3') @picocli.groovy.PicocliScript import groovy.transform.Field import java.security.MessageDigest import static picocli.CommandLine.* @Parameters(arity="1", paramLabel="FILE", description="The file(s) whose checksum to calculate.") @Field File[] files @Option(names = ["-a", "--algorithm"], description = [ "MD2, MD5, SHA-1, SHA-256, SHA-384, SHA-512,", " or any other MessageDigest algorithm."]) @Field String algorithm = "MD5" @Option(names= ["-h", "--help"], usageHelp= true, description= "Show this help message and exit.") @Field boolean helpRequested files.each { println MessageDigest.getInstance(algorithm).digest(it.bytes).encodeHex().toString() + "\t" + it }
在$picocli-home/examples/src/main/groovy/picocli/examples
目录中运行时,此示例脚本将产生以下结果:
$ groovy checksum.groovy *.* 4995d24bbb3adf67e2120c36dd3027b7 checksum.groovy a03c852de017f9303fcc373c7adafac6 checksum-with-banner.groovy 1ee567193bf41cc835ce76b6ca29ed30 checksum-without-base.groovy
使用-h
或--help
选项调用脚本将显示以下ANSI颜色和样式的用法帮助消息:
代码在哪里?
您可能已经注意到,上面的脚本不包含任何用于解析命令行参数或处理使用帮助请求的逻辑。
没有@picocli.groovy.PicocliScript
批注,脚本代码将如下所示:
class Checksum { @Parameters(arity = "1", paramLabel = "FILE", description = "...") File[] files @Option(names = ["-a", "--algorithm"], description = ["..."]) String algorithm = "MD5" @Option(names = ["-h", "--help"], usageHelp = true, description = "...") boolean helpRequested } Checksum checksum = new Checksum() CommandLine commandLine = new CommandLine(checksum) try { commandLine.parse(args) if (commandLine.usageHelpRequested) { commandLine.usage(System.out) } else { checksum.files.each { byte[] digest = MessageDigest.getInstance(checksum.algorithm).digest(it.bytes) println digest.encodeHex().toString() + "\t" + it } } } catch (ParameterException ex) { println ex.message commandLine.usage(System.out) }
上面的示例包含用于解析命令行,处理无效用户输入以及检查使用帮助请求的显式代码。 该脚本的第一个版本没有任何此样板代码。
让我们看一下它是如何工作的。
底标
用@picocli.groovy.PicocliScript
注释的脚本会自动转换为使用picocli.groovy.PicocliBaseScript
作为其基类。 这会将Groovy脚本变成基于picocli的命令行应用程序。
运行脚本时,Groovy会调用脚本的run
方法。 PicocliBaseScript::run
方法负责解析命令行并使用结果填充脚本字段。 run方法执行以下操作:
- 首先,以
@Option
或@Parameters
注释的@Field
变量是从命令行参数初始化的。 - 如果用户输入无效,则会打印一条错误消息,然后显示用法帮助消息。
- 如果用户请求使用帮助或版本信息,则将其打印到控制台并退出脚本。
- 否则,将执行脚本主体。
可以自定义此行为,有关更多详细信息,请参见PicocliBaseScript javadoc 。
除了更改脚本基类, @PicocliScript
批注还允许Groovy脚本直接使用@Command
批注,而无需引入帮助程序类。 picocli解析器将在包含@Option
和@Parameters
注释字段的类中寻找此注释。 更改脚本基类的同一自定义AST转换还将脚本中的任何@Command
注释都移动到此转换后的类,以便picocli解析器可以将其拾取。
颜色的使用帮助
@Command
注释使您可以自定义用法帮助消息的各个部分,例如命令名称,描述,页眉,页脚等。
让我们在示例脚本中添加一些麻烦。 (对于ASCII Art Generator,请登录http://patorjk.com/software/taag/ 。)
@Grab('info.picocli:picocli:2.0.3') @Command(header = [ $/@|bold,green ___ ___ _ _ |@/$, $/@|bold,green / __|_ _ ___ _____ ___ _ / __| |_ ___ __| |__ ____ _ _ __ |@/$, $/@|bold,green | (_ | '_/ _ \/ _ \ V / || | | (__| ' \/ -_) _| / /(_-< || | ' \ |@/$, $/@|bold,green \___|_| \___/\___/\_/ \_, | \___|_||_\___\__|_\_\/__/\_,_|_|_|_||@/$, $/@|bold,green |__/ |@/$ ], description = "Print a checksum of each specified FILE.", version = 'checksum v1.2.3', showDefaultValues = true, footerHeading = "%nFor more details, see:%n", footer = ["[1] https://docs.oracle.com/javase/9/docs/specs/security/standard-names.html", "ASCII Art thanks to http://patorjk.com/software/taag/"] ) @picocli.groovy.PicocliScript import groovy.transform.Field import java.security.MessageDigest import static picocli.CommandLine.* @Parameters(arity="1", paramLabel="FILE", description="The file(s) whose checksum to calculate.") @Field private File[] files @Option(names = ["-a", "--algorithm"], description = [ "MD2, MD5, SHA-1, SHA-256, SHA-384, SHA-512, or", " any other MessageDigest algorithm. See [1] for more details."]) @Field private String algorithm = "MD5" @Option(names= ["-h", "--help"], usageHelp=true, description="Show this help message and exit.") @Field private boolean helpRequested @Option(names= ["-V", "--version"], versionHelp=true, description="Show version info and exit.") @Field private boolean versionInfoRequested files.each { println MessageDigest.getInstance(algorithm).digest(it.bytes).encodeHex().toString() + "\t" + it }
脚本的新版本添加了页眉和页脚,以及打印版本信息的功能。 使用帮助消息和版本信息中显示的所有文本都可能包含格式说明符,例如%n
行分隔符。
使用帮助消息还可以显示ANSI颜色和样式。 Picocli支持简单的标记语法,其中@|
开始一个ANSI样式的节, |@
结束它。 立即跟随@|
是用逗号分隔的颜色和样式的列表,例如@|STYLE1[,STYLE2]… text|@
。 有关可用颜色和样式的详细信息,请参见picocli 用户手册 。
新脚本的用法帮助消息如下所示:
@Command
批注还具有version = "checksum v1.2.3"
属性。 当用户指定该版本字符串印刷--version
在命令行上,因为我们声明的@Option
带属性,该属性名称versionHelp = true
。
$ groovy checksum-with-banner.groovy --version checksum v1.2.3
有关更多详细信息,请参见用户手册的“ 版本帮助”部分。
结论
@PicocliScript
批注允许Groovy脚本省略样板代码,同时添加强大的通用命令行应用程序功能。 在示例脚本的最终版本中,大多数代码实际上是使用帮助消息的描述文本。
picocli还有很多其他功能,请尝试一下!
如果愿意,请在GitHub上为项目加注星标,然后告诉您的朋友!
翻译自: https://www.javacodegeeks.com/2018/01/picocli-2-0-groovy-scripts-steroids.html