Статьи

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

Сентябрь 26, 2018

Это седьмой пост в моей серии, в котором кратко представлены различные библиотеки для обработки аргументов командной строки в Java. Этот пост возвращается к освещению библиотеки на основе аннотаций, которая кажется одной из наиболее известных и популярных из многочисленных доступных библиотек для обработки аргументов командной строки из Java: JCommander .

Веб -страница JCommander гласит: «Поскольку жизнь слишком коротка для разбора параметров командной строки», а « Обзор» представляет JCommander как «очень маленькую среду Java, которая упрощает анализ параметров командной строки». Примеры кода и соответствующие снимки экрана исполняемого кода в этом посте основаны на JCommander 1.72 (июнь 2017 г.). Полный код показанных здесь демонстраций доступен на GitHub .

JCommander использует аннотации для реализации этапа «определения» обработки командной строки. Это продемонстрировано в следующем фрагменте кода.

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

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
/**
 * Demonstrates use of JCommander for Java-based command-line processing.
 */
public class Main
{
   @Parameter(names={"-v","--verbose"},
              description="Enable verbose logging")
   private boolean verbose;
 
   @Parameter(names={"-f","--file"},
              description="Path and name of file to use",
              required=true)
   private String file;
 
   @Parameter(names={"-h", "--help"},
              description="Help/Usage",
              help=true)
   private boolean help;
 
   // . . .
 
final JCommander commander
   = JCommander.newBuilder()
              .programName("JCommander Demonstration")
             .addObject(this)
             .build();

Только что показанный листинг кода демонстрирует использование аннотации @Parameter в JCommander для определения параметров командной строки через аннотацию полей класса. В примерах демонстрируется спецификация names для обозначения нескольких флагов опций, которые должны быть связаны с одной опцией, description для предоставления описания каждой опции, required=true для обеспечения наличия аргумента командной строки и help=true для указания «help» »Или« использование »аргумента командной строки (указывает JCommander не генерировать исключение, если требуемые аргументы также не предоставлены).

С атрибутами класса, аннотированными аннотациями @Parameter , экземпляр класса с аннотированными полями можно использовать для создания экземпляра класса JCommander . В приведенном выше примере кода я использовал JCommander.Builder для большей беглости и других преимуществ, связанных с использованием компоновщиков. В частности, экземпляр с аннотированными полями классов добавляется с помощью метода addObject (Object) .

Этап «синтаксического анализа» обработки командной строки с помощью JCommander выполняется с помощью вызова одной строки метода синтаксического анализа (String…) на экземпляре JCommander который был только что JCommander . Это продемонстрировано в следующем листинге кода.

Этап «Разбор» с JCommander

1
commander.parse(arguments);

Этап «допроса» обработки командной строки с помощью JCommander включает простой доступ к аннотированным полям экземпляра, переданного в JCommander класса JCommander . Это продемонстрировано в следующем листинге кода.

Этап «Допрос» с JCommander

1
2
3
4
5
6
7
8
9
if (help)
{
   commander.usage();
}
else
{
   out.println(
      "The file name provided is '" + file + "' and verbosity is set to " + verbose);
}

Последний листинг кода демонстрирует возможность определения, был ли boolean атрибут с help имени задан спецификацией --help или -h . Поскольку это простое boolean , его можно использовать в условных выражениях и, если оно true , предоставляется информация справки / использования. В случае, если флаг «помощь» не был установлен, доступ к значениям, связанным с другими параметрами командной строки («verbose» / -v / --verbose и «file» / -f / --file ).

Самый последний листинг кода также демонстрирует запись информации об использовании в стандартный вывод посредством вызова метода JCommander () в экземпляре класса JCommander . Стоит отметить, что у ParameterException также есть метод use () .

Следующая серия снимков экрана демонстрирует использование JCommander с простым приложением, включающим приведенные выше фрагменты кода. Первое изображение показывает запуск приложения на основе JCommander без каких-либо аргументов и показывает исключение ParameterException , которое отображается в этом случае, поскольку не была указана необходимая опция --file / -f .

Следующий снимок экрана демонстрирует «нормальное» выполнение, когда предоставляются ожидаемые аргументы командной строки.

Следующий снимок экрана демонстрирует использование опции «помощь». Поскольку это было аннотировано с help=true , отсутствие обязательного аргумента командной строки «file» не приводит к исключению, и автоматически сгенерированная справка / информация об использовании записывается в стандартный вывод.

JCommander предоставляет функцию, которая мне очень нравится для разработки и изучения JCommander. Можно указать повышенную детализацию анализа JCommander, вызвав метод verbose (int) в JCommandBuilder .

Увеличивая многословность JCommander

1
2
3
4
5
6
final JCommander commander
   = JCommander.newBuilder()
               .programName("JCommander Demonstration")
               .addObject(this)
               .verbose(1)
               .build();

С увеличением детализации можно лучше понять, что делает JCommander в отношении обработки в командной строке, и это продемонстрировано на следующих двух снимках экрана.

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

  • JCommander имеет открытый исходный код и лицензируется с помощью Apache License 2.0 .
  • Размер jcommander-1.72.jar составляет приблизительно 68 КБ, и он не имеет сторонних зависимостей компиляции библиотеки.
  • Документация по JCommander содержит примеры использования JCommander с Kotlin и использования JCommander с Groovy .
  • JCommander все еще активно поддерживается создателем TestNG Седриком Беустом, и его веб-страница отражает его современную / текущую поддержку.

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

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