Статьи

Интерфейсы командной строки Java (часть 10): picocli

Декабрь 1, 2018

Главная страница picocli описывает picocli как «могущественный крошечный интерфейс командной строки», который «представляет собой однофайловую инфраструктуру Java для анализа аргументов командной строки и создания полированных, легко настраиваемых сообщений помощи по использованию. С цветами. » Этот пост содержит краткий обзор применения Picocli 0.9.7 для обработки аргументов командной строки в коде Java.

Как и другие библиотеки обработки командной строки на основе Java, рассмотренные в этой серии, picolci имеет открытый исходный код . Поскольку вся реализация picocli существует в одном файле исходного кода Java, при желании легко использовать источник напрямую. На странице picocli это подчеркивается: «Отличительной особенностью picocli является то, как она стремится позволить пользователям запускать приложения на основе picocli, не требуя picocli в качестве внешней зависимости: весь исходный код находится в одном файле, чтобы поощрить авторов приложений включать его в исходная форма . » Если вы предпочитаете использовать Picocli в качестве библиотеки, в репозитории Maven имеется JAR с многочисленными скомпилированными файлами .class (Picocli содержит один файл Java, но с множеством вложенных классов и аннотаций).

Самый простой подход к пониманию однофайловой природы Picocli — это посмотреть на этот отдельный файл. Исходный код Java для CommandLine.java доступен на странице загрузки Picocli . Следующие два снимка экрана показывают некоторый вывод из javap, когда выполняются против класса CommandLine и когда выполняются против одной его внутренней аннотации и одного из его внутренних классов.

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

Этап «Определение» с Picocli

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
/**
 * Demonstrate Java-based command-line processing with 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 добавляет более конкретную поддержку типов справки с помощью usageHelp и usageHelp .

Этап «синтаксического анализа» выполняется в Picocli с помощью CommandLine.populateCommand (T, String…) , где T является экземпляром класса с полями, аннотированными Picocli, а оставшиеся String St являются аргументами для анализа. Это продемонстрировано в следующем фрагменте кода.

Этап «Парсинга» с Picocli

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

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

Этап «Допрос» с Пикокли

1
2
3
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 . Мне довелось использовать одну из static версий этого метода, как показано в следующем листинге кода.

Помощь / Использование с Picocli

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

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

Одной из дополнительных функций Picocli, которой нет во многих других библиотеках синтаксического анализа на основе Java, является поддержка цветового синтаксиса . Первый листинг кода в этом посте показал некоторые строки, определенные в аннотациях с @| |@ @| |@ синтаксис. На снимке экрана, демонстрирующем использование «помощи» выше, эти символы были переданы как есть без специальной обработки. Однако, если я вместо этого запущу этот пример кода в Cygwin, я увижу, чего достигают эти токены.

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

Вот некоторые дополнительные характеристики Picocli, которые следует учитывать при выборе каркаса или библиотеки, чтобы помочь с анализом командной строки в Java.

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

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

Дополнительные ссылки

Ссылка: Интерфейсы командной строки Java (часть 10): picocli от нашего партнера по JCG Дастина Маркса в блоге Inspired by Actual Events .
47
Share: