Better shell completion

Intro

In this issue I will explain how to automatically provide your CLI app's shell completions to your users in a seamless way.

I've been recently investigating how shell completion works, and various approaches to it. I decided to write my findings down to share knowledge with others, and to (hopefully) improve this package's documentation and functionality so that we can improve how shell completions are distributed for Dart CLI apps.

Intended audience: authors of CLI tools written in Dart that depend on cli_completion package

Description

That's how the original zsh completion script provided by this package looks like this. Let's assume our CLI app name is foobar and that we called foobar install-completion-files, which generates the following zsh shell completion script in ~/.config/.dart-cli-completion/foobar.zsh:

if type compdef &>/dev/null; then
  _foobar_completion () {
    local reply
    local si=$IFS

    IFS=$'
' reply=($(COMP_CWORD="$((CURRENT-1))" COMP_LINE="$BUFFER" COMP_POINT="$CURSOR" foobar completion -- "${words[@]}"))
    IFS=$si

    if [[ -z "$reply" ]]; then
        _path_files
    else
        _describe 'values' reply
    fi
  }
  compdef _foobar_completion foobar
fi

I modified the script above a bit to be a "standard" zsh completion script, that is:

• it has #compdef <program_name> at the top -> #compdef foobar
• it is named _<program_name> -> _foobar
• it works well on "first run" (you don't have to click TAB twice to initalize it on first run, like it is now) (another description of this issue)

#compdef foobar

local reply
local si=$IFS

IFS=$'
'
reply=($(COMP_CWORD="$((CURRENT-1))" COMP_LINE="$BUFFER" COMP_POINT="$CURSOR" foobar completion -- "${words[@]}"))
IFS=$si

if [[ -z "$reply" ]]; then
    _path_files
else
    _describe 'values' reply
fi

Now I put that script to zsh's conventional location for shell completion scripts - in case of my macOS, it's /opt/homebrew/share/zsh/site-functions:

cp _foobar /opt/homebrew/share/zsh/site-functions

Restart zsh by running exec zsh and voilà, the completion for foobar should work now!

If it does not, make sure you're adding opt/homebrew/share/zsh/site-function to your $FPATH - see relevant docs.

Distribution

With the above in mind, I can easily write e.g. a Homebrew formula for my CLI tool, and inside that formula put shell completion installation files:

# excerpt from a hypothetical foobar.rb Formula

def install
  bin.install "foobar"
  bash_completion.install "autocomplete/bash_autocomplete" => "foobar"
  zsh_completion.install "autocomplete/zsh_autocomplete" => "_foobar"
end

Note that this automatic setup of completion files is only possible when your CLI app is installed through a proper package manager, like Homebrew or Pacman. If it is installed with dart pub global activate, the approach I described here won't work, because dart pub global activate only compiles the Dart source code to a JIT executable, and doesn't have any way of also copying files – which is required for automatical installation of shell completion.

But even if you prefer to install your Dart CLI app with dart pub global activate, you can distribute the completion scripts in different way – e.g. as an oh-my-zsh plugin – or you can just provide the completion script and tell your users "hey, install it at this-and-that path". I think it's much better than appending some code to ~/.zshrc or ~/.bashrc.

Start in lib/src/installer/shell_completion_configuration.dart, especially the existing zsh completion generation linked in the issue, and compare it with the proposed standard script. The completed change should generate zsh completion files with the program directive and first-run behavior described, while preserving the existing completion command integration.