picocli

picocli — очень маленький интерфейс командной строки

Picocli стремится стать самым простым в использовании способом создания многофункциональных приложений командной строки, которые могут работать как на JVM, так и за ее пределами. Рассматриваете пикокли? Посмотрите, что счастливые пользователи говорят о picocli.

Picocli — это современная библиотека и платформа, написанная на Java, которая содержит как API аннотаций, так и программный API. Он включает помощь по использованию цветов и стилей ANSI, автозаполнение TAB и вложенные подкоманды. В одном файле, поэтому вы можете включить его в исходную форму . Это позволяет пользователям запускать приложения на основе picocli, не требуя picocli в качестве внешней зависимости.

Приложения на основе Picocli могут быть заранее скомпилированы в собственный образ с чрезвычайно быстрым запуском и меньшими требованиями к памяти, который можно распространять как один исполняемый файл. Picocli поставляется с обработчиком аннотаций, который автоматически включает Graal для вашего jar-файла во время компиляции.

Приложения Picocli могут быть очень компактными и не содержать шаблонного кода: ваша команда (или подкоманда) может быть выполнена с помощью одной строки кода. Просто реализуйте Runnable или Callable или поместите бизнес-логику вашей команды в метод с аннотацией @Command .

Picocli позволяет легко следовать рекомендациям по интерфейсу командной строки.

Как это работает: аннотируйте свой класс, и picocli инициализирует его из аргументов командной строки, преобразуя входные данные в строго типизированные данные. Поддерживает подкоманды в стиле git (и вложенные подкоманды), любой стиль префикса параметров, сгруппированные короткие параметры в стиле POSIX, преобразователи настраиваемых типов, параметры пароля и многое другое.

Picocli различает именованные параметры и позиционные параметры и позволяет строго типизировать оба . Многозначные поля могут указывать точное количество параметров или диапазон (например, 0..* , 1..2 ). Поддерживает такие параметры карты, как -Dkey1=val1 -Dkey2=val2 , где и ключ, и значение могут быть строго типизированы. Трассировка парсера облегчает устранение неполадок. Файлы аргументов командной строки (@-files) позволяют приложениям обрабатывать очень длинные командные строки.

Создает отполированную и легко адаптируемую справку по использованию и версии, используя, где это возможно, цвета ANSI. Требуется как минимум Java 5, но он предназначен для облегчения использования лямбда-выражений Java 8. Протестировано на всех версиях Java от 5 до 18 (включительно).

Приложения командной строки на основе Picocli могут иметь автозаполнение TAB, интерактивно показывая пользователям, какие параметры и подкоманды доступны. Если параметр имеет completionCandidates или тип enum , автозаполнение также может предлагать значения параметра. Picocli может генерировать сценарии завершения для bash и zsh и предлагает модули picocli-shell-jline2 и picocli-shell-jline3 с реализациями JLine Completer для создания интерактивных приложений оболочки.

Уникальные функции picocli включают поддержку отрицаемых параметров, расширенные значения в кавычках и группы аргументов. Группы аргументов можно использовать для создания взаимоисключающих параметров, взаимозависимых параметров, разделов параметров в сообщении справки по использованию и повторяющихся составных аргументов, таких как ([-a=<a> -b=<b> -c=<c>] (-x | -y | -z))... . В расширенных случаях использования приложения могут получать доступ к объектной модели команд picocli с помощью аннотации @Spec и реализовывать обработку настраиваемых параметров для параметров опций, если встроенной логики недостаточно.

Приложения на основе Picocli могут легко интегрироваться с контейнерами внедрения зависимостей. Платформа микросервисов Micronaut имеет встроенную поддержку picocli. Quarkus имеет командный режим с расширением Picocli для облегчения создания приложений CLI на основе picocli с помощью Quarkus. Picocli поставляется с модулем picocli-spring-boot-starter , который включает в себя автоконфигурацию PicocliSpringFactory и Spring Boot для использования внедрения зависимостей Spring в вашем приложении командной строки picocli. В руководстве пользователя есть примеры интеграции с Guice, Spring Boot, Micronaut, Quarkus и с контейнерами, соответствующими спецификации CDI 2.0 (JSR 365).

Релизы

• Все релизы
• Последнее: 4.7.6 Примечания к выпуску
• Старая версия: Picocli 4.0. Примечания к выпуску
• Старая версия: Picocli 3.0. Примечания к выпуску
• Старая версия: Примечания к выпуску Picocli 2.0

Документация

