介紹

Picocli是一個單文件命令行解析框架，它使您幾乎不需要任何代碼即可創建命令行應用程序。 使用@Option或@Parameters注釋應用程序中的字段，picocli將分別使用命令行選項和位置參數填充這些字段。 例如：

@Command(name = "Greet", header = "%n@|green Hello world demo|@") class Greet implements Runnable {@Option(names = {"-u", "--user"}, required = true, description = "The user name.")String userName;public void run() {System.out.println("Hello, " + userName);}public static void main(String... args) {CommandLine.run(new Greet(), System.err, args);} }

當我們執行該程序時，picocli會在調用run方法之前解析命令行并填充userName字段：

$ java Greet -u picocliHello, picocli

Picocli生成具有Ansi顏色和樣式的使用幫助消息。 如果我們在輸入無效的情況下運行上述程序（缺少必需的用戶名選項），picocli將顯示錯誤和使用幫助消息：

Picocli可以生成自動完成腳本，該腳本允許最終用戶使用<TAB>命令行完成功能來發現可用的選項和子命令。 您可能還喜歡picocli對子命令和嵌套子子命令的任何深度的支持。

用戶手冊詳細介紹了picocli的功能。 本文重點介紹了picocli 2.0版本引入的新功能和值得注意的功能。

帶有位置參數的混合選項

解析器得到了改進，現在可以在命令行中將位置參數與選項混合使用。

以前，位置參數必須遵循選項。 從此版本開始，任何不是選項或子命令的命令行參數都將被解釋為位置參數。

例如：

class MixDemo implements Runnable {@Option(names = "-o")List<String> options;@ParametersList<String> positional;public void run() {System.out.println("positional: " + positional);System.out.println("options : " + options);}public static void main(String[] args) {CommandLine.run(new MixDemo(), System.err, args);} }

通過混合使用選項和位置參數來運行上述類，表明將非選項識別為位置參數。 例如：

$ java MixDemo param0 -o AAA param1 param2 -o BBB param3positional: [param0, param1, param2, param3] options : [AAA, BBB]

為了支持帶有位置參數的混合選項，解析器已更改。 從picocli 2.0開始， 默認情況下 ，多值選項（數組，列表和地圖字段） 不再貪婪 。 2.0發行說明詳細描述了此更改和其他可能的重大更改 。

發現集合類型

Picocli執行將命令行參數自動類型轉換為帶注釋字段的類型。 命名選項和位置參數都可以強類型化。

在v2.0之前，picocli需要在Collection和Map字段中標注type屬性，以便能夠進行類型轉換。 對于其他類型的字段，例如數組字段和int或java.io.File字段等單值字段，picocli會自動從字段類型中檢測目標類型，但是集合和映射需要更多詳細的注釋。 例如：

class Before {@Option(names = "-u", type = {TimeUnit.class, Long.class})Map<TimeUnit, Long> timeout;@Parameters(type = File.class)List<File> files; }

從v2.0開始，對于Collection和Map字段，不再需要type屬性：picocli將根據通用類型推斷出collection元素的類型。 type屬性仍然像以前一樣工作，在大多數情況下只是可選的。

省略type屬性可消除某些重復，并產生更簡單，更簡潔的代碼：

class Current {@Option(names = "-u")Map<TimeUnit, Long> timeout;@ParametersList<File> files; }

在上面的示例中，picocli 2.0能夠自動發現將命令行參數添加到列表之前需要將其轉換為File ，對于地圖而言，需要將鍵轉換為TimeUnit并將值轉換為Long 。

自動幫助

Picocli提供了許多方便的方法，例如run和call ，它們可以解析命令行參數，處理錯誤并調用接口方法來執行應用程序。

從此版本開始，當用戶在命令行上指定帶有versionHelp或usageHelp屬性注釋的選項時，便捷方法還將自動打印使用幫助和版本信息。

下面的示例程序演示了自動幫助：

