# -*- coding: utf-8 mode: sh -*- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8
##@cooked nocomments
module: base.args base_ "Fonctions de base: analyse d'arguments"
require: base.arr

function: base_myargs_local "Afficher des commandes pour rendre locales des variables utilisées par base_myargs()

Cela permet d'utiliser base_myargs() à l'intérieur d'une fonction. Par défaut, la génération automatique de l'autocomplete est désactivée."
function base_myargs_local() {
    # par défaut, désactiver génération de autocomplete
    echo "local NULIB_ARGS_HELP_DESC NULIB_ARGS_HELP_USAGE NULIB_ARGS_HELP_OPTIONS args"
    echo "local NULIB_ARGS_DISABLE_AC=1"
    echo "local NULIB_ARGS_ONERROR_RETURN=1"
}

function: base_myargs: "Débuter la description des arguments reconnus par ce script.

Arguments
: \$1 est un résumé de l'objet de ce script
: \$2 est le nom du script s'il est différent de \$MYNAME

Le mode opératoire est généralement le suivant:
~~~
myargs:
desc \"faire un traitement\"
usage \"MYNAME [options] <args>\"
arg -o:,--output:file output= \"spécifier le fichier destination\"
arg -h:,--host:host hosts+ \"spécifier les hôtes concernés\"
arg -c,--count count=1
parse \"\$@\"; set -- \"\${args[@]}\"
~~~"
function base_myargs:() {
    NULIB_ARGS_HELP_DESC=
    NULIB_ARGS_HELP_USAGE=
    NULIB_ARGS_HELP_OPTIONS=()
    args=()
    function desc() { base_myargs_desc "$@"; }
    function usage() { base_myargs_usage "$@"; }
    function arg() { base_myargs_add "$@"; }
    function parse() { base_myargs_parse "$@"; }
}

function: base_myargs_desc ""
function base_myargs_desc() {
    NULIB_ARGS_HELP_DESC="$*"
}

function: base_myargs_usage ""
function base_myargs_usage() {
    NULIB_ARGS_HELP_USAGE="$*"
}

function: base_myargs_add "Ajouter une définition d'option

Syntaxes
: base_arg MODE
: base_arg [MODE] -OPTIONS ACTION DESC
: base_arg [MODE] VARIABLE DESC

MODE peut être l'un des caractères '+', '-', '%' et a un effet sur l'analyse
entière de la ligne de commande
* Les caractères '+' et '-' influent sur la méthode d'analyse. Par défaut, les
  options sont valides n'importe où sur la ligne de commande. Avec '+',
  l'analyse s'arrête au premier argument qui n'est pas une option. Avec '-', les
  options sont valides n'importe ou sur la ligne de commande, mais les arguments
  ne sont pas réordonnés, et apparaissent dans l'ordre de leur mention.
* Le caractère '%' demande que toutes les variables mentionnées à partir de ce
  moment soient initialisées. Elle sont garanties d'être vides.

