bash args

Bash-args

Il s'agit d'un framework pour écrire des scripts bash qui acceptent des options et/ou des arguments. Définissez les options et arguments acceptés par votre script à l'aide d'une syntaxe déclarative simple et laissez bash-args :

• Analyser les arguments de la commande
• Générer des pages d'aide
• Gérer la saisie semi-automatique

Il est conçu pour être simple à utiliser, pour ne pas gêner et pour offrir une expérience utilisateur raffinée.

Elle se veut portable, la suite de tests transmet toutes les versions majeures de bash >= 3.2.

Table des matières

• Démarrage rapide
  • Sous-commandes
• Métadonnées de script
• Définir les options
• Complétion automatique
  • Types d'arguments
  • Types d'arguments personnalisés

Démarrage rapide

Pour utiliser bash-args dans vos scripts, sourcez simplement le fichier init.sh

Voici un exemple de script eval-command.sh :

 #! /usr/bin/env bash
# Summary : My first bash script using bash-args.
#
# Description : This takes a command as argument, and runs it.
#
# Argument : command
#
# Options :
#
# % dry-run
# desc="Don't execute, just print."
# short="n" type="flag" variable="dry_run" value=1 default=0
#
# % directory
# desc="The directory in which to run the command." argument=directory
# short="d" type="option" variable="directory" default="$(pwd)"
#

. path/to/bash-args/init.sh

# After sourcing the script, you can use the $directory and the $dry_run
# variables to get the values of the options typed (or not) in the command line.
# The other arguments are available as standard bash arguments $1, $2, etc.

command= " cd $directory && $1 "

if [[ $dry_run -eq 1 ]] ; then
    echo " $command "
else
    eval " $command "
fi

Essayons d'exécuter cette commande avec options :

 $ eval-command.sh --dry-run --directory /home 'echo hello'
cd /home && echo hello

Vous pouvez utiliser des options courtes, et elles peuvent être regroupées :

 $ eval-command.sh -nd /home 'echo hello'
cd /home && echo hello

Complétion de l'onglet Configuration avec une simple commande :

 $ eval $(eval-command.sh _register_completion)

Une page d'aide est fournie :

 $ eval-command.sh --help
My first bash script using bash-args.

Usage : eval-command.sh [OPTIONS] [COMMAND]

This takes a command as argument, and runs it.

Options :

  --help | -h
          Show this help.

  --dry-run | -n
          Don't execute, just print.

  --directory | -d [DIRECTORY]
          The directory in which to run the command.

Sous-commandes

Bash-args peut également gérer des sous-commandes :

• Des pages d'aide sont disponibles pour chaque commande en utilisant main-script.sh help subcmd1 ou main-script.sh subcmd1 --help .
• L'auto-complétion propose des sous-commandes, leurs options et leurs arguments.

Pour ce faire, appelez la fonction cmd_run à la fin de votre script principal et définissez des sous-commandes en ajoutant des scripts shell au répertoire cmd/ . La structure de votre projet doit ressembler à :

 main-script.sh
cmd/
  - subcmd1.sh
  - subcmd2.sh

Pour documenter les sous-commandes et définir leurs options et arguments, écrivez les métadonnées dans les premiers blocs de commentaires de chaque sous-commande, comme dans le script principal.

Les options définies dans le script principal sont disponibles pour toutes les sous-commandes, tandis que les options définies dans une sous-commande ne sont disponibles que pour cette sous-commande spécifique.

Métadonnées de script

Les métadonnées du script suivent une syntaxe très simple : dans le premier bloc de commentaire, chaque ligne qui commence par un mot suivi d'un point-virgule définit un nouveau champ, et tout ce qui suit le point-virgule définit sa valeur. Les lignes suivantes, jusqu'au début du champ suivant, sont ajoutées à la valeur.

Voici les champs utilisés par bash-args .

• Résumé : Une description en une ligne du script.
• Description : Une longue description du script.
• Version : une chaîne de version. Si votre script principal a un champ méta de version, il obtiendra une option --version qui imprime son nom et sa version.
• Utilisation : Si la ligne d'utilisation par défaut de la page d'aide ne vous convient pas, vous pouvez la remplacer ici.
• Argument : Définit le type d'argument utilisé pour l'auto-complétion. voir Types d'arguments
• Options : Définissez les options de votre script. voir Définir les options