• 4.x Руководство пользователя: https://picocli.info
• 4.x Краткое руководство
• 4.x API Javadoc
• ПРЕДВАРИТЕЛЬНЫЙ ПРОСМОТР: модульная Javadoc для всех артефактов (4.7.6-SNAPSHOT)
• Автодополнение командной строки
• Программный API
• Часто задаваемые вопросы
• Компиляция AOT GraalVM в собственный образ

Старше

• 3.x Руководство пользователя
• 3.x Краткое руководство
• 3.x API Javaдокументация
• 2.x Руководство пользователя
• 2.x API Javadoc
• 1.x Руководство пользователя

Статьи и презентации

Английский

• 6 вещей, которые вы можете сделать с JBang, но не можете с Shell (28 февраля 2022 г.), автор: Ф.Марчиони.
• [ВИДЕО]Kotlin, CLI и StarWars! - Введение в создание приложений CLI с помощью Kotlin с использованием Picocli (05 февраля 2022 г.), Жюльен Ленгран-Ламбер.
• [ВИДЕО]Автозаполнение Java CLI с помощью Picocli (24 января 2022 г.), автор raksrahul.
• Picocli - Легкость аргументов CLI в Java (27 октября 2021 г.), автор agamboa.
• Создание интерфейсов командной строки с помощью Kotlin с использованием picoCLI (23 сентября 2021 г.), Жюльен Ленгран-Ламберт.
• [ВИДЕО]Создавайте приложения Java CLI с помощью picocli (14 сентября 2021 г.) от coder4life.
• ПИКОКЛИ (30 июня 2021 г.), автор Сибрен Боланд.
• Пикокли | Создайте свое первое CLI-приложение Kotlin/JVM с помощью GraalVM (13 февраля 2021 г.), автор manserpatrice.
• [ВИДЕО] Создание плагинов kubectl с помощью Quarkus, picocli, Fabric8io и jbang (22 января 2021 г.), автор: Себастьен Блан.
• [ВИДЕО] J-Fall Virtual 2020: Жюльен Ленгранд — Введение в создание приложений CLI с использованием picoCLI (07.12.2020), Жюльен Ленгран-Ламберт. Это было самое рейтинговое выступление @nljug #jfall virtual 2020! Поздравляю, Жюльен!
• Результаты разбиения на страницы представляют собой приложение командной строки с использованием picoCLI (17 ноября 2020 г.), Жюльен Ленгранд-Ламберт.
• Приложения CLI с собственным образом GraalVM (13 ноября 2020 г.), Олег Шелаев.
• Подкоманды Picocli - Одна программа, много целей (22 сентября 2020 г.), Йонас Андерсен.
• Собственный интерфейс командной строки с Picocli и GraalVM (20 августа 2020 г.), автор jbebar.
• Как создать приложение CLI на Java с использованием jbang и picocli (13 августа 2020 г.), Мэтью Гиллиард.
• Создание парсера GitHub Dependents Dependents с помощью Quarkus и Picocli (31 июля 2020 г.), Марк Нури.
• Создание достойного Java CLI (27 июля 2020 г.), автор: Андреас Текстор.
• [ВИДЕО] (Еще одно очень хорошо подготовленное видео Шимона Степняка) Реализация OAuth 2.0 в приложении командной строки Java с использованием Micronaut, Picocli и GraalVM (23 июля 2020 г.), Шимон Степняк (канал YouTube).
• Micronaut, Picocli и GraalVM (08 июля 2020 г.), автор Шимон Степняк.
• [ВИДЕО] (Очень хорошо подготовленное и информативное, рекомендуется!) Создание приложения командной строки с использованием Java 11, Micronaut, Picocli и GraalVM (01 июля 2020 г.), автор Шимон Степняк (канал YouTube).
• [АУДИО] Scala Valentines #2 (21.06.2020) Подкаст рассказывает о пикокли (с 18:11).
• Как создать инструмент командной строки с использованием Java? (18 июня 2020 г.), Виджай С.Р.Дж.
• Инструменты командной строки с Quarkus и Picocli (08.06.2020), Дмитрий Чабан.
• Руководство Quarkus по командному режиму Quarkus с picocli благодаря расширению picocli Михала Горневского, включенному в Quarkus 1.5 (03.06.2020).
• Собственные изображения с Micronaut и GraalVM (01.06.2020), автор Λ: Olivier Revial.
• Приложения CLI с Micronaut и Picocli (01.06.2020), автор Λ: Olivier Revial.
• Введение в Picocli — анализ командной строки современного Java (19 мая 2020 г.), автор Йонас Андерсен.
• Создание собственного интерфейса командной строки трекера Covid19 с использованием Java, PicoCLI и GraalVM (11 мая 2020 г.), Мохаммед Абуллайт.
• Режим Quarkus Command с Пикокли (27 апреля 2020 г.), автор Дмитрий Чабан.
• Создание инструментов CLI с помощью Scala, Picocli и GraalVM (09 марта 2020 г.), Наоки Такезо.
• Создание собственных интерфейсов командной строки Java с помощью GraalVM, Picocli и Gradle (08 марта 2020 г.), Митч Сеймур
• Создавайте отличные собственные приложения CLI на Java с помощью Graalvm и Picocli (07.03.2020)
• Структурированные объекты Picocli (10 сентября 2019 г.) Филиппа Хансловского объясняет, как использовать поддержку picocli для повторяющихся групп аргументов для добавления или настройки структурированных объектов из командной строки.
• Создайте программу командной строки Java с помощью Picocli|Baeldung (07.05.2019), автор Франсуа Дюпир.
• Бурный тур по журналу picocli JAX Magazine «В центре внимания инструменты Java» (08.04.2019).
• Введение в PicoCLI (10 февраля 2019 г.), автор: devop.
• Руководство Corda CLI UX (User Experience) (2018, автор R3 Limited) дает полезные советы.
• Разработайте инструмент CLI с использованием сценариев groovy (26 октября 2018 г.), автор: Чинтака Динадаса.
• Миграция с Commons CLI на picocli. Вы не пожалеете об этом! :-) (также на: DZone и Java Code Geeks).
• Обновление Groovy 2.5 CliBuilder (также на сайте blogs.apache.org). Состоит из двух частей: Часть 1 (также на сайте: DZone, Java Code Geeks), Часть 2 (также на сайте: DZone, Java Code Geeks).
• Руководство пользователя Micronaut для автономного запуска микросервисов с помощью picocli.
• Интерфейсы командной строки Java (часть 30): наблюдения Дастина Маркса о picocli 2.0.1 (также на: DZone, Java Code Geeks)
• Интерфейсы командной строки Java (часть 10): Picocli Дастина Маркса о picocli 0.9.7 (также на: DZone, Java Code Geeks)
• Picocli 2.0: Groovy Scripts на стероидах (также на: DZone, Java Code Geeks)
• Picocli 2.0: Делайте больше с меньшими затратами (также на: DZone, Java Code Geeks)
• Анонс picocli 1.0 (также на: DZone)

