Complétion programmable en Shell

Comment réaliser une complétion pour ses petits scripts maison ?

Documentation

Usages basiques

Enregistrement de la "spec de complétion"

Pour enregistrer une "spec de complétion" on utilise la commande complete :

complete -W "LISTE_DE_MOTS" -- MA_COMMANDE_A_COMPLETER
complete -F _MA_FONCTION -- MA_COMMANDE_A_COMPLETER

Une fois la spec enregistrée, lorsque l'utilisateur utilise le mécanisme de complétion (avec la touche <TAB>), une liste mot lui est proposé pour compléter sa ligne de commande.

La fonction _MA_FONCTION (utilisé avec complete -F)

Si la spec de complétion indique que l'on utilise une fonction, alors a chaque fois que l'utilisateur utilise le mécanisme de complétion (avec la touche <TAB>), la fonction _MA_FONCTION est appelée pour déterminer quels sont les mots à proposer à l'utilisateur.

La fonction est chargé de déterminer en fonction du contexte la liste des mots à proposer à l'utilisateur pour compléter sa ligne de commande.

Il est d'usage de nommer cette fonction avec un _ (underscore) comme préfixe.

Dans la fonction, on dispose de 3 variables d'environnement pour implémenter la logique de complétion :

COMP_WORDS : Le tableau contenant la liste des mots déjà complétés et en cours de "tapage".
COMP_CWORD : L'index du mot en cours de "tapage" (le dernier index du tableau COMP_WORDS, ce qui en fait le nombre de mot déjà complétés, puisque l'index commence à 0).
COMPREPLY : Le tableau qui contiendra la liste des mots à proposer à l'utilisateur. Cette variable sera lu par le mécanisme de complétion une fois l'exécution de la fonction terminé.

La fonction est appelée avec ces 3 paramètres :

$1 le nom de la commande en cours de complétion
$2 le mot en cours de "tapage"
$3 le mot précédent le mot en cours de "tapage"

Recherche des mots qui match

Pour des usages complexes, notamment avec une fonction, il est pratique d'utiliser la commande compgen :

compgen -W "LISTE_DE_MOTS"  -- MOT_A_MATCHER

Cette commande permet par exemple de filtrer une liste de mots. Dans notre exemple, elle retourne tous les mots de la LISTE_DE_MOTS qui match le MOT_A_MATCHER au sens habituel du mécanisme de complétion.

Exemples

_ma_commande() {
    COMPREPLY=();
    # Mot en cours d'écriture
    local word="${COMP_WORDS[COMP_CWORD]}";
    local completions
 
    if [ "$COMP_CWORD" -eq 1 ]
    then
        # En cours d'écriture du premier mot après la commande
        completions="foo bar baz"
        COMPREPLY=($(compgen -W "$completions" -- "$word"))
    else
        # Le premier mot est déjà écrit
        local firstWord = "${COMP_WORDS[1]}"
        case "${COMP_WORDS[1]}" in
            un) completions="-a -b --test" ;;
            deux) completions="-a -e" ;;
            trois) completions="--name" ;;
            quattre) completions="-o -i" ;;
        esac
    fi
 
    # On stocke les mots à proposer à l'utilisateur dans le tableau COMPREPLY
    COMPREPLY=($(compgen -W "$completions" -- "$word"))
}
 
complete -F _ma_commande -- ma_commande
 
complete -W "foo bar baz" -- mon_autre_commande