Интерфейсы командной строки Java: picocli

Всем привет!

Очередной старт группы «Разработчик Java» ^[1], на котором мы всё продолжаем наш эксперимент того, что процесс обучения не обязан быть непрерывным («Контрамоция должна быть непрерывной?» ). То есть мы чуть переработали и перетасовали программу, и разбили её на три ступени, которые можно спокойно проходить с перерывом между ними. В общем интересно и для студентов, и для нас, лишь бы никто не расхолаживался, а то программа стала даже вроде чуть сложнее, хотя и была непростой до этого. Ну и традиционно интересная статья связанная с нашим курсом.

Поехали!

На официальном сайте ^[2]picocli описывается как «мощный маленький интерфейс командной строки», который «является однофайловым Java-фреймворком для разбора аргументов командной строки и создания безупречных, легко настраиваемых вспомогательных сообщений. С цветами». В этом посте представлен краткий обзор Picocli 0.9.7 ^[3] и его применения для разбора аргументов командной строки в Java-коде.

Как и другие библиотеки обработки командной строки, написанные на Java, которые описаны в этой серии, picocli имеет открытый исходный код ^[4]. Поскольку вся picocli реализована в одном Java-файле ^[5], при желании можно легко использовать исходный код напрямую. Сайт picocli подчеркивает, что «отличительной особенностью picocli является то, что он позволяет пользователям запускать приложения, использующие picocli, не требуя самого picocli в качестве внешней зависимости: весь исходный код располагается в одном файле, чтобы побудить авторов приложений включить его в программный исходный код". Если вам больше нравится использовать picocli в качестве библиотеки, в Maven Repository есть JAR-файл ^[6] с множеством скомпилированных .class файлов (Picocli представляет собой один Java-файл, но содержит многочисленные вложенные классы и аннотации).

Самый простой способ получить представление об однофайловой природе Picocli — это взять и посмотреть на сам файл. Исходный код для CommandLine.java доступен на странице загрузки Picocli ^[5]. Следующие два скриншота показывают вывод из javap ^[7] при выполнении класса CommandLine и при выполнении одной из его внутренних аннотаций и одного из его внутренних классов.

Независимо от того, компилируем ли мы CommandLine.java в свой собственный класс/JAR-файл или используем уже собранный JAR из Maven, исходный код приложения, использующего Picocli, очевидно, будет один и тот же. Этап «определения» в разборе аргументов с помощью Picocli выполняется путем аннотирования полей экземпляра, который будет хранить значения, связанные с параметрами командной строки. Это показано в фрагменте кода ниже.

Этап “определения” в Picocli

/* 
Демонстрирует обработку командной строки Java с помощью picocli. 
 */  
@Command(  
   name="Main",  
   description="Demonstrating picocli",  
   headerHeading="Demonstration Usage:%n%n")  
public class Main  
{  
   @Option(names={"-v", "--verbose"}, description="Verbose output?")  
   private boolean verbose;  
  
   @Option(names={"-f", "--file"}, description="Path and name of file", required=true)  
   private String fileName;  
  