русский

• Выбор основных опций Пикокли на основе основных масел (07.05.2020)
• Интерфейсы командной строки Java: picocli (06 августа 2018 г.): русский перевод Макса Рокатански поста в блоге Дастина Маркса.

испанский

• picocli, рамка для создания приложений для онлайн-команд (2023-09-09) от Darkcizt
• picocli, рамка для создания приложений для онлайн-команд (2023-09-09) от Darkcizt
• Quarkus + Picocli: веб-скейпер для дополнительных зависимых проектов на GitHub (15 августа 2020 г.), автор Марк Нури.
• Quarkus - Введение: пикокли (15 июня 2020 г.), Херардо Арройо.
• [ВИДЕО] Picocli — пример Spring Boot (24 мая 2020 г.), 7-минутное краткое введение Гонсало Х. Мендосы.

Франсэ

• Мобильное приложение: Создание превосходных приложений на основе CLI на Java с Graalvm et Picocli (07.05.2020) Перевод книги «Создание отличных собственных приложений CLI на Java с помощью Graalvm и Picocli», автор bouf1450.
• [ВИДЕО] Приложения на линии управления с Picocli и GraalVM (Н. Петерс) (07.05.2019): 15-минутная презентация Николаса Петерса во время Devoxx FR. Слайды презентации доступны на GitHub.

Португальский

• Desenvolva aplicações CLI nativas em Java com Graalvm e Picocli (28 августа 2020 г.): португальский перевод книги «Создание отличных собственных приложений CLI на Java с помощью Graalvm и Picocli», спасибо Родриго Ап Дж Батисте.
• [ВИДЕО] Quarkus #40: Command Mode com Picocli (23 июня 2020 г.): 13-минутная презентация Винисиуса Ферраза (@viniciusfcf).

日本語