Définir les options

Les options sont définies dans les métadonnées Options , comme dans l'exemple de script :

 # Options :
#
# % dry-run
# desc="Don't execute, just print."
# short="n" type="flag" variable="dry_run" value=1 default=0
#
# % directory
# desc="The directory in which to run the command." argument=directory
# short="d" type="option" variable="directory" default="$(pwd)"
#

Une option commence par un % suivi de son nom. Les noms d'options doivent contenir uniquement des caractères alphanumériques, _ ou - .

Les lignes suivantes définissent les paramètres de l'option. Lorsque le script est exécuté, il est en fait évalué comme du code bash. Les variables définies sont les paramètres de l'option. Cela signifie que les règles générales de citation pour les chaînes s'appliquent et que vous pouvez définir les options de manière dynamique, comme dans l'exemple ci-dessus, dans lequel le paramètre default de l'option directory est défini sur $(pwd) .

Une option doit définir au minimum le type et le paramètre variable :

• type peut être un flag ou option . Les drapeaux n'acceptent pas les arguments, contrairement aux options.
• variable est le nom de la variable sous laquelle la valeur de l'argument de l'option sera disponible dans votre script.

Une option peut définir ces autres paramètres :

• desc est une description de l'option, utilisée dans les pages d'aide.
• short est une seule lettre, utilisée pour l’option courte.
• argument est le type d'argument. voir Types d'arguments
• default est la valeur que prend l'option lorsque l'option n'est pas spécifiée dans la commande saisie par l'utilisateur.
• value est la valeur que prend l'option lorsque l'option est spécifiée, mais sans argument.

Les variables définies par options sont garanties d'être définies dans votre script : si bash-args ne trouve pas de valeur pour une option, il se terminera avec une erreur. Cela signifie que si vous ne spécifiez pas default d'une option, l'exécution du script principal sans cette option renverra une erreur.

Autrement dit, si vous ne souhaitez pas qu'une option soit obligatoire, définissez un paramètre default dans sa définition.

Le paramètre value fonctionne de la même manière. Si vous ne le spécifiez pas, l'option, lorsqu'elle est utilisée, nécessite un argument. Si vous le faites, l’option peut être utilisée sans argument.

Les options d'indicateur fonctionnent de la même manière, et comme elles ne prennent pas d'arguments, vous devez définir à la fois leurs paramètres default et value .

Complétion automatique

Bash-args peut gérer la complétion automatique de votre script à l'aide de l'API de complétion de Bash. Pour activer la saisie semi-automatique pour votre commande, exécutez la commande suivante :

 eval $( my-command.sh _register_completion )

La complétion par tabulation suggérera alors les options définies si le mot au point commence par un - , et suggérera des sous-commandes et des arguments dans le cas contraire.

Types d'arguments

Pour indiquer à bash-args quoi suggérer comme argument, vous spécifiez un type d'argument dans les métadonnées Argument de votre script (ou sous-commande), ou dans le paramètre argument d'une option.

Voici les types d'arguments intégrés :

• file suggérera des fichiers.
• directory suggérera des répertoires.

Types d'arguments personnalisés

Pour créer un nouveau type d'argument et le configurer pour la complétion automatique, définissez une fonction appelée _complete_my_arg_type . Cette fonction doit être disponible pour le script init.sh , elle doit donc être définie avant le . init.sh ligne . init.sh

Les fonctions de complétion sont censées ajouter leurs suggestions au tableau global COMP_REPLIES . Ils obtiennent le mot actuel au point comme paramètre pour plus de commodité, mais vous pouvez également utiliser les variables globales COMP_LINE et COMP_POINT , comme dans tous les scripts de complétion bash.

Voici comment le type d'argument du fichier est défini :

 _complete_file () {

    # $1 is the word being typed that we want to complete.
    for file in " ${1-} " * ; do
        # add each file to the completion candidates.
        COMP_REPLIES+=( " $file " )
    done
}