Skip to main content

Crate caress

Crate caress 

Source
Expand description

shell completions and man pages for pound commands

§completions

call handle first thing in main. a shell’s completion script runs the program with COMPLETE set, and handle answers and exits before the program does anything else. completion runs pound’s own parser over the line, so it agrees with what the program will accept, and an arg’s #[pound(complete = ...)] completer sees every other arg already typed.

use pound::Parse;

#[derive(Parse)]
struct Grab {
    url: Vec<String>,
}

caress::handle(Grab::SPEC);
let grab = Grab::parse();

users register completion by sourcing the script the program prints when COMPLETE names a shell and no words follow.

shellsetup
bashsource <(COMPLETE=bash grab)
zshCOMPLETE=zsh grab > ~/.zfunc/_grab, with it in fpath
fishCOMPLETE=fish grab | source
nuCOMPLETE=nu grab | save grab.nu, then source it
elvisheval (COMPLETE=elvish grab | slurp)
powershell$env:COMPLETE='powershell'; grab | Out-String | Invoke-Expression, then Remove-Item Env:COMPLETE

packagers can write the same scripts at build time with Shell::script and install them with the other completion files.

§startup

every TAB runs the program, so its startup is the completion latency. answering takes caress about 10 µs. the rest is the process itself, measured on x86-64 Linux at about 180 µs for exec and the Rust runtime, plus about 350 µs more when the binary is dynamically linked, for the loader to resolve glibc. two things keep it short.

  • call handle before anything else in main. config loading, logging setup, or a lock taken earlier lands on every TAB.
  • link the binary statically when completion latency matters, with RUSTFLAGS='-C target-feature=+crt-static' or a musl target, or pkgsStatic in nix. that took a full bash TAB from 0.9 ms to 0.55 ms.

§man pages

man::pages renders an mdoc page for the command and each subcommand.

Modules§

man
mdoc manual pages, one per command

Structs§

Completions
the answer to one completion request
Line
a command line cut at the cursor
UnknownShell
a shell name caress does not know

Enums§

Fallback
what the shell offers on top of the candidates
Request
what a shell asked the program for
Shell
a shell caress can complete for

Functions§

handle
answer a completion request and exit, when COMPLETE names a shell