• Приложения CLI с GraalVM Native Image (21 ноября 2020 г.), перевод поста Олега Шелаева, сделанный Logico_jp.
• Плагин Picocli + Kotlin + graalvm-native-image でネイティブツールを作る (24 апреля 2020 г.), сообщение в блоге mike-neck (引きこもり持田 в Twitter).
• pythonのArgumentParserような使い心地！picocliのご紹介 (15 апреля 2020 г.) от @astamuseLab
• Javaのコマンドラインアプリケーション向けのフレームワーク、picocliで遊ぶ (2020-03-07) сообщение в блоге отかずひら.
• Сообщение в блоге KuromojiのCLIコマンドとpicocliとGraalVM (28 февраля 2020 г.) от @johtani.
• GraalVM, PicocliとJavaでときめくネイティブコマンドラインアプリを作ろう (2019-11-23) Слайды для моей презентации на JJUG CCC японской группы пользователей Java Осенняя конференция 2019 года.
• Picocliを使用してJavaコマンドラインプログラムを作成する - 開発者ドキュメント (18.10.2019)
• GraalVM と Picocliで Javaのネイティブコマンドラインアプリを作ろう (06 сентября 2019 г.) Слайды для моей презентации на 【東京】JJUGナイトセミナー: ビール片手にLT大会 9/6（金）
• Picocli＋Spring Boot でコマンドラインアプリケーションを作成してみる (20 июля 2019 г.)かんがるーさんの日記.
• GraalVM の собственный образ を使って Java で爆速 Lambda の夢を見る (2019-05-02) от @kencharos

中文

• Java命令行界面(第10部分):picocli (07.06.2020), перевод dnc8371.
• 如何借助 Graalvm и Picocli 构建 Java 编写的原生 CLI 应用 (26 марта 2020 г.): китайский перевод книги «Создание отличных собственных приложений CLI на Java с помощью Graalvm и Picocli», спасибо 张卫滨.
• 从Commons CLI迁移到Picocli (13 марта 2019 г.): китайский перевод перехода от Commons CLI к picocli, благодаря genghaihua.
• Picocli 2.0: Steroids 上的Groovy脚本
• Пикокли 2.0: 以少求多

Список рассылки

Присоединяйтесь к группе picocli Google, если вы заинтересованы в обсуждении всего, что связано с picocli, и получении объявлений о новых выпусках.

Кредит

Компания Realinfo разработала логотип Пикокли! Большое спасибо!

Обязательства

Этот проект следует семантическому версионированию и придерживается принципа Zero Bugs Commitment .

Принятие

• Пикокли теперь является частью Groovy. Начиная с Groovy 2.5, все инструменты командной строки Groovy основаны на picocli, а picocli является базовым анализатором для Groovy CliBuilder DSL.
• Пикокли теперь является частью Micronaut. Интерфейс командной строки Micronaut был переписан с использованием picocli, и Micronaut имеет специальную поддержку автономного запуска микросервисов с помощью picocli. См. также Руководство Micronaut Picocli.
• Quarkus теперь предлагает командный режим с picocli.
• Picocli теперь является частью JUnit 5. JUnit 5.3 перенес свой ConsoleLauncher с jopt-simple на picocli для поддержки @-файлов (файлов аргументов); это помогает пользователям, которым необходимо указать множество тестов в командной строке и столкнуться с системными ограничениями.
• Debian теперь предлагает пакет libpicocli-java. Спасибо Мирославу Кравецу.
• Picocli используется в автономном JAR-файле/исполняемом файле Intuit Karate.
• Пикокли является частью группы Ballerina. Ballerina использует picocli для всех своих утилит командной строки.
• Picocli используется в автономном JAR-файле или исполняемом файле CheckStyle из Checkstyle 8.15.
• Picocli включен в список проектов бесплатного программного обеспечения с открытым исходным кодом (FOSS) OpenJDK Quality Outreach, которые активно тестируют сборки OpenJDK.
• Picocli используется в инструментах командной строки Apache Hadoop Ozone/HDDS, эталонном интерфейсе командной строки Apache Hive, Apache Ignite TensorFlow и преобразователе модели функций Apache Sling.
• Пикокли указан на StackShare. Пожалуйста, добавьте его в свою стопку и укажите/проголосуйте за причины, по которым вам нравятся пикокли!
• Пикокли используется в Pinterest ktlint.
• Picocli используется в Spring IO nohttp-cli.
• Библиотека MinecraftPicocli облегчает использование пикокли в Minecraft Forge.
• Simple Java Mail теперь предлагает интерфейс командной строки на основе picocli.
• jbang не только использует picocli внутри себя, но также имеет шаблон CLI для создания исходного сценария: используйте jbang --init=cli helloworld.java чтобы сгенерировать образец сценария jbang с поддержкой picocli. См. асцинему.
• Picocli — это основная библиотека, используемая в шаблоне cli-java CookieTemple для создания собственных исполняемых файлов CLI GraalVM на Java. Посмотрите этот предварительный просмотр.
• Picocli упоминается в рекомендациях по интерфейсу командной строки.

Рад видеть, что все больше людей используют пикокли. Должно быть, мы делаем что-то правильно. :-)

