picocli

picocli - uma interface de linha de comando minúscula e poderosa

O Picocli pretende ser a maneira mais fácil de usar para criar aplicativos avançados de linha de comando que possam ser executados dentro e fora da JVM. Considerando picocli? Verifique o que usuários satisfeitos dizem sobre o picocli.

Picocli é uma biblioteca e estrutura moderna, escrita em Java, que contém uma API de anotações e uma API programática. Possui ajuda de uso com cores e estilos ANSI, preenchimento automático TAB e subcomandos aninhados. Em um único arquivo, para que você possa incluí-lo no formato fonte . Isso permite que os usuários executem aplicativos baseados em picocli sem exigir o picocli como dependência externa.

Os aplicativos baseados em Picocli podem ser compilados antecipadamente em uma imagem nativa, com tempo de inicialização extremamente rápido e menores requisitos de memória, que podem ser distribuídos como um único arquivo executável. Picocli vem com um processador de anotação que habilita automaticamente seu jar para Graal durante a compilação.

Os aplicativos Picocli podem ser muito compactos, sem código padrão: seu comando (ou subcomando) pode ser executado com uma única linha de código. Simplesmente implemente Runnable ou Callable ou coloque a lógica de negócios do seu comando em um método anotado @Command .

O Picocli facilita seguir as diretrizes da interface de linha de comando.

Como funciona: anote sua classe e o picocli a inicializa a partir dos argumentos da linha de comando, convertendo a entrada em dados fortemente digitados. Suporta subcomandos do tipo git (e subcomandos aninhados), qualquer estilo de prefixo de opção, opções curtas agrupadas no estilo POSIX, conversores de tipo personalizados, opções de senha e muito mais.

Picocli distingue entre opções nomeadas e parâmetros posicionais e permite que ambos sejam fortemente digitados. Campos com valores múltiplos podem especificar um número exato de parâmetros ou um intervalo (por exemplo, 0..* , 1..2 ). Suporta opções de mapa como -Dkey1=val1 -Dkey2=val2 , onde a chave e o valor podem ser digitados com força. O rastreamento do analisador facilita a solução de problemas. Arquivos de argumentos de linha de comando (@-files) permitem que os aplicativos manipulem linhas de comando muito longas.

Gera ajuda de uso e ajuda de versão refinadas e facilmente personalizadas, usando cores ANSI sempre que possível. Requer no mínimo Java 5, mas foi projetado para facilitar o uso de lambdas Java 8. Testado em todas as versões Java entre 5 e 18-ea (inclusive).

Os aplicativos de linha de comando baseados em Picocli podem ter preenchimento automático TAB, mostrando interativamente aos usuários quais opções e subcomandos estão disponíveis. Quando uma opção tem completionCandidates ou tem um tipo enum , o preenchimento automático também pode sugerir valores de opção. Picocli pode gerar scripts de conclusão para bash e zsh e oferece módulos picocli-shell-jline2 e picocli-shell-jline3 com implementações JLine Completer para construir aplicativos shell interativos.

Os recursos exclusivos do picocli incluem suporte para opções negáveis, valores citados avançados e grupos de argumentos. Grupos de argumentos podem ser usados ​​para criar opções mutuamente exclusivas, opções mutuamente dependentes, seções de opções na mensagem de ajuda de uso e argumentos compostos repetidos como ([-a=<a> -b=<b> -c=<c>] (-x | -y | -z))... . Para casos de uso avançados, os aplicativos podem acessar o modelo de objeto de comando picocli com a anotação @Spec e implementar o processamento de parâmetros personalizados para parâmetros de opção se a lógica integrada for insuficiente.

Os aplicativos baseados em Picocli podem ser facilmente integrados aos contêineres de injeção de dependência. A estrutura de microsserviços Micronaut possui suporte integrado para picocli. Quarkus possui um modo de comando com extensão Picocli para facilitar a criação de aplicativos CLI baseados em picocli com Quarkus. O Picocli vem com um módulo picocli-spring-boot-starter que inclui uma configuração automática PicocliSpringFactory e Spring Boot para usar injeção de dependência Spring em seu aplicativo de linha de comando picocli. O manual do usuário traz exemplos de integração com Guice, Spring Boot, Micronaut, Quarkus e com containers que atendem à especificação CDI 2.0 (JSR 365).