   @Option(names={"-h", "--help"}, description="Display help/usage.", help=true)  
   boolean help;  

Приведенный выше пример кода демонстрирует, что Picocli позволяет указывать несколько имен флагов (в моем примере указаны односимвольные имена с одним дефисом и многосимвольные имена с двумя дефисами). В этом примере также показывается, что для обязательных параметров может быть задано required=true, а для вспомогательных опций ^[8], таких как печать деталей использования и исключение ошибок, связанных с отсутствием требуемых параметров, может быть указано help=true. Обратите внимание, что в Picocli 0.9.8 добавлена дополнительная поддержка более специфичных типов вспомогательных сообщений versionHelp ^[8]и usageHelp ^[9].

Этап «разбора» в Picocli выполняется в CommandLine.populateCommand (T, String ...) ^[10], где T — экземпляр класса с Picocli-аннотированными полями, а оставшиеся строки — аргументы, которые нужно проанализировать. Это показано в следующем фрагменте кода.
Этап «разбора» в Picocli

final Main main = CommandLine.populateCommand(new Main(), arguments);  

Этап «опроса» в Picocli заключается в простом обращении к Picocli-аннотированным полям экземпляра, который передали в метод CommandLine.populateCommand (T, String ...) на этапе «разбора». Простой пример такого «опроса» показан в следующем листинге.

Этап «опроса» в Picocli

out.println(  
     "The provided file path and name is " + main.fileName  
   + " and verbosity is set to " + main.verbose);  

Отображать пользователю вспомогательные сообщения или информацию об использовании, когда в командной строке указано -h или --help, так же просто, как «опросить» Picocli-аннотированное поле, для которого было указано help=true, чтобы определить, установлено ли это логическое значение или нет и, если оно установлено, вызывать один из перегруженных методов CommandLine.usage. Мне пришлось использовать одну из статических версий этого метода, как показано в следующем листинге.

Вспомогательные сообщения / информация об использовании в Picocli

if (main.help)  
{  
   CommandLine.usage(main, out, CommandLine.Help.Ansi.AUTO);  
}  

Следующие несколько скриншотов демонстрируют простое приложение, написанное с использованием picocli. На первом скриншоте отображается тип сообщения об ошибке и трассировка стека, если требуемый флаг отсутствует. Второй скриншот показывает, как используются длинные и короткие имена, указанные в аннотациях. На третьем изображении показана функция отображения вспомогательных сообщений в действии.

Одна из дополнительных возможностей Picocli, которая отсутствует во многих других библиотеках разбора аргументов командной строки, написанных на Java, — это поддержка цветного синтаксис ^[11]а. В первом листинге этого поста были строки, определенные в аннотациях с @ | | @ синтаксисом. На скриншоте выше, который демонстрирует использование вспомогательных сообщений, эти символы были переданы как есть, без специальной обработки. Однако, если я запущу этот пример кода в Cygwin, я увижу, что делают эти знаки.

На приведенном выше скриншоте мы видим, что Picocli автоматически применил цветной синтаксис (желтый и белый) к опциям вспомогательных сообщений а также применил жирный и подчеркнутый жирный синтаксис к областям с описанием вспомогательных сообщений, где применен синтаксис @ | | @.

Ниже приведены дополнительные характеристики Picocli, которые следует учитывать при выборе фреймворка или библиотеки, помогающих с разбором аргументов командной строки в Java.

• Picocli является проектом с открытым исходным кодом с лицензией Apache 2.0. ^[12]
• Picocli не требует загрузки сторонних библиотек или фреймворков.
• Весь исходный код Picocli содержится в одном .java файле, и этот код может быть скопирован и вставлен в собственную систему управления конфигурацией и собран с остальной частью кода приложения, это означает, что даже JAR-файл Picocli не является необходимым.
• Файл исходного кода CommandLine.java (Picocli 0.9.7) составляет чуть более 3700 строк (включая пробелы и комментарии) и весит почти 200 КБ. Файл picocli-0.9.7.jar весит около 83 КБ.
• Picocli своевременно и часто обновляется. Версия 0.9.8 была выпущена вчера (после того, как я написал большую часть этого поста).
• Picocli имеет очень подробную документацию ^[13] и она во многом более современна, чем документация для некоторых других библиотек обработки командной строки, написанных на Java.
• Поддержка цветного синтаксиса в Picocli проста в использовании, а справка об использовании цветного синтаксиса на разных платформах задокументирована в разделе «Поддерживаемые платформы ^[14]».
• Использование аннотаций Picocli для полей на уровне экземпляра похоже на использование аннотаций в некоторых других библиотек обработки командной строки и имеет те же преимущества.
• Основные возможности Picocli очень удобны и легко осваиваются, но Picocli также поддерживает возможность настройки нескольких аспектов обработки командной строки с помощью Picocli.

Листинги, приведенные в этом посте, полностью доступны на GitHub ^[15].

Picocli — это поддерживаемая и обновляемая библиотека для разбора аргументов командной строки Java. Она содержит несколько новых фич и подходов из некоторых других доступных библиотек обработки командной строки, написанных на Java, но в нее добавлены пара отличающихся фич (таких как цветной синтаксис и целая библиотека, инкапсулированная в один исходный Java-файл). Picocli достаточно проста в использовании и привлекательна сама по себе, но, скорее всего, она будет выделяться среди других библиотек для отдельного разработчика, если этот разработчик хочет поддержки цветного синтаксиса или возможности добавить файл исходного кода в проект разработчика без дополнительных JAR-файлов или скомпилированных .class-файлов.

THE END

Как всегда ждём ваши вопросы и комментарии.

Автор: MaxRokatansky

Источник ^[16]