Feature: zsh completions and formatting target lists with gotemplates

Short description

This pull request implements following functionalities:

Implement a formatting handle for listing targets in a templated syntax.
- This would be useful for machine parseable formats and implementing autocompletion scripts.
- E.g. MAGEFILE_HASHFAST=1 mage -l -format "{{ .Name }} {{ .Synopsis }}" (with hashfast)
-completion command to generate a completion script that can be sourced or deployed by the user.
Tests for new functionalities

Detailed description

This pull request implements following new features:

Support listing mage targets in a given go-template format
Generate completion script for zsh in an extendable way
Unit tests and CLI command call tests

Support listing mage targets in a given go-template format

Context: Autocompletion scripts can be wrapped around mage -l (list). This syntax has whitespaces and extra strings in the output, which need to be taken into account in parsing.

Idea: Implement a format handler similar to go list -format command that accepts go template language string. Calling then mage -l -format <template> will describe each target name-synopsis pair how they should be listed.

Implementation: mage -l -format "<template-string>" command with which custom formatted output can be created. This can be then easily'ish be parsed with shell scripts to provide completion scripts for targets. E.g. provided zsh shell script uses piped CSV as output and parses that with awk.

❯ mage -l -format "{{ .Name }}|{{ .Synopsis }}"
build|binaries for executables under ./cmd
buildForArmMac|Build for arm64 MacOS
buildForLinux|Build for x64 Linux
buildForMac|Build for amd64 MacOS
...

Generate completion scripts

Context: Many golang tools nowadays support creation and sourcing autocompletion scripts. To keep the implementation simple, mage could print the completion scripts which user can then decide how to either source or deploy to their environment.

Idea: Implement an extendable completion interface around which different shell formats can be extended.

Implementation: completions/completion.go package has been implemented with an interface which (at the moment) reads a zsh shell function script for autocompletion and prints this to the user. By default in zsh completion script, hashfast feature is disabled, but README guides users how to enable it, so hitting tab and getting results after initial compilation is much faster. Script also supports namespaces and all targets are sorted alphabetically.

# zsh completions script
mage -completion zsh

# Add following line to `.zshrc` for faster autocomplete after initial compilation:
echo "zstyle ':completions:*:mage:*' hash-fast true" >> ~/.zshrc

Demo

With dash+tab

With tab only

Enhancement ideas

go:embed directive could be used instead of storing the completion script contents in Go files. This would require go1.16 at minimum, but could be considered later?

Fixes #289

magefile / mage