Lançamentos

• Todos os lançamentos
• Mais recente: Notas de versão 4.7.6
• Mais antigo: Notas de versão do Picocli 4.0
• Mais antigo: Notas de versão do Picocli 3.0
• Mais antigo: Notas de versão do Picocli 2.0

Documentação

• 4.x Manual do usuário: https://picocli.info
• 4.x Guia rápido
• API Javadoc 4.x
• PREVIEW: Javadoc modular para todos os artefatos (4.7.6-SNAPSHOT)
• Preenchimento automático de linha de comando
• API programática
• Perguntas frequentes
• Compilação GraalVM AOT para imagem nativa

Mais velho

• 3.x Manual do usuário
• 3.x Guia rápido
• Javadoc da API 3.x
• 2.x Manual do usuário
• API Javadoc 2.x
• 1.x Manual do usuário

Artigos e Apresentações

Inglês

• 6 coisas que você pode fazer com JBang, mas não pode com Shell (28/02/2022) por F.Marchioni.
• [VÍDEO]Kotlin, CLIs e StarWars! - Uma introdução à criação de aplicativos CLI com Kotlin usando Picocli (2022-02-05) por Julien Lengrand-Lambert.
• [VÍDEO] Autocomplete Java CLI usando Picocli (2022-01-24) por raksrahul.
• Picocli – Facilidade para argumentos CLI em Java (2021-10-27) por agamboa.
• Construindo interfaces de linha de comando com Kotlin usando picoCLI (23/09/2021) por Julien Lengrand-Lambert.
• [VÍDEO] Crie aplicativos Java CLI com picocli (14/09/2021) por coder4life.
• PICOCLI (30/06/2021) de Sybren Boland.
• Picocl | Crie seu primeiro aplicativo Kotlin /JVM CLI com GraalVM (13/02/2021) por manserpatrice.
• [VÍDEO] Construindo plug-ins kubectl com Quarkus, picocli, fabric8io e jbang (22/01/2021) por Sébastien Blanc.
• [VÍDEO] J-Fall Virtual 2020: Julien Lengrand - Uma introdução à criação de aplicativos CLI usando picoCLI (2020-12-07) por Julien Lengrand-Lambert. Esta foi a palestra mais bem avaliada do @nljug #jfall virtual 2020! Parabéns, Juliano!
• Paginar resulta em um aplicativo de linha de comando usando picoCLI (2020-11-17) de Julien Lengrand-Lambert.
• Aplicativos CLI com GraalVM Native Image (2020-11-13) por Oleg Šelajev.
• Subcomandos Picocli - Um programa, muitos propósitos (22/09/2020) por Jonas Andersen.
• CLI nativo com Picocli e GraalVM (20/08/2020) por jbebar.
• Como construir um aplicativo CLI em Java usando jbang e picocli (13/08/2020) por Matthew Gilliard.
• Construindo um raspador de dependentes do GitHub com Quarkus e Picocli (31/07/2020) por Marc Nuri.
• Construindo um Java CLI decente (27/07/2020) por Andreas Textor.
• [VÍDEO] (Outro vídeo muito bem produzido por Szymon Stepniak) Implementando OAuth 2.0 em um aplicativo de linha de comando Java usando Micronaut, Picocli e GraalVM (23/07/2020) por Szymon Stepniak (canal do YouTube).
• Micronauta, Picocli e GraalVM (08/07/2020) por Szymon Stepniak.
• [VÍDEO] (Extremamente bem produzido e informativo, recomendado!) Construindo aplicativo de linha de comando com Java 11, Micronaut, Picocli e GraalVM (01/07/2020) por Szymon Stepniak (canal do YouTube).
• [ÁUDIO] Scala Valentines #2 (2020-06-21) Podcast fala sobre picocli (a partir das 18h11).
• Como criar uma ferramenta de linha de comando usando Java? (18/06/2020) por Vijay SRJ.
• Ferramentas de linha de comando com Quarkus e Picocli (08/06/2020) por Dmytro Chaban.
• Guia Quarkus para o modo de comando Quarkus com picocli, graças a uma extensão picocli de Michał Górniewski incluída no Quarkus 1.5 (03/06/2020).
• Imagens nativas com Micronaut e GraalVM (01/06/2020) por Λ: Olivier Revial.
• Aplicativos CLI com Micronaut e Picocli (01/06/2020) por Λ: Olivier Revial.
• Introdução ao Picocli - Análise de linha de comando Java moderna (19/05/2020) por Jonas Andersen.
• Construindo CLI Native Covid19 Tracker usando Java, PicoCLI e GraalVM (11/05/2020) por Mohammed Aboullaite.
• Modo Quarkus Command com Picocli (2020-04-27) por Dmytro Chaban.
• Criando ferramentas CLI com Scala, Picocli e GraalVM (09/03/2020) por Naoki Takezoe
• Construindo CLIs Java nativos com GraalVM, Picocli e Gradle (08/03/2020) por Mitch Seymour
• Crie ótimos aplicativos CLI nativos em Java com Graalvm e Picocli (07/03/2020)
• Picocli Structured Objects (10/09/2019) de Philipp Hanslovsky explica como usar o suporte do picocli para repetir grupos de argumentos para adicionar ou configurar objetos estruturados a partir da linha de comando.
• Crie um programa de linha de comando Java com Picocli | Baeldung (07/05/2019) por François Dupire.
• Um rápido tour pela revista picocli JAX "Colocando destaque nas ferramentas Java" (08/04/2019).
• Uma introdução ao PicoCLI (10/02/2019) por devop.
• Guia Corda CLI UX (User Experience) (2018 da R3 Limited) fornece conselhos úteis.
• Desenvolva uma ferramenta CLI usando scripts interessantes (26/10/2018) por Chinthaka Dinadasa.
• Migrando do Commons CLI para o picocli. Você não vai se arrepender! :-) (também em: DZone e Java Code Geeks).
• Renovação do Groovy 2.5 CliBuilder (também em blogs.apache.org). Em duas partes: Parte 1 (também em: DZone, Java Code Geeks), Parte 2 (também em: DZone, Java Code Geeks).
• Manual do usuário do Micronaut para executar microsserviços de forma independente com picocli.
• Interfaces de linha de comando Java (Parte 30): Observações de Dustin Marx sobre o picocli 2.0.1 (também em: DZone, Java Code Geeks)
• Interfaces de linha de comando Java (Parte 10): Picocli de Dustin Marx sobre picocli 0.9.7 (também em: DZone, Java Code Geeks)
• Picocli 2.0: Groovy Scripts on Steroids (também em: DZone, Java Code Geeks)
• Picocli 2.0: Faça mais com menos (também em: DZone, Java Code Geeks)
• Anunciando o picocli 1.0 (também em: DZone)

