Écrire un fichier de complétion pour zsh

zsh est très connu pour son système de complétion très poussé. Malheureusement, zsh n'est pas équipé pour gérer les conventions d'appel de tous les outils qu'on peut trouver sur nos babasses. On peut donc être amené à écrire soi-même une méthode de complétion. Ces notes ont été prises à l'occasion de l'écriture d'un fichier de complétion pour ezjail, et les exemples viennent de là.

1. Parfois, il n'y a presque rien à faire…

Il y a quelques cas où on n'a presque rien à faire pour bénéficier de la complétion sur un nouvel outil. Par exemple, si un outil utilise les conventions GNU, zsh peut parser la sortie de --help pour obtenir la liste des options existantes. Il suffit pour cela d'ajouter quelque chose comme :

compdef _gnu_generic foo

dans un fichier lu par zsh (.zshrc conviendra), et de relancer son shell pour pouvoir compléter les options de foo. On a même le droit à la documentation des options.

Un autre cas où l'on n'a presque rien à faire est lorsqu'on peut réutiliser une complétion existante. Si un outil attend comme argument uniquement des noms d'hôtes, on utilisera :

compdef _hosts foo

Maintenant, en tapant foo <TAB>, zsh proposera des complétions basées sur les noms d'hôtes, trouvés par `getent hosts` ou qui sont dans l'une des bases ssh_known_hosts entre autres.

Dans l'exemple au-dessus, _hosts est le nom d'une fonction zsh, dont la définition est (sur mon système) dans /usr/local/share/zsh/4.3.11/functions/Completion/Unix.

La documentation de zsh donne un autre exemple assez courant : le cas d'une commande qui accepte tous les fichiers qui ont une certaine extension.

compdef '_files -g "*.h"' foo

Ici, _files est encore une fonction, définie au même endroit que _hosts (et bon courage à celui qui voudra se plonger dans le code de cette fonction…). La documentation de cette fonction est visible dans le manuel de zsh, au nœud « Completion Functions > Utility Functions ».

2. …parfois c'est plus compliqué

Lorsqu'on a des besoins plus poussés, au hasard pour un outil tel qu'ezjail, on va devoir coder sa propre complétion. Une complétion n'est en soi qu'une fonction zsh qui est appelée par le shell lorsque l'utilisateur appuie sur TAB (ou C-d pour afficher les complétions).