Внесите свой вклад, помогая продвигать пикокли

Если вам нравятся пикокли, помогите другим открыть для себя пикокли:

Легко и эффектно?

• Дайте Пикокли звезду на GitHub!
• Проголосуйте за мой ответ StackOverflow на вопрос «Как мне анализировать аргументы командной строки в Java?»
• Проголосуйте за мой ответ Quora на вопрос «Как лучше всего анализировать аргументы командной строки с помощью Java?»

Распространяйте радость! ?

• Напишите в Твиттере о пикокли! Что вам в этом нравится? Как это помогло вам? Чем он отличается от альтернатив?
• Упомяните, что ваш проект использует picocli в документации вашего проекта.
• Покажите, что ваш проект GitHub использует picocli, используя этот значок в README.md:

 [![picocli](https://img.shields.io/badge/picocli-4.7.6-green.svg)](https://github.com/remkop/picocli)

Проповедуйте это! ?

• Возможно, самый эффективный способ показать людям, как пикокли может облегчить их жизнь, — это написать сообщение в блоге или статью или даже снять видео!

Пример

Аннотируйте поля именами и описанием параметров командной строки. При необходимости реализуйте Runnable или Callable , чтобы делегировать обработку ошибок и запросы справки по использованию или версии picocli. Например:

 import picocli . CommandLine ;
import picocli . CommandLine . Option ;
import picocli . CommandLine . Parameters ;
import java . io . File ;

@ Command ( name = "example" , mixinStandardHelpOptions = true , version = "Picocli example 4.0" )
public class Example implements Runnable {

    @ Option ( names = { "-v" , "--verbose" },
      description = "Verbose mode. Helpful for troubleshooting. Multiple -v options increase the verbosity." )
    private boolean [] verbose = new boolean [ 0 ];

    @ Parameters ( arity = "1..*" , paramLabel = "FILE" , description = "File(s) to process." )
    private File [] inputFiles ;

    public void run () {
        if ( verbose . length > 0 ) {
            System . out . println ( inputFiles . length + " files to process..." );
        }
        if ( verbose . length > 1 ) {
            for ( File f : inputFiles ) {
                System . out . println ( f . getAbsolutePath ());
            }
        }
    }

    public static void main ( String [] args ) {
        // By implementing Runnable or Callable, parsing, error handling and handling user
        // requests for usage help or version help can be done with one line of code.

        int exitCode = new CommandLine ( new Example ()). execute ( args );
        System . exit ( exitCode );
    }
}

Реализуйте Runnable или Callable , и ваша команда может быть выполнена в одной строке кода. В приведенном выше примере используется метод CommandLine.execute для анализа командной строки, обработки ошибок, обработки запросов на использование и справку по версии, а также вызова бизнес-логики. Приложения могут вызывать System.exit с возвращенным кодом выхода, чтобы сообщить вызывающей стороне об успехе или неудаче.

$ java Example -v inputFile1 inputFile2

2 files to process...

Метод CommandLine.execute автоматически печатает сообщение со справкой по использованию, если пользователь запросил помощь или если введенные данные оказались недействительными.

Это можно настроить разными способами. Подробности см. в разделе руководства пользователя «Выполнение команд».

Справка по использованию цветов и стилей ANSI

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

Смотрите исходный код.

API справки по использованию

Аннотации Picocli предлагают множество способов настройки справочного сообщения по использованию.

Если аннотаций недостаточно, вы можете использовать API справки picocli для дальнейшей настройки. Например, ваше приложение может генерировать подобную справку с настраиваемым макетом:

Смотрите исходный код.

Скачать

Вы можете добавить picocli в качестве внешней зависимости к вашему проекту или включить его в качестве источника. Смотрите исходный код. Скопируйте и вставьте его в файл с именем CommandLine.java , добавьте в свой проект и наслаждайтесь!

Градл

 implementation 'info.picocli:picocli:4.7.6'

Мавен

 <dependency>
  <groupId>info.picocli</groupId>
  <artifactId>picocli</artifactId>
  <version>4.7.6</version>
</dependency>

Скала СБТ

 libraryDependencies += "info.picocli" % "picocli" % "4.7.6"

Айви

 <dependency org="info.picocli" name="picocli" rev="4.7.6" />

Виноград

 @Grapes (
    @ Grab ( group = ' info.picocli ' , module = ' picocli ' , version = ' 4.7.6 ' )
)

Лейнинген

 [info.picocli/picocli "4.7.6"]

Строитель

 'info.picocli:picocli:jar:4.7.6'

ДжейБанг

 //DEPS info.picocli:picocli:4.7.6