Clap para Rust: guia completo com exemplos

O que é Clap e para que serve?

\n\n

Clap (Command Line Argument Parser) é uma biblioteca poderosa, rápida e conveniente para análise de argumentos de linha de comando na linguagem Rust. Ela permite que desenvolvedores definam facilmente quais argumentos, flags, opções e subcomandos seu aplicativo deve aceitar, gerando automaticamente ajuda (--help), verificando tipos de dados e tratando erros de entrada.

\n\n

Para que serve o Clap? Em vez de analisar manualmente std::env::args() e escrever dezenas de linhas de código para validação, o Clap faz todo o trabalho para você. Você simplesmente descreve a estrutura do seu CLI, e a biblioteca cuida da análise, geração de mensagens de erro e formatação de dicas. O Clap suporta:

\n

\n
• Argumentos posicionais (obrigatórios e opcionais).
\n
• Opções nomeadas (flags) com nomes curtos e longos.
\n
• Subcomandos (como em git commit).
\n
• Autocompletar para shells (bash, zsh, fish, PowerShell).
\n
• Validação de valores, valores padrão, valores múltiplos e muito mais.
\n

\n\n

Clap é o padrão de facto para criar aplicações CLI no ecossistema Rust. É usado em projetos conhecidos como cargo, ripgrep (rg), fd e muitos outros.

\n\n

Instalação

\n\n

Clap é uma biblioteca para Rust, portanto é instalada através do gerenciador de pacotes cargo. Adicione a seguinte linha ao seu arquivo Cargo.toml:

\n\n

[dependencies]\nclap = { version = "4.5", features = ["derive"] }

\n\n

Recomendamos o uso de derive-macros (recurso derive), pois é a forma mais moderna e conveniente de trabalhar com Clap. Se você precisar apenas da funcionalidade básica sem derive, pode escrever:

\n\n

[dependencies]\nclap = "4.5"

\n\n

Após adicionar a dependência, execute o comando cargo build para baixar e compilar a biblioteca.

\n\n

Início rápido com exemplo de código

\n\n

Vamos criar um aplicativo simples que aceita um nome de usuário e uma flag opcional de saudação. Crie um novo projeto:

\n\n

cargo new hello_clap\ncd hello_clap

\n\n

Substitua o conteúdo de src/main.rs pelo seguinte código:

\n\n

use clap::Parser;\n\n/// Programa simples para saudação\n#[derive(Parser)]\n#[command(name = "greeter")]\n#[command(about = "Sauda o usuário", long_about = None)]\nstruct Cli {\n    /// Nome do usuário\n    name: String,\n\n    /// Número de vezes para repetir a saudação\n    #[arg(short = 'c', long = "count", default_value_t = 1)]\n    count: u8,\n}\n\nfn main() {\n    let cli = Cli::parse();\n\n    for _ in 0..cli.count {\n        println!("Olá, {}!", cli.name);\n    }\n}

\n\n

Agora execute o programa:

\n\n

cargo run -- Mundo\n# Saída: Olá, Mundo!\n\ncargo run -- Mundo -c 3\n# Saída:\n# Olá, Mundo!\n# Olá, Mundo!\n# Olá, Mundo!\n\ncargo run -- --help\n# Saída da ajuda

\n\n

Como você pode ver, o Clap gerou automaticamente a ajuda, processou os argumentos e realizou a verificação de tipos (se você passar -c com um valor não numérico, ocorrerá um erro).

\n\n

Principais métodos e funções do Clap

\n\n

Vamos analisar os principais métodos e atributos que o Clap oferece. Usaremos a abordagem com derive-macros, pois é a mais popular.

\n\n

1. #[derive(Parser)]

\n

O que faz: Transforma sua estrutura em um analisador de linha de comando. Este é o macro principal com o qual tudo começa. Ele implementa automaticamente a trait Parser para sua estrutura.

\n

Parâmetros: Atributos da estrutura (#[command(...)]) e dos campos (#[arg(...)]).

\n

Exemplo:

\n

use clap::Parser;\n\n#[derive(Parser)]\n#[command(name = "myapp")]\nstruct C