<?php
namespace nur\ref;

/**
 * Class ref_args: référence du format des arguments pour une application
 */
class ref_args {
  const DEFS_SCHEMA = [
    "set_defaults" => [null, null, "tableau contenant des paramètres et des options par défaut"],
    "merge_arrays" => [null, null, "liste de tableaux à merger à celui-ci avant de calculer la liste effective des options"],
    "merge" => [null, null, "tableau à merger à celui-ci avant de calculer la liste effective des options",
      # si merge_arrays et merge sont spécifiés tous les deux, "merge" est mergé après "merge_arrays"
    ],
    "prefix" => [null, null, "texte à afficher avant l'aide générée automatiquement"],
    "name" => [null, null, "nom du programme, utilisé pour l'affichage de l'aide"],
    "purpose" => [null, null, "courte description de l'objet de ce programme"],
    "usage" => [null, null, "exposé textuel des arguments valides du programme",
      # ce peut être une chaine e.g '[options] SRC DESC'
      # ou un tableau auquel cas autant de lignes que nécessaire sont affichées
    ],
    "description" => [null, null, "description longue de l'objet du programme, affiché après usage"],
    "suffix" => [null, null, "texte à afficher après l'aide générée automatiquement"],
    "dynamic_command" => [null, null, "fonction indiquant si une commande est valide",
      # la signature de la fonction est function(string $command):?array
      # elle doit retourner un tableau au format DEFS_SCHEMA qui définit la
      # commande spécifiée, ou null si ce n'est pas une commande valide
    ],
    "sections" => [null, null, "liste de sections permettant de grouper les arguments"],
    "commandname" => [null, null, "propriété ou clé qui obtient la commande courante",
      # la valeur par défaut est "command" si ni commandproperty ni commandkey ne sont définis
    ],
    "commandproperty" => [null, null, "comme commandname mais force l'utilisation d'une propriété"],
    "commandkey" => [null, null, "comme commandname mais force l'utilisation d'une clé"],
    "argsname" => [null, null, "propriété ou clé qui obtient les arguments restants",
      # la valeur par défaut est "args" si ni argsproperty ni argskey ne sont définis
    ],
    "argsproperty" => [null, null, "comme argsname mais force l'utilisation d'une propriété"],
    "argskey" => [null, null, "comme argsname mais force l'utilisation d'une clé"],
    "autohelp" => ["?bool", null, "faut-il ajouter automatiquement le support de l'option --help"],
    "autoremains" => ["?bool", null, "faut-il ajouter automatiquement la prise en compte des arguments restants"],
  ];

  const SECTION_SCHEMA = [
    "show" => ["bool", true, "faut-il afficher cette section?"],
    "title" => [null, null, "titre de la section"],
    "prefix" => [null, null, "texte à afficher avant l'aide générée automatiquement"],
    "suffix" => [null, null, "texte à afficher après l'aide générée automatiquement"],

    # ces valeurs sont calculées
    "defs" => [null, null, "(interne) liste des définitions de cette section"],
  ];

  const DEF_SCHEMA = [
    "set_defaults" => [null, null, "tableau contenant des paramètres par défaut"],
    "merge_arrays" => [null, null, "liste de tableaux à merger à celui-ci"],
    "merge" => [null, null, "tableau à merger à celui-ci",
      # si merge_arrays et merge sont spécifiés tous les deux, "merge" est mergé après "merge_arrays"
    ],
    "kind" => [null, null, "type de définition: 'option' ou 'command'"],
    "arg" => [null, null, "type de l'argument attendu par l'option"],
    "args" => [null, null, "type des arguments attendus par l'option",
      # si args est spécifié, arg est ignoré
    ],
    "argsdesc" => [null, null, "description textuelle des arguments, utilisé pour l'affichage de l'aide"],
    "type" => [null, null, "types dans lesquels convertir les arguments avant de les fournir à l'utilisateur"],
    "action" => [null, null, "fonction à appeler quand cette option est utilisée",
      # la signature de la fonction est ($value, $name, $arg, $dest, $def)
    ],
    "name" => [null, null, "propriété ou clé à initialiser en réponse à l'utilisation de cette option",
      "desc" => "le nom à spécifier est au format under_score, qui est transformée en camelCase si la destination est un objet",
    ],
    "property" => [null, null, "comme name mais force l'utilisation d'une propriété"],
    "key" => [null, null, "comme name mais force l'utilisation d'une clé"],
    "inverse" => ["bool", false, "décrémenter la destination au lieu de l'incrémenter pour une option sans argument"],
    "value" => ["mixed", null, "valeur à forcer au lieu d'incrémenter la destination"],
    "ensure_array" => [null, null, "forcer la destination à être un tableau"],
    "help" => [null, null, "description de cette option, utilisé pour l'affichage de l'aide"],
    "cmd_args" => [null, null, "définition des sous-options pour une commande"],

    # ces valeurs sont calculées
    "cmd_defs" => [null, null, "(interne) liste des définitions correspondant au paramètre options"],
  ];

  const ARGS_ALLOWED_VALUES = ["value", "path", "dir", "file", "host"];
}