Complétion shell programmable

Documentation

1. https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion-Builtins.html
2. https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion-Builtins.html
3. https://www.gnu.org/software/bash/manual/html_node/A-Programmable-Completion-Example.html

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 ), 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 ), 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

Completion simple "à 1 seul niveau"

Dans cet exemple, la commande mon_autre_commande sera complétée avec les mots "foo bar baz".

 complete -W "foo bar baz" -- mon_autre_commande

Completion plus compliqué "à 2 niveaux"

Dans cet exemple, la commande ma_commande sera complétée par un premier niveau de mots : "foo bar baz".

Puis un second niveau de complétion sera proposé lorsque le premier mot sera complété : la commande ma_commande bar sera complété par les mots "-o -i -b toto".

_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
            foo) completions="-a -b --test" ;;
            bar) completions="-o -i -b toto" ;;
            baz) completions="--name -a" ;;
        esac
    fi
 
    # On stocke les mots à proposer à l'utilisateur dans le tableau COMPREPLY
    COMPREPLY=($(compgen -W "$completions" -- "$word"))
}
 
complete -F _ma_commande -- ma_commande