@Command(version = "Help demo v1.2.3", header = "%nAutomatic Help Demo%n",description = "Prints usage help and version help when requested.%n") class AutomaticHelpDemo implements Runnable {@Option(names = "--count", description = "The number of times to repeat.")int count;@Option(names = {"-h", "--help"}, usageHelp = true,description = "Print usage help and exit.")boolean usageHelpRequested;@Option(names = {"-V", "--version"}, versionHelp = true,description = "Print version information and exit.")boolean versionHelpRequested;public void run() {// NOTE: code like below is no longer required://// if (usageHelpRequested) {// new CommandLine(this).usage(System.err);// } else if (versionHelpRequested) {// new CommandLine(this).printVersionHelp(System.err);// } else { ... the business logicfor (int i = 0; i < count; i++) {System.out.println("Hello world");}}public static void main(String... args) {CommandLine.run(new AutomaticHelpDemo(), System.err, args);} }

與-h或--help一起執行時，程序將輸出用法幫助：

類似地，當使用-V或--version執行時，程序將輸出版本信息：

自動打印幫助的方法：

• CommandLine :: call
• 命令行::運行
• CommandLine :: parseWithHandler（帶有內置的Run ...處理程序）
• CommandLine :: parseWithHandlers（帶有內置的Run ...處理程序）

不會自動打印幫助的方法：

• CommandLine :: parse
• 命令行:: populateCommand

更好的子命令支持

此版本添加了新的CommandLine::parseWithHandler方法。 這些方法提供了與run和call方法相同的易用性，但具有更大的靈活性，并且更好地支持嵌套子命令。

考慮帶有子命令的應用程序需要做什么：

解析命令行。

如果用戶輸入無效，則在解析失敗的地方為子命令打印錯誤消息和用法幫助消息。

如果解析成功，請檢查用戶是否為頂級命令或子命令請求了使用幫助或版本信息。 如果是這樣，請打印所需的信息并退出。

否則，執行業務邏輯。 通常，這意味著執行最特定的子命令。

Picocli提供了一些構建基塊來完成此任務，但應由應用程序將它們連接在一起。 該接線本質上是樣板，在應用程序之間非常相似。 例如，以前，帶有子命令的應用程序通常包含如下代碼：

public static void main() {// 1. parse the command lineCommandLine top = new CommandLine(new YourApp());List<CommandLine> parsedCommands;try {parsedCommands = top.parse(args);} catch (ParameterException ex) {// 2. handle incorrect user input for one of the subcommandsSystem.err.println(ex.getMessage());ex.getCommandLine().usage(System.err);return;}// 3. check if the user requested helpfor (CommandLine parsed : parsedCommands) {if (parsed.isUsageHelpRequested()) {parsed.usage(System.err);return;} else if (parsed.isVersionHelpRequested()) {parsed.printVersionHelp(System.err);return;}}// 4. execute the most specific subcommandObject last = parsedCommands.get(parsedCommands.size() - 1).getCommand();if (last instanceof Runnable) {((Runnable) last).run();} else if (last instanceof Callable) {Object result = ((Callable) last).call();// ... do something with result} else {throw new ExecutionException("Not a Runnable or Callable");} }

這是很多樣板代碼。 Picocli 2.0提供了一種便捷的方法，使您可以將以上所有內容簡化為一行代碼，以便您可以專注于應用程序的業務邏輯：

public static void main() {// This handles all of the above in one line:// 1. parse the command line// 2. handle incorrect user input for one of the subcommands// 3. automatically print help if requested// 4. execute one or more subcommandsnew CommandLine(new YourApp()).parseWithHandler(new RunLast(), System.err, args); }

新的便捷方法是parseWithHandler 。 您可以創建自己的自定義處理程序，也可以使用內置處理程序之一。 Picocli提供了一些常見用例的處理程序實現。

內置的處理程序是RunFirst ， RunLast和RunAll 。 所有這些都提供了自動幫助：如果用戶請求了useHelpHelp或versionHelp，則將打印所請求的信息，并且處理程序將返回而無需進一步處理。 處理程序希望所有命令都實現java.lang.Runnable或java.util.concurrent.Callable 。

• RunLast執行最特定的命令或子命令。 例如，如果用戶調用了java Git commit -m "commit message" ，則picocli會將Git視為頂級命令并commit一個子命令。 在此示例中， commit子命令是最特定的命令，因此RunLast僅執行該子命令。 如果沒有子命令，則執行頂層命令。 RunLast現在由picocli內部使用，用于執行現有CommandLine::run和CommandLine::call方便的方法。
• RunFirst僅執行first ，頂層命令，而忽略子命令。
• RunAll執行頂層命令和出現在命令行中的所有子命令。

還有一個parseWithHandlers方法，該方法與此類似，但另外，您還可以為錯誤的用戶輸入指定自定義處理程序。

改進的

現在， CommandLine::call和CommandLine::run便捷方法支持子命令，并將執行用戶指定的最后一個子命令。 以前，子命令將被忽略，僅執行頂層命令。

改進的例外

最后，從該版本開始，所有picocli異常都提供了getCommandLine方法，該方法在解析或執行失敗的情況下返回命令或子命令。 以前，如果用戶為帶有子命令的應用程序提供了無效的輸入，則很難準確地指出哪個子命令未能解析輸入。

結論

如果您已經在使用picocli，則v2.0是必不可少的升級。 如果您以前從未使用過picocli，希望以上內容使您有興趣嘗試一下。

其中許多改進源自用戶反饋和后續討論。 請隨時在picocli 問題跟蹤器上提問，索取功能或提供其他反饋。

如果愿意，請在GitHub上為項目加注星標，然后告訴您的朋友！

翻譯自: https://www.javacodegeeks.com/2018/01/picocli-2-0-less.html

創作挑戰賽新人創作獎勵來咯，堅持創作打卡瓜分現金大獎

總結

以上是生活随笔為你收集整理的Picocli 2.0：事半功倍的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。