// ZSH-CPAN-COMPLETION — LIVE CPAN MODULE COMPLETION FOR cpan / cpanm

Install

# Zinit
zinit ice lucid nocompile
zinit load MenkeTechnologies/zsh-cpan-completion

# Oh My Zsh
git clone https://github.com/MenkeTechnologies/zsh-cpan-completion \
    "$HOME/.oh-my-zsh/custom/plugins/zsh-cpan-completion"
# then: plugins+=(zsh-cpan-completion)

# Manual
git clone https://github.com/MenkeTechnologies/zsh-cpan-completion
source zsh-cpan-completion/zsh-cpan-completion.plugin.zsh

What it does

Two zsh #compdef completion files — src/_cpan (for the cpan CPAN.pm client) and src/_cpanm (for cpanm / App::cpanminus) — plus a plugin entrypoint that defines the shared module-search helpers and prepends src/ to fpath. Both completion files declare their full flag table via _arguments -s, then fall through to a single shared dispatcher, __cpan_modules, that runs perl -MCPAN -e 'CPAN::Shell->m("/$PREFIX/")' at completion time to resolve module names from the live CPAN index. Results render through zsh's _describe and are cached per-prefix via _retrieve_cache / _store_cache, so the Perl spawn happens at most once per prefix per shell session.

Configuration

One environment variable. It is exported with a default of 2 by the plugin entrypoint (export ZPWR_CPAN_MIN_PREFIX=2); set it in ~/.zshrc before the plugin loads to override.

# ~/.zshrc — require 3 chars before hitting the network
export ZPWR_CPAN_MIN_PREFIX=3
zinit load MenkeTechnologies/zsh-cpan-completion

How completion fires

For both cpan and cpanm, when you TAB in a positional (module-name) argument:

1. The completion file checks $#PREFIX >= $ZPWR_CPAN_MIN_PREFIX. If the typed prefix is too short, it skips the network and offers only tarball files (.tar.gz, .tgz, .tar.bz2, .zip) plus directories via _files -/ -g "*.(tar.gz|tgz|tar.bz2|zip)(-.)".
2. If the prefix is long enough, it calls __cpan_modules $PREFIX, which spawns perl -MCPAN -e 'CPAN::Shell->m("/$PREFIX/")' — the CPAN.pm shell's m (module) command with a regex anchored on your prefix.
3. The Perl output is split into lines and matched against two shapes: single-module verbose output (a Module id = NAME line paired with a CPAN_FILE TARBALL line, handled by __cpan_single_module) and the multi-module short listing (Module < NAME TARBALL, handled by __cpan_multiple_modules). Colons in module names are backslash-escaped so _describe doesn't treat them as value/description separators.
4. Each entry is built as name:tarball and passed to _describe -t cpan-module 'CPAN modules', which renders the completion menu with the tarball shown as the description.
5. For the multi-module path, the parsed list is stored with _store_cache cpan_${PREFIX}_cache; subsequent TABs on the same prefix are served from _retrieve_cache with no Perl spawn.

cpan flag reference

Every short flag the cpan(1) client accepts, taken from src/_cpan. Flags whose description is a bracketed [ module ... ] / [ author ... ] placeholder take list arguments and fall through to module-name completion.

cpanm flag reference

Long+short flag pairs from src/_cpanm (cpanminus completion, supported version 1.4000). Pairs are declared with zsh brace expansion ({--long,-s}); several carry mutex groups so conflicting flags drop out of the menu.

Examples

cpan install Mo<TAB>        # live remote completion of modules matching /Mo/
cpanm install DBI<TAB>      # same shared dispatcher via cpanm
cpan -<TAB>                  # short-flag menu: -a -i -l -u -p ...
cpanm --<TAB>               # long-flag menu: --install --force --scandeps ...
cpanm --format <TAB>        # literal set: tree json yaml dists
cpanm --mirror <TAB>        # _urls completion for the mirror base URL
cpan install ./Some-1.0.tar.gz  # tarball file completion (.tar.gz/.tgz/.tar.bz2/.zip)

Troubleshooting

Sibling plugins

Part of the MenkeTechnologies zsh plugin family — the MenkeTechnologiesMeta umbrella:

• zsh-better-npm-completion — cache-aware npm install completion
• zsh-cargo-completion — live cargo add / cargo install completion
• zsh-dotnet-completion — dotnet CLI completion
• zsh-expand — spacebar expansion (11,683 tests)
• zsh-gem-completion — ruby gem install remote completion
• zsh-git-acp — 159 git aliases + add/commit/push keybindings
• zsh-git-repo-cache — index every git repo on disk
• zsh-learn — MySQL-backed learning collection / quiz
• zsh-more-completions — 33,175-file mega completion corpus
• zsh-nginx — nginx commands + service-wrapper aliases
• zsh-pip-description-completion — pip remote completion with descriptions
• zsh-sed-sub — in-place sed substitution on the command line
• zsh-sudo — ESC ESC to prepend sudo
• zsh-xcode-completions — xcodebuild / xcrun / swift completion