[Перевод] Интерфейсы командной строки Java: picocli
Всем привет!
Очередной старт группы «Разработчик Java», на котором мы всё продолжаем наш эксперимент того, что процесс обучения не обязан быть непрерывным («Контрамоция должна быть непрерывной?»). То есть мы чуть переработали и перетасовали программу, и разбили её на три ступени, которые можно спокойно проходить с перерывом между ними. В общем интересно и для студентов, и для нас, лишь бы никто не расхолаживался, а то программа стала даже вроде чуть сложнее, хотя и была непростой до этого. Ну и традиционно интересная статья связанная с нашим курсом.
Поехали!
На официальном сайте picocli описывается как «мощный маленький интерфейс командной строки», который «является однофайловым Java-фреймворком для разбора аргументов командной строки и создания безупречных, легко настраиваемых вспомогательных сообщений. С цветами». В этом посте представлен краткий обзор Picocli 0.9.7 и его применения для разбора аргументов командной строки в Java-коде.
Как и другие библиотеки обработки командной строки, написанные на Java, которые описаны в этой серии, picocli имеет открытый исходный код. Поскольку вся picocli реализована в одном Java-файле, при желании можно легко использовать исходный код напрямую. Сайт picocli подчеркивает, что «отличительной особенностью picocli является то, что он позволяет пользователям запускать приложения, использующие picocli, не требуя самого picocli в качестве внешней зависимости: весь исходный код располагается в одном файле, чтобы побудить авторов приложений включить его в программный исходный код». Если вам больше нравится использовать picocli в качестве библиотеки, в Maven Repository есть JAR-файл с множеством скомпилированных .class файлов (Picocli представляет собой один Java-файл, но содержит многочисленные вложенные классы и аннотации).
Самый простой способ получить представление об однофайловой природе Picocli — это взять и посмотреть на сам файл. Исходный код для CommandLine.java доступен на странице загрузки Picocli. Следующие два скриншота показывают вывод из javap при выполнении класса 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, а для вспомогательных опций, таких как печать деталей использования и исключение ошибок, связанных с отсутствием требуемых параметров, может быть указано help=true. Обратите внимание, что в Picocli 0.9.8 добавлена дополнительная поддержка более специфичных типов вспомогательных сообщений versionHelp и usageHelp.
Этап «разбора» в Picocli выполняется в CommandLine.populateCommand (T, String …), где 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, — это поддержка цветного синтаксиса. В первом листинге этого поста были строки, определенные в аннотациях с @ | | @ синтаксисом. На скриншоте выше, который демонстрирует использование вспомогательных сообщений, эти символы были переданы как есть, без специальной обработки. Однако, если я запущу этот пример кода в Cygwin, я увижу, что делают эти знаки.
На приведенном выше скриншоте мы видим, что Picocli автоматически применил цветной синтаксис (желтый и белый) к опциям вспомогательных сообщений, а также применил жирный и подчеркнутый жирный синтаксис к областям с описанием вспомогательных сообщений, где применен синтаксис @ | | @.
Ниже приведены дополнительные характеристики Picocli, которые следует учитывать при выборе фреймворка или библиотеки, помогающих с разбором аргументов командной строки в Java.
- Picocli является проектом с открытым исходным кодом с лицензией Apache 2.0.
- Picocli не требует загрузки сторонних библиотек или фреймворков.
- Весь исходный код Picocli содержится в одном .java файле, и этот код может быть скопирован и вставлен в собственную систему управления конфигурацией и собран с остальной частью кода приложения, это означает, что даже JAR-файл Picocli не является необходимым.
- Файл исходного кода CommandLine.java (Picocli 0.9.7) составляет чуть более 3700 строк (включая пробелы и комментарии) и весит почти 200 КБ. Файл picocli-0.9.7.jar весит около 83 КБ.
- Picocli своевременно и часто обновляется. Версия 0.9.8 была выпущена вчера (после того, как я написал большую часть этого поста).
- Picocli имеет очень подробную документацию и она во многом более современна, чем документация для некоторых других библиотек обработки командной строки, написанных на Java.
- Поддержка цветного синтаксиса в Picocli проста в использовании, а справка об использовании цветного синтаксиса на разных платформах задокументирована в разделе «Поддерживаемые платформы».
- Использование аннотаций Picocli для полей на уровне экземпляра похоже на использование аннотаций в некоторых других библиотек обработки командной строки и имеет те же преимущества.
- Основные возможности Picocli очень удобны и легко осваиваются, но Picocli также поддерживает возможность настройки нескольких аспектов обработки командной строки с помощью Picocli.
Листинги, приведенные в этом посте, полностью доступны на GitHub.
Picocli — это поддерживаемая и обновляемая библиотека для разбора аргументов командной строки Java. Она содержит несколько новых фич и подходов из некоторых других доступных библиотек обработки командной строки, написанных на Java, но в нее добавлены пара отличающихся фич (таких как цветной синтаксис и целая библиотека, инкапсулированная в один исходный Java-файл). Picocli достаточно проста в использовании и привлекательна сама по себе, но, скорее всего, она будет выделяться среди других библиотек для отдельного разработчика, если этот разработчик хочет поддержки цветного синтаксиса или возможности добавить файл исходного кода в проект разработчика без дополнительных JAR-файлов или скомпилированных .class-файлов.
THE END
Как всегда ждём ваши вопросы и комментарии.
