Comment créer facilement des scripts bash prenant en charge les options

Exemple de script

Disons que nous voulons créer un script bash appelé archive-project.sh pour archiver un projet sous Gitlab Dépôt du projet. Voici comment nous souhaitons utiliser le script :

(bash)$ ./archive-project.sh -h

Archive Gitlab project repository

Usage :
> ./archive-project.sh --id <project-id> -u <gitlab-url> --token <gitlab-token>

Options :

-h, --help               Show help on how to use this script
--id                     ID of the project to archive
-u, --url                URL of the Gitlab instance where the project resides
-t, --token              User API token to use for authentication. 
                         The user  generating the API token need to have
                         'Owner' privilege on the project to archive

Comme vous pouvez le voir, les utilisateurs du script pourront définir des options pour indiquer au script quel projet archiver, sur quelle instance Gitlab, avec quel jeton d'authentification. La routine shell getopt peut être très utile pour y parvenir. Nous verrons comment, continuez à lire 😉

Avantages de l'utilisation de getopt

La routine shell getopt peut être très utile pour créer des scripts shell prenant en charge les options. getopt s'occupera des tâches suivantes pour vous :

• vérifier et valider vos options prédéfinies
• reconnaitre les options courtes (-s par exemple), longues (--my-long-option) ou alternatives (-myoption)
• vérifier et valider les arguments des options lorsque cela est nécessaire
• sortie avec un code d'erreur différent de 0 quand quelque chose ne va pas (argument d'option requis non défini, options non définies passées au script...)
• afficher des messages d'erreur précis (dans la langue configurée dans vos paramètres régionaux)
• possibilité de désactiver l'affichage des messages d'erreur prédéfinis afin d'afficher vos messages personnalisés

Comment fonctionne getopt ?

Lors de l'utilisation de getopt, deux parties séparées par -- peuvent être identifiées. La première partie est celle où nous personnalisons le comportement de getopt en utilisant certaines de ses options pour indiquer quels paramètres prédéfinis nous voulons que nos scripts prennent en charge, sous quelle forme nous voulons qu'ils soient (long : --something, court: -b ...), ont-ils des paramètres requis, etc.

La deuxième partie est la liste des arguments du script que getopt analysera pour reconnaître nos options prédéfinies et effectuer certains traitements. Cette deuxième partie est généralement récupérée dans les scripts bash avec la variable "$@" , variable qui stocke les arguments du script.

Voici la liste des getopt à utiliser à l'intérieur du script archive-project.sh exemple de script :

getopt -s 'bash' -o 'h,u,t' -a -l 'help,id:,url:,token:' -n 'archive-project.sh' -- "$@"

Dans la commande getopt commande, nous avons utilisé les options suivantes :

• --name, -n: le nom du script qui sera utilisé par getopt lors du signalement de certaines erreurs... par exemple, lors de la détection d'options non reconnues dans les arguments
  Ex: archive-project.sh : option non reconnue '--fakeoption'
• --shell, -s: représente le type de shell que nous utiliserons avec getopt pour analyser les arguments des scripts... Valeurs possibles : bash or tcsh
• --longoptions, -l: dire à getopt de reconnaître les options longues séparées par des virgules que nous avons spécifiées... les : à la fin de certaines options indiquent à getopt que des arguments/valeurs sont requises pour ces options. Nous pouvons également utiliser :: pour dire à getopt que nous voulons que l'argument soit facultatif pour une option spécifique.
• -a, --alternative: autoriser les options longues à être spécifiée avec un seul tiret : -. Cela signifie que l'utilisation de -token par exemple, pendant l'exécution du script, fonctionnera également en plus de --token. Cependant, lors du parsing des arguments du script, vous devez utiliser le format d'options longues (--token) dans le bloc while/case ... -token ne sera pas reconnu...
• -o, --options: options courtes

Nous pouvons également utiliser l'option -q dans la ligne de commande getopt précédente, si nous ne souhaitons pas afficher les messages d'erreur prédéfinis. Ne pas utiliser l'option -q fait que getopt affiche des messages d'erreur lorsque les utilisateurs :

• exécutent le script avec une option non définie
• exécutent le script avec une option définie mais sans argument, lorsqu'il en faut obligatoirement un
• pour une erreur interne à getopt lui-même

Exemples de messages d'erreur

(bash)$ ./archive-project.sh --id
archive-project.sh: option '--id' requires an argument

(bash)$ ./archive-project.sh --non-existent-option
archive-project.sh: unrecognized option '--non-existent-option'

Utilisation de getopt pour implémenter le script de l'exemple

Dans cette section, nous montreront comment implémenter le comportement défini pour le script exemple : archive-project.sh et voir en pratique, comment des scripts conviviaux, facilement configurables et extensibles pourraient être créés en tirant parti des fonctionnalités de getopt .

Pour rappel, voici comment nous souhaitons que le script soit utilisable :

(bash)$ ./archive-project.sh -h

Archive Gitlab project repository

Usage :
> ./archive-project.sh -id <project-id> -u <gitlab-url> --token <access-token>

Options :

-h, --help               Show help on how to use this script
-id, --project-id        ID of the project to archive
-u, --gitlab-url         URL of the Gitlab instance where the project resides
-t, --access-token       User API token to use for authentication. 
                         The user  generating the API token need to have
                         'Owner' privilege on the project to archive

Comme vous pouvez le constater, il est facilement configurable grâce aux options. L'ajout de nouvelles fonctionnalités signifie simplement de nouvelles options pour les utilisateurs, ce qui est très convivial.

Dans la première partie du script, nous définissons les fonctions :

#!/bin/bash

# Print usage
usage() {
  echo -e "\nArchive Gitlab project repository \n"
  echo -e "Usage : $0 -id <project-id> -u <gitlab-url> --token <access-token> \n"
  echo -e "Options : \n"
  echo -e "-h, --help               \t Show help on how to use this script"
  echo -e "-id, --project-id        \t ID of the project to archive"
  (...)
  exit 1
}

# Archive project
archive_project()
{
  gitlab_url=$1    # value taken from the first argument of the function
  project_id=$2    # value taken from the second argument of the function
  access_token=$3  # value taken from the third argument of the function
  
  # code to archive Gitlab project here
}

La routine shell usage sera appelée lorsque le script est exécuté sans arguments ou avec l'option -h . La fonction archive_project sera appelée lorsque les utilisateurs définiront correctement chacune des options requises pour archiver un projet Gitlab.

Voici la partie restante du contenu du script archive-project.sh script divisé en plusieurs morceaux :

Pièce n°1

# getopt command used to add option support
GETOPT=$(getopt -s 'bash' -o 'h,u:,t:' -a -l 'help,id:,url:,token:' -n 'archive-project.sh' -- "$@")

# If there is any error with the previous getopt command,
# an explicit error message will be printed by getopt and
# the script will exit
if [ $? -ne 0 ]; then
    exit 1
fi

# If no argument is provided print usage and exit
if [[ -z "$@" ]] ; then usage ; exit 1 ; fi

Pièce n°2

eval set -- "$GETOPT"

• Définit la valeur des arguments positionnels ($@) à la valeur de la variable GETOPT .
• Ceci est exécuté uniquement lorsque la commande getopt de la Pièce n°1 réussit
• La routine shell GETOPT contiendra simplement tous les arguments passés au script plus le -- à la fin. Exemple :

# Script execution command
(bash)# ./archive-project.sh -id 152 --gitlab-url https://gitlab.hackerstack.org --access-token mytoken

# GETOPT variable resulting content
-id '152' --gitlab-url 'https://gitlab.hackerstack.org' --access-token 'mytoken

Pièce n°3

while true; do
    case "$1" in
        -h|--help)
            usage
        ;;
        --id)
            id=$2
            shift 2;
        ;;
        -u|--gitlab-url)
            url=$2
            shift 2;
        ;;
        -t|--access-token)
            token=$2
            shift 2;
        ;;
        --)
            shift ;
            break ;
        ;;
    esac
done

# Exploit parsed options arguments to archive the Gitlab project
archive_project $url $id $token

• Récupère les arguments d'options à partir des arguments positionnels (contenus dans $@) grâce à une boucle while/case .
• Pour chaque option valide présente dans les arguments du script, nous effectuons une action. Pour l'option -h or --help par exemple, nous faisons appel à la fonction usage .
• Pour chacune des autres options, nous définissons la valeur de leurs arguments en utilisant la variable appropriée et passons à l’option suivante dans l’argument positionnel (shift 2)
• Nous sommes à la fin des arguments positionnels lorsque l'argument -- est récupéré. Il est temps de quitter la boucle (shift + break) et exploiter les valeurs des options enregistrées
• Les entrées des utilisateurs nécessaires à l'archivage d'un projet Gitlab, transmises via les options correspondantes, sont désormais enregistrées dans les variables url, id et token , et peuvent être transmises à la fonction archive_project pour archiver le projet correspondant

Et voilà ! Vous savez maintenant comment créer des utilitaires bash conviviaux, configurables et facilement extensibles grâce aux fonctionnalités fournies par la routine shell getopt