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.
| shell | setup |
|---|---|
| bash | source <(COMPLETE=bash grab) |
| zsh | COMPLETE=zsh grab > ~/.zfunc/_grab, with it in fpath |
| fish | COMPLETE=fish grab | source |
| nu | COMPLETE=nu grab | save grab.nu, then source it |
| elvish | eval (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
handlebefore anything else inmain. 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, orpkgsStaticin 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
- Unknown
Shell - 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
COMPLETEnames a shell