russo

• Выбор необходимых опций Picocli em sua nova variante (2020-05-07)
• Интерфейсы командной строки Java: picocli (06/08/2018): tradução russa por MaxRokatansky da postagem no blog de Dustin Marx.

Espanhol

• picocli, uma estrutura poderosa para a criação de aplicativos de linha de comando (2023-09-09) por Darkcrizt
• picocli, uma estrutura poderosa para a criação de aplicativos de linha de comando (2023-09-09) por Darkcrizt
• Quarkus + Picocli: Web scaper para extraer projetos dependentes no GitHub (15/08/2020) por Marc Nuri.
• Quarkus - Introdução: picocli (2020-06-15) de Gerardo Arroyo.
• [VÍDEO] Picocli - Exemplo de Spring Boot (2020-05-24) Introdução rápida de 7 minutos por Gonzalo H. Mendoza.

Francês

• Aplicativo móvel: Crie aplicativos excelentes CLI nativos em Java com Graalvm e Picocli (2020-05-07) Tradução de Construa ótimos aplicativos CLI nativos em Java com Graalvm e Picocli por bouf1450.
• [VÍDEO] Des aplicações on-line de comando com Picocli et GraalVM (N. Peters) (07-05-2019): apresentação de 15 minutos de Nicolas Peters durante Devoxx FR. Os slides da apresentação estão disponíveis no GitHub.

Português