Avec la première syntaxe, on définit précisément l'option. Deux formes sont
supportées. La forme détermine le type d'action
* Avec la forme '-OPT VAR[=VALUE]', OPT est une description d'option, VAR un nom
  de variable à mettre à jour, et VALUE une valeur éventuelle pour les options
  sans argument. Si plusieurs options sont mentionnées, séparées par des
  virgules, alors tous les options partagent les mêmes paramètres.

  OPT peut être de la forme '-o' ou '--longopt' pour des options sans arguments.
  Dans ce cas, VAR obtient le nombre de fois que l'option est mentionnée (vide
  pour aucune mention, '1' pour une seule mention, etc.), sauf si on utilise la
  forme VAR=VALUE, auquel cas la variable obtient la valeur VALUE, et le nombre
  d'occurences de l'option n'est pas compté.

  Pour faciliter la lecture:
    * '--longopt .' est équivalent à '--longopt longopt'
    * '--longopt: .' est équivalent à '--longopt: longopt='

  Avec les formes '-o:' et '--longopt:', l'option prend un argument obligatoire.
  Avec les formes '-o::' et '--longopt::', l'option prend un argument facultatif
  (dans ce cas, la valeur de l'option sur la ligne de commande doit
  obligatoirement être collée à l'option.)

  Si ces options sont mentionnées plusieurs fois sur la ligne de commande, alors
  la variable de destination est un tableau qui contient toutes les valeurs. Le
  traitement de la valeur d'une variable dépend de la forme utilisée.
    * Avec une option sans argument, le comportement est celui décrit ci-dessus.
    * Avec une option qui prend des arguments, la forme '-o: VAR' considère que
      VAR est un tableau qui contiendra toutes les valeurs mentionnées dans les
      options. Avec la forme '-o: VAR=', la variable n'est pas un tableau et
      contient toujours la dernière valeur spécifiée.
* Dans la forme 'opt \$cmd', la commande cmd est executée avec eval *dès* que
  l'option est rencontrée. La variable option_ contient l'option, e.g. '-o' ou
  '--longopt'. Le cas échéant, la variable value_ contient la valeur de
  l'option. La fonction 'set@ NAME' met à jour la variable NAME, soit en lui
  donnant la valeur \$value_, soit en l'incrémentant, suivant le type d'option.
  La fonction 'inc@ NAME' incrémente la variable NAME, 'res@ NAME [VALUE]'
  initialise la variable à la valeur VALUE, 'add@ NAME [VALUE]' ajoute VALUE à
  la fin du tableau NAME. Par défaut, VALUE vaut \$value_

Avec la deuxième syntaxe, l'option est déterminée sur la base du nom de la
variable.
* Une variable de la forme 'sansarg' est pour une option simple qui ne prend pas
  d'argument
* Une variable de la forme 'avecarg=[default-value]' est pour une option qui
  prend un argument.
L'option générée est une option longue. En l'occurence, les options générées
sont respectivement '--sansarg' et '--avecarg:'
Les variables et les options sont toujours en minuscule. Pour les variables, le
caractère '-' est remplacé par '_'. Si une option contient une lettre en
majuscule, l'option courte correspondante à cette lettre sera aussi reconnue.

"
function base_myargs_add() {
    # description des options
    base_array_add args "${@:1:2}"
    # puis construire la description de l'option pour l'aide
    local -a os; local o odesc
    base_array_split os "$1" ,
    for o in "${os[@]}"; do
        o="${o%%:*}"
        [ -n "$odesc" ] && odesc="$odesc, "
        odesc="$odesc$o"
    done
    for o in "${os[@]}"; do
        if [[ "$o" == *:* ]]; then
            if [ "${2#\$}" != "$2" ]; then
                o=ARG
            else
                o="${2%%=*}"
                o="${o^^}"
            fi
            [ -n "$odesc" ] && odesc="$odesc "
            odesc="$odesc$o"
        fi
        break
    done
    base_array_add NULIB_ARGS_HELP_OPTIONS "$odesc"
    [ -n "$3" ] && base_array_add NULIB_ARGS_HELP_OPTIONS "$3"
}

function: base_myargs_show_help ""
function base_myargs_show_help() {
    local help="$MYNAME"
    [ -n "$NULIB_ARGS_HELP_DESC" ] && help="$help: $NULIB_ARGS_HELP_DESC"
    [ -n "$NULIB_ARGS_HELP_USAGE" ] && help="$help

USAGE
    $NULIB_ARGS_HELP_USAGE"
    [ ${#NULIB_ARGS_HELP_OPTIONS[*]} -gt 0 ] && help="$help

OPTIONS"
    echo "$help"
    for help in "${NULIB_ARGS_HELP_OPTIONS[@]}"; do
        echo "$help"
    done
}

function: base_myargs_parse ""
function base_myargs_parse() {
    [ -z "$NULIB_NO_DISABLE_SET_X" ] && [[ $- == *x* ]] && { set +x; local NULIB_ARGS_SET_X=1; }
    local r=0
    if ! parse_opts "${PRETTYOPTS[@]}" "${args[@]}" @ args -- "$@"; then
        edie "$args"
        r=$?
    fi
    [ -n "$NULIB_ARGS_SET_X" ] && set -x; return $r
}