clap

clap (v4) constrói CLIs tipadas com macros derive, autocompletar de shell e uma útil saída --help. É o padrão para ferramentas de linha de comando em Rust.

Receita

[dependencies]
clap = { version = "4", features = ["derive"] }

use clap::Parser;
 
#[derive(Parser, Debug)]
#[command(name = "ship", about = "Helper de lançamento")]
struct Cli {
    /// Ambiente para fazer deploy
    #[arg(short, long, default_value = "staging")]
    env: String,
 
    /// Apenas simulação (dry run)
    #[arg(long)]
    dry_run: bool,
}
 
fn main() {
    let cli = Cli::parse();
    println!("env={} dry_run={}", cli.env, cli.dry_run);
}

Quando usar isso:

• Qualquer binário com flags, subcomandos ou fallbacks de variáveis de ambiente.
• Ferramentas distribuídas para usuários (veja estudos de caso).
• CLIs de desenvolvimento internas substituindo scripts bash.

Exemplo de Trabalho

use clap::{Parser, Subcommand};
 
#[derive(Parser)]
struct Cli {
    #[command(subcommand)]
    cmd: Commands,
}
 
#[derive(Subcommand)]
enum Commands {
    /// Listar usuários
    List { limit: u32 },
    /// Criar usuário
    Create { email: String },
}
 
fn main() {
    let cli = Cli::parse();
    match cli.cmd {
        Commands::List { limit } => println!("limit={limit}"),
        Commands::Create { email } => println!("create {email}"),
    }
}

O que isso demonstra:

• Subcomandos como enums.
• Comentários de documentação se tornam texto de --help.
• Derive mantém a análise separada da lógica de negócios.

Mergulho Profundo

Ambiente e Configuração

#[arg(long, env = "API_URL")]
api_url: String,

Combine com figment ou TOML manual para configuração em camadas.

Códigos de Saída

use clap::Error;
 
// clap lida com --help e uso indevido com código de saída 2.
// Retorne `std::process::ExitCode` de main para erros do aplicativo.

Armadilhas

• Quebrar usuários ao renomear flags - scripts falham silenciosamente. Correção: mantenha aliases #[arg(long, alias = "old")].
• Análise em crates de biblioteca - acopla a API à CLI. Correção: analise em main, passe structs para dentro.
• Falta de default_value - flags obrigatórias irritam o desenvolvimento local. Correção: padrões sensatos mais variáveis de ambiente.
• CLIs grandes e planas - ajuda inadministrável. Correção: subcomandos por domínio.
• Sem display_order - flags relacionadas se espalham. Correção: agrupe com next_help_heading.

Alternativas

FAQs

Relacionados

• Noções básicas de Cargo - alvos de binário
• Noções básicas de implantação - distribuição de CLIs
• Skill de Publicação de Crate
• Melhores Práticas de Crates Essenciais

Versões da Stack: 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+.