Como criar facilmente uma CLI em ferrugem usando palmas e clap_mangen

Defina seu CLI uma vez com o blap derivar, execute-o em tempo de execução e as páginas do Man-Generate automaticamente no momento da construção com CLAP_MANGEN, tudo da mesma fonte de verdade. Para o exemplo completo de trabalho, consulte: O que é uma “página do homem” e por que se importar? “Man” significa manual. Em sistemas semelhantes ao Unix, o MAN abre a documentação em seu terminal (por exemplo, homem LS). Páginas de remessa com sua CLI significa: Ajuda interna Offline: os usuários podem ler documentos sem internet. UX consistente: MyCli, MyCli -Help e Man MyCli contam a mesma história. Easy Descoberta: Man -K MyCli (Apropos) permite que os usuários encontrem comandos relacionados. Configuração rápida Instale as dependências primeiro, depois você está pronto para acompanhar: Cargo Adicionar palmas -Rometas Derivar carga Adicionar palmas -BUILD -Romeiras Derive Cargo Adicione CLAP_MANGEN -Build Digite Modo de tela cheia Modo de tela cheia Isso produz uma carga.toml como:

[package]
name = “myCli” versão = “0.1.0” edição = “2021” build = “build.rs”

[dependencies]
clap = {versão = “4”, recursos = [“derive”] }

[build-dependencies]
clap = {versão = “4”, recursos = [“derive”] } clap_mangen = “0.2” Digite o modo de saída de tela cheia de tela cheia por que essa é uma fonte única de verdade: os tipos de derivamento acionam a análise e a documentação do tempo de execução. Sem documentos obsoletos: as páginas do homem se regeneram na construção quando a CLI muda. Ótimo para embalagem: o destino do navio/man/*. 1 ou instale -o em/usr/share/man. Trabalha com subcomando aninhados fora da caixa. A definição da CLI (deriva) definimos toda a CLI sob src/cli.rs usando derivar clap. Tanto o script binário quanto o Build reutilizam esses tipos. // em src/cli.rs usa clap :: {command, commandfactory, parser}; // Descrição mais longa usada para a seção Página do Man de nível superior. const LONG_ABOUT: &str = r#” mycli is a tiny example CLI demonstrating auto-generated man pages with clap and clap_mangen. It showcases: – Nested subcommands (eg, `config get`, `config set`) – Rich help/usage text derived from a single source of truth – Build-time man page generation to `target/man/` Top-level commands: – config: manage Valores de configuração (get/set) – servidor: execute um servidor de demonstração (addr/porta/verbosity) – remoto: adicione ou remova um controle remoto pelo nome “#; /// MyCli-Um pequeno exemplo de CLI usado para demonstrar páginas de homem gerado automaticamente. #[derive(Debug, Parser)]
#[command(
name = “mycli”,
about = “Example CLI with nested subcommands and man page generation”,
long_about = LONG_ABOUT,
version
)]
pub struct cli {/// Subcomando de Top-Level para executar #[command(subcommand)]
Comando do Pub: Comandos,} Digite o modo de tela cheia de saída de tela cheia Modo de tela Mínimo de tempo de execução: main.rs no tempo de execução, você analisa uma vez e envia para o subcomando selecionado. Aqui está a essência do src/main.rs: use clap :: parser; mod cli; fn main () {let opts = cli :: CLI :: parse (); Match Opt.Command {CLI :: Commands :: Server (s) => {println! (“Servidor Iniciar em {}: {} (verbosidade: {})”, s.addr, s.port, s.verbose); } cli :: comandos :: remote (r) => {if r.remove {println! (“remoto removido: {}”, r.Name); } else se deixe alguns (url) = r.url {println! (“Remote adicionado: {} -> {}”, r.Name, url); } else {println! (“Informações remotas solicitadas: {}”, r.Name); }} cli :: comandos :: config (cfg) => corresponde a cfg.action {cli :: configaction :: get (g) => println! (“config get {} (formato: {:?})”, g.key, g.format), cli :: configaction:}) {}) “, S.Key, S.Value, S.Global),},}} Digite o modo de tela cheia de tela cheia compartilhamento de CLI com comput.rs Build.rs Compila como uma caixa separada, por isso incluímos o mesmo SRC/CLI.RS (e garantir [build-dependencies] com recursos =[“derive”]). // em build.rs mod cli {inclua! (concat! (Env! (“cargo_manifest_dir”), “/src/cli.rs”)); } deixe mut cmd = <:cli as clap::commandfactory>::comando(); Digite o modo de tela cheia Sair do modo de tela cheia, gerando páginas Man Pages recursivamente CLAP_MANGEN pode gerar páginas MAN para o comando root e todos os subcomandos aninhados com uma única chamada: let out_dir = manifest_dir.join (“Target”). Join (“Man”); std :: fs :: create_dir_all (& out_dir)?; Deixe mut cmd = <:cli as clap::commandfactory>::comando(); clap_mangen :: generate_to (& mut cmd, & out_dir)?; // grava mycli.1, mycli-config.1, mycli-config-get.1, etc. Digite o modo de saída do modo de tela cheia, o script de criação imprime uma carga: aviso mostrando onde os arquivos foram gravados. Como as peças se encaixam na fonte única de verdade: SRC/CLI.RS contém todos os tipos de derivados de CLI. Tanto o tempo de execução quanto o script de compilação incluem esse arquivo, para que o texto e a estrutura ajudem nunca desvie. 1) Parsing de tempo de execução (src/main.rs)- cli :: parse () cria valores da linha de comando. 2) DOCs de tempo de construção (build.rs)- inclui src/cli.rs, para que ele tenha o mesmo layout de comando.- Calls clap_mangen :: generate_to no comando root.- Recursivamente escreve páginas para a raiz e cada subcomando no alvo/homem/. 3) Benefícios- Nenhuma especificação duplicada para ajuda vs. doces. Experimente a construção localmente de carga LS Target/Man Man -l Target/Man/MyCli.1 # ROOT Command Man -l Target/Man/MyCli -Config -Get.1 # Subcomando aninhado Digite Modo FullScreen Sair A geração pesada pode retardar os ciclos iterativos. Para pipelines de documentos maiores, considere um XTask de carga e execute -o sob demanda ou no IC. Alguns hosts do DOC (por exemplo, docs.rs) restringem ou ignoram os efeitos colaterais do script. Mantenha -o leve. Se você precisar de nomes/seções personalizados, use CLAP_MANGEN :: Man :: New (CMD) .render (& mut writer) e recorrente a si mesmo. Próximos etapas Os instaladores do pacote podem colocar as páginas em/usr/share/man/man1/. As fórmulas homebrew podem instalar o destino/man/*. 1 durante a instalação da fermentação. Explore documentos: palmas em docs.rs e clap_mangen no docs.rs para opções avançadas.

Fonte