Les fonctions de complétions sont installées par défaut dans /usr/local/share/zsh/site-functions/ (l'emplacement exact peut dépendre de votre OS). Par convention, le fichier dans lequel vous allez écrire votre fonction de complétion a le même nom que la commande concerné, avec un _ ajouté au début.

Lors du développement d'un fichier de complétion, il sera peut-être plus pratique de pouvoir éditer le fichier sans être root. Dans ce cas, il suffit de choisir un dossier local, par exemple ~/zsh. On placera le fichier de complétion dedans, et on l'ajoute au tableau $fpath (bien sûr, à placer avant l'appel à compinit) :

fpath=(~/zsh $fpath)

Notons que zsh refusera de charger des fonctions (donc des définitions de complétion) si le fichier appartient à un utilisateur autre que root ou l'utilisateur courant, ou s'il est modifiable par un autre utilisateur.

Le fichier de complétion commence avec un tag spécial sur la première ligne :

#compdef ezjail-admin

C'est un commentaire, qui indique à zsh que le fichier contient une complétion, et bien sûr quelle commande est concernée.

Ensuite, on définit une fonction de complétion, et on l'appelle :

_ezjail () {
    # code de complétion
}

_ezjail "$@"

2.1. Informations fournies par le shell aux fonctions de complétions

Notre code, ici la fonction _ezjail, sera appelée avec quelques informations sur la ligne de commande qui a déjà été saisie par l'utilisateur.

Les informations qui sont accessibles depuis le code de complétion seront les suivantes :

Variable	Description
`$words`	Les mots déjà entrés par l'utilisateur
`$CURRENT`	L'index, dans `$words`, du mot que l'utilisateur essaie de compléter (c'est `$#words` sauf si l'utilisateur est revenu en arrière)
`$curcontext`	Une chaîne de caractères, décrivant le contexte courant

Le contexte courant est utilisé en interne à zsh pour savoir comment interpréter les demandes de complétions. Depuis le code de complétion, on passera aussi $curcontext à zstyle pour récupérer les styles de complétion voulus par l'utilisateur. Comme je n'utilise pas zstyle, je ne me suis pas beaucoup avancé dans cette direction.

Si vous avez sous les yeux le fichier de complétion d'ezjail, vous verrez que la fonction principale, _ezjail, fait un petit tour de passe-passe sur ces variables pour sauter sur la fonction correspondant à la sous-commande déjà entrée. La plupart des outils pourront certainement se passer d'une telle manipulation.

2.2. Renvoyer les candidats à la complétion

Pour renvoyer à zsh les complétions elles-mêmes, on va utiliser l'une des fonctions de complétion. La fonction _arguments sera notre outil principal, en particulier pour les outils qui ont des options standards.

2.2.1. Exemple typique

Si l'on prend comme exemple la complétion (un peu réorganisée) pour ezjail-admin create:

_ezjail_cmd_create () {
    _arguments -s : \
        "-i[file-based jail]" \
        "-x[jail exists, only update the config]" \
        "-a[restore from archive]:archive:_files" \
        "-c[image type]:imagetype:(bde eli zfs)" \
        "-C[image parameters]:imageparams:" \
        "-s[size of the jail]:jailsize:" \
        ":jail name:" \
        ":comma-separated IP addresses:"
}

Le -s donné à _arguments permet de dire que pour cette commande, les options courtes peuvent être combinées, i.e. -ix est équivalent à -i -x. Le texte entre crochets est affiché à côté de la complétion, sauf si l'utilisateur a désactivé cela.

Dans l'exemple au-dessus, -i et -x sont des options qui n'attendent pas d'arguments. Les autres options attendent des arguments : on les distingue parce qu'une description de l'argument et une méthode pour compléter cet argument sont données, avec des : pour séparer les champs. Dans le cas de -a, l'argument sera complété par la fonction _files, qui propose des noms de fichiers comme choix. Dans le cas de -c, la completion se fait sur un petit nombre de choix possibles, qui sont donnés entre parenthèses. Pour -C, on indique qu'on attend un mot donné par l'utilisateur, mais le shell n'aidera pas à le compléter.

Enfin, la commande prend encore deux arguments, mais on ne sait pas offrir d'aide pour les compléter (il n'y a rien avant le premier :).

2.2.2. Options mutuellement exclusives

Il peut y avoir des cas où des options sont mutuellement exclusives. C'est le cas pour ezjail-admin archive : ou bien l'on archive toutes les jails avec -A, ou alors on donne une liste de jails.

_ezjail_cmd_archive () {
    _arguments -s : \
        "-a[archive name]:archive name:" \
        "-d[destination directory]:destination dir:_files -/" \
        "-f[archive the jail even if it is running]" \
        - archiveall \
            "-A[archive all jails]" \
        - somejails \
            "*:jail:_ezjail_stopped_jails"
}

On sépare les groupes d'options qui s'excluent avec un tag (je ne sais pas si le nom est réutilisé pour être montré à l'utilisateur dans certaines circonstances). Les options qui peuvent toujours être utilisées sont données en premier. Remarquez au passage l'astérisque pour la dernière ligne : cela permet d'indiquer qu'on peut avoir des répétitions.

2.2.3. `_values`: plus simple

Lorsqu'on a juste une liste de mots à proposer, surtout si cette liste est générée dynamiquement, les arguments pour _arguments ne sont pas faciles à manipuler. Dans ce cas, _values, qui permet de simplement donner la liste des mots candidats à la complétion, est plus facile à manipuler. En prenant comme exemple _ezjail, dans le cas où on propose les sous-commandes, on a :

_ezjail () {
    local cmd
    if (( CURRENT > 2)); then
        # déjà un mot complet sur la ligne; sauter à la fonction
        # spécifique à cette sous-commande.
    else
        # on complète la sous-commande
        _values :                                                \
            "archive[create a backup of one or several jails]"   \
            "config[manage specific jails]"                      \
            "console[attach your console to a running jail]"     \
            "create[installs a new jail inside ezjail\'s scope]" \
            "cryptostart[start the encrypted jails]"             \
            "delete[removes a jail from ezjail\'s config]"       \
            "install[create the basejail from binary packages]"  \
            "list[list all jails]"                               \
            "restart[restart a running jail]"                    \
            "restore[create new ezjails from archived versions]" \
            "start[start a jail]"                                \
            "stop[stop a running jail]"                          \
            "update[create or update the basejail from source]"
    fi
}

2.2.4. `compadd`: pour construire les complétions au fur et à mesure

compadd est le builtin utilisé par _arguments, _values et les autres fonctions pour ajouter les candidats à la complétion. Il y a certains cas où il est plus facile d'ajouter un à un les candidats. C'est le cas pour lister les jails : une première version utilisait quelque chose de la forme :

_ezjail_running_jails () {
    _values : `_ezjail_list_jails running`
}

_ezjail_list_jails () {
    local jailcfgs="/usr/local/etc/ezjail"
    local state=$1
    local j
    ( cd $jailcfgs && echo * ) | while read j; do
        case $state in
        running) [[ -f /var/run/jail_${j}.id ]] && echo $j ;;
        stopped) [[ -f /var/run/jail_${j}.id ]] || echo $j ;;
        *)       echo $j ;;
        esac
    done
}

