Outils pour utilisateurs

Outils du site


programable_shell_complete

Complétion shell programmable

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

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
programable_shell_complete.txt · Dernière modification: 2020/03/30 14:42 de bigMax