clap

Análise de argumentos baseada em derive com validação, geração de ajuda e subcomandos.

Receita

use clap::Parser;
 
#[derive(Parser)]
#[command(name = "greet", version, about = "Cumprimenta alguém")]
struct Args {
    /// Nome para cumprimentar
    name: String,
 
    /// Número de vezes para cumprimentar
    #[arg(short, long, default_value_t = 1)]
    count: u8,
}
 
fn main() {
    let args = Args::parse();
    for _ in 0..args.count {
        println!("Olá, {}!", args.name);
    }
}

Quando usar isso: Qualquer CLI com mais de uma ou duas flags. clap é o padrão de fato no ecossistema Rust.

Exemplo de Trabalho

use clap::{Parser, Subcommand, ValueEnum};
use std::path::PathBuf;
 
#[derive(Parser)]
#[command(name = "backup", version, about = "Faz backup de arquivos")]
struct Cli {
    /// Aumenta a verbosidade (-v, -vv)
    #[arg(short, long, action = clap::ArgAction::Count)]
    verbose: u8,
 
    /// Caminho do arquivo de configuração
    #[arg(short, long, env = "BACKUP_CONFIG")]
    config: Option<PathBuf>,
 
    #[command(subcommand)]
    command: Command,
}
 
#[derive(Subcommand)]
enum Command {
    /// Cria um novo backup
    Create {
        #[arg(value_enum)]
        format: Format,
        source: PathBuf,
    },
    /// Lista backups existentes
    List,
}
 
#[derive(Clone, ValueEnum)]
enum Format {
    Tar,
    Zip,
}
 
fn main() -> anyhow::Result<()> {
    let cli = Cli::parse();
    match cli.command {
        Command::Create { format, source } => {
            println!("fazendo backup de {source:?} como {format:?}");
        }
        Command::List => println!("ainda não há backups"),
    }
    Ok(())
}

O que isso demonstra:

• Macros derive geram --help e validação automaticamente
• env = vincula variáveis de ambiente a flags
• ValueEnum restringe escolhas a um conjunto tipado
• Subcomandos organizam CLIs multi-verbo

Mergulho Profundo

Como Funciona

• #[derive(Parser)] expande para uma implementação parse() em tempo de compilação
• Comentários de documentação em campos se tornam texto de ajuda
• ArgAction::Count implementa padrões de verbosidade -v / -vv
• Erros imprimem dicas de uso e saem com o código 2

Atributos Comuns

Alternativa da API Builder

Use a API builder quando precisar de argumentos dinâmicos em tempo de execução.

use clap::{Arg, Command};
 
let cmd = Command::new("dynamic")
    .arg(Arg::new("file").required(true));
let matches = cmd.get_matches();

Armadilhas

• Recurso derive ausente - Adicione clap = { version = "4", features = ["derive"] }. Correção: Habilite o recurso derive em Cargo.toml.
• Subcomandos de enum precisam de Subcommand derive - Enums simples falham na compilação. Correção: Adicione #[derive(Subcommand)].
• default_value vs default_value_t - Padrões de string precisam de aspas; padrões tipados usam _t. Correção: Combine o atributo com o tipo do seu campo.
• Estruturas aninhadas achatadas - #[command(flatten)] mescla argumentos, mas pode causar colisões de nomes. Correção: Use nomes de campo únicos ou id explícito.
• Versão da ajuda desatualizada - Strings de versão codificadas ficam desatualizadas. Correção: Use #[command(version = env!("CARGO_PKG_VERSION"))].

Alternativas

FAQs

Relacionado

• Fundamentos de CLI - fundamentos
• Configuração e Ambiente - vinculação de variáveis de ambiente
• Completions de Shell e Páginas Man - completions
• Relatório de Erros - erros amigáveis ao usuário

Versões da Pilha: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.