Le problème est que lorsque la sortie de _ezjail_list_jails est vide, _values remonte un message d'erreur parce qu'on ne lui a donné aucun argument. Pour corriger cela, une première solution pourrait être de capturer la sortie de _ezjail_list_jails dans une variable, tester si cette variable est vide ou non, et agir en conséquence. La deuxième solution, qui est celle que j'ai retenu, est de faire ajouter à _ezjail_list_jails les complétions elles-mêmes. Il faut encore gérer à part le cas où il n'y a pas de candidats à la complétion, en revoyant 1 dans ce cas ; mais c'est plus facile à gérer. Au passage, la première version ne renvoyait pas 1 en l'absence de candidates… L'implémentation ressemble à ceci :

_ezjail_running_jails () {
    _ezjail_list_jails running
}

_ezjail_list_jails () {
    local jailcfgs="/usr/local/etc/ezjail"
    local state=$1
    local ret=1
    local j
    for j in $jailcfgs/*(:t) ; do
        case $state in
        running) [[ -f /var/run/jail_${j}.id ]] && compadd $j && ret=0 ;;
        stopped) [[ -f /var/run/jail_${j}.id ]] || compadd $j && ret=0 ;;
        *)       compadd $j && ret=0 ;;
        esac
    done
    return $ret
}

compadd, en tant que brique de base, permet bien plus que de simplement ajouter un candidat. Encore une fois, allez voir la documentation pour tous les détails.

2.3. Style

Le code de complétion est lancé à chaque fois que l'utilisateur tapotte sa touche TAB ou C-d. Le code doit donc être raisonnablement rapide.

Par ailleurs, le code de complétion s'exécute dans le shell courant de l'utilisateur. En particulier :

le code n'a pas le droit de faire un exit ;
il ne peut pas afficher de chose sur std{out,err} sans faire une horrible mixture entre le prompt, les propositions de complétion et ce qui est affiché ;
il faut penser à retourner 1 si on n'a pas de candidats à la complétion ;
toutes les variables utilisées doivent être déclarées avec local, pour éviter d'écraser ou de polluer les variables du shell courant de l'utilisateur ;
on écrit du code pour zsh, on a toute latitude pour écrire du code qui n'est pas POSIX.

Il y a également completion-style-guide, qui est chez moi dans /usr/local/share/doc/zsh (copie en ligne), qui donne des conseils. J'ai découvert ce fichier un peu tard, et la complétion pour ezjail ne suit pas toujours à la lettre les conseils donnés.

Bien sûr, lorsqu'on a quelque chose qui marche, on le propose au projet en question, ou alors directement sur la liste zsh-workers@, pour en faire profiter les petits copains.

3. À voir

A User's Guide to the Z-Shell, Peter Stephenson, Chapter 6: Completion, old and new. Il y a en particulier un tutorial bien fait.

The Z Shell Manual, 20. Completion System, et en particulier 20.6 Utility Functions. Vous en avez certainement une version accessible en local avec info zsh (ou C-h i m zsh depuis emacs). Le manuel est assez aride, je ne l'ai utilisé que comme référence.

zsh completion support for ezjail, de votre serviteur.