<markdown>
# Complétion shell programmable
## Documentation
1. https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion-Builtins.html
1. https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion-Builtins.html
1. 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` :
``` bash
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` :
``` bash
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".

``` bash
 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".

``` bash
_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

```
</markdown>