• Desenvolva aplicações CLI nativas em Java com Graalvm e Picocli (2020-08-28): Tradução para o português de Build Great Native CLI Apps in Java with Graalvm and Picocli, graças a Rodrigo Ap G Batista.
• [VÍDEO] Quarkus #40: Command Mode com Picocli (23/06/2020): apresentação de 13 minutos de Vinícius Ferraz (@viniciusfcf).

日本語

• Aplicativos CLI com GraalVM Native Image (2020-11-21) tradução por Logico_jp da postagem de Oleg Šelajev.
• Picocli + Kotlin + graalvm-native-image plugin でネイティブツールを作る (2020-04-24) postagem no blog por mike-neck (引きこもり持田 no Twitter).
• pythonのArgumentParserような使い心地！picocliのご紹介 (2020-04-15) por @astamuseLab
• Javaのコマンドラインアプリケーション向けのフレームワーク、picocliで遊ぶ (2020-03-07) postagem no blog porかずひら.
• KuromojiのCLIコマンドとpicocliとGraalVM (28/02/2020) postagem no blog de @johtani.
• GraalVM, PicocliとJavaでときめくネイティブコマンドラインアプリを作ろう (2019-11-23) Slides para minha apresentação no JJUG CCC do Japan Java User Group Conferência de outono de 2019.
• Picocliを使用してJavaコマンドラインプログラムを作成する - 開発者ドキュメント (2019-10-18)
• GraalVM と Picocliで Javaのネイティブコマンドラインアプリを作ろう (2019-09-06) Slides para minha apresentação relâmpago em 【東京】JJUGナイトセミナー: ビール片手にLT大会 9/6（金）
• Picocli＋Spring Boot でコマンドラインアプリケーションを作成してみる (2019-07-20) porかんがるーさんの日記.
• GraalVM の imagem nativa を使って Java で爆速 Lambda の夢を見る (02/05/2019) por @kencharos

中文

• Java命令行界面（第10部分）：picocli (2020-06-07) tradução por dnc8371.
• 如何借助 Graalvm 和 Picocli 构建 Java 编写的原生 CLI 应用 (2020-03-26): Tradução chinesa de Construa ótimos aplicativos CLI nativos em Java com Graalvm e Picocli, graças a 张卫滨.
• 从Commons CLI迁移到Picocli (13/03/2019): Tradução chinesa de Migrando do Commons CLI para picocli, graças a genghaihua.
• Picocli 2.0: Esteróides 上的Groovy脚本
• Picocli 2.0: 以少求多

Lista de discussão

Junte-se ao grupo picocli do Google se estiver interessado em discutir qualquer assunto relacionado ao picocli e receber anúncios sobre novos lançamentos.

Crédito

Reallinfo desenhou o logotipo do picocli! Muito obrigado!

Compromissos

Este projeto segue versionamento semântico e segue o Compromisso Zero Bugs .

Adoção

• Picocli agora faz parte do Groovy. A partir do Groovy 2.5, todas as ferramentas de linha de comando do Groovy são baseadas em picocli, e picocli é o analisador subjacente para o CliBuilder DSL do Groovy.
• Picocli agora faz parte do Micronaut. O Micronaut CLI foi reescrito com picocli, e o Micronaut tem suporte dedicado para executar microsserviços de forma independente com picocli. Veja também Guia do Micronauta Picocli.
• Quarkus agora oferece modo Command com picocli.
• Picocli agora faz parte do JUnit 5. O JUnit 5.3 migrou seu ConsoleLauncher de jopt-simple para picocli para suportar @-files (arquivos de argumento); isso ajuda os usuários que precisam especificar muitos testes na linha de comando e enfrentar limitações do sistema.
• O Debian agora oferece um pacote libpicocli-java. Obrigado a Miroslav Kravec.
• Picocli é usado no JAR/executável independente do Intuit Karate.
• Picocli faz parte da Bailarina. Ballerina usa picocli para todos os seus utilitários de linha de comando.
• Picocli é usado no JAR/executável autônomo CheckStyle do Checkstyle 8.15.
• Picocli está incluído na lista OpenJDK Quality Outreach de projetos de software de código aberto gratuito (FOSS) que testam ativamente em compilações do OpenJDK.
• Picocli é usado nas ferramentas de linha de comando Apache Hadoop Ozone/HDDS, na CLI de benchmark Apache Hive, Apache Ignite TensorFlow e Apache Sling Feature Model Converter.
• Picocli está listado no StackShare. Por favor, adicione-o à sua pilha e adicione/vote pelos motivos pelos quais você gosta do picocli!
• Picocli é usado no Pinterest ktlint.
• Picocli é usado no Spring IO nohttp-cli.
• A biblioteca MinecraftPiccocli facilita o uso de picocli no Minecraft Forge.
• Simple Java Mail agora oferece uma CLI baseada em picocli.
• jbang não apenas usa picocli internamente, mas também possui um modelo CLI para gerar um script inicial: use jbang --init=cli helloworld.java para gerar um exemplo de script jbang habilitado para picocli. Veja asciinema.
• Picocli é a biblioteca principal usada no modelo cli-java CookieTemple para construir executáveis ​​CLI nativos do GraalVM em Java. Veja esta prévia.
• Picocli é mencionado nas Diretrizes da interface de linha de comando.

Fico feliz em ver que mais pessoas estão usando o picocli. Devemos estar fazendo algo certo. :-)

Contribua ajudando a promover o picocli

Se você gosta do picocli, ajude outras pessoas a descobrir o picocli:

Fácil e impactante?

• Dê uma estrela ao picocli no GitHub!
• Vote positivamente em minha resposta StackOverflow para "Como analiso argumentos de linha de comando em Java?"
• Vote positivamente na minha resposta do Quora para "Qual é a melhor maneira de analisar argumentos de linha de comando com Java?"

Espalhe a alegria! ?

• Tweet sobre picocli! O que você gosta nisso? Como isso ajudou você? Como é diferente das alternativas?
• Mencione que seu projeto usa picocli na documentação do seu projeto.
• Mostre que seu projeto GitHub usa picocli, com este emblema em seu README.md:

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

Pregue! ?

• Talvez a maneira mais impactante de mostrar às pessoas como o picocli pode facilitar suas vidas seja escrever uma postagem no blog ou artigo, ou até mesmo fazer um vídeo!

Exemplo

Anote os campos com os nomes e a descrição dos parâmetros da linha de comando. Opcionalmente, implemente Runnable ou Callable para delegar tratamento de erros e solicitações de ajuda de uso ou ajuda de versão ao picocli. Por exemplo:

 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 );
    }
}

Implemente Runnable ou Callable e seu comando poderá ser executado em uma linha de código. O exemplo acima usa o método CommandLine.execute para analisar a linha de comando, tratar erros, tratar solicitações de uso e ajuda de versão e invocar a lógica de negócios. Os aplicativos podem chamar System.exit com o código de saída retornado para sinalizar sucesso ou falha ao chamador.

$ java Example -v inputFile1 inputFile2

2 files to process...

O método CommandLine.execute imprime automaticamente a mensagem de ajuda de uso se o usuário solicitar ajuda ou quando a entrada for inválida.

Isso pode ser personalizado de várias maneiras. Consulte a seção do manual do usuário em Execução de comandos para obter detalhes.

Ajuda de uso com cores e estilos ANSI

Cores, estilos, cabeçalhos, rodapés e títulos de seção são facilmente personalizados com anotações. Por exemplo:

Veja o código fonte.

API de ajuda de uso

As anotações do Picocli oferecem muitas maneiras de personalizar a mensagem de ajuda de uso.

Se as anotações não forem suficientes, você pode usar a API de Ajuda do picocli para personalizar ainda mais. Por exemplo, seu aplicativo pode gerar ajuda como esta com um layout personalizado:

Veja o código fonte.

Download

Você pode adicionar picocli como uma dependência externa ao seu projeto ou incluí-lo como fonte. Veja o código fonte. Copie e cole em um arquivo chamado CommandLine.java , adicione-o ao seu projeto e divirta-se!

Gradle

 implementation 'info.picocli:picocli:4.7.6'

Maven

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

Escala SBT

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

Hera

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

Uva

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

Leiningen

 [info.picocli/picocli "4.7.6"]

Construtor

 'info.picocli:picocli:jar:4.7.6'

JBang

 //DEPS info.picocli:picocli:4.7.6