nl::ArgParser

Analyser un ensemble d'arguments de type ligne de commande, en appelant des fonctions de gestion pour traiter chaque option et un argument autre qu'une option

ParseArgs() prend une liste d'arguments (argv) et les analyse en fonction d'un ensemble de définitions d'options fournies. La fonction prend en charge les options long (opt) et court (-o) et implémente la même syntaxe d'option que la fonction GNU getopt_long(3).

Les définitions d'option sont transmises à ParseArgs() sous la forme d'un tableau de structures OptionSet (optSets). Chaque OptionSet contient un tableau de définitions d'options et une fonction de gestionnaire. ParseArgs() traite les arguments d'option dans l'ordre indiqué, en appelant la fonction de gestionnaire correspondante pour chaque option reconnue. Une fois toutes les options analysées, une fonction de gestionnaire distincte (nonOptArgHandler) est appelée une fois pour traiter les arguments restants.

ENSEMBLES D'OPTION

Un OptionSet contient un ensemble de définitions d'options, ainsi qu'un pointeur vers une fonction de gestionnaire qui est appelée lorsque l'une des options associées est rencontrée. Les jeux d'options contiennent également un texte d'aide décrivant la syntaxe et l'objectif de chaque option (voir AIDE SUR LES OPTIONs ci-dessous). Les ensembles d'options sont conçus pour permettre la création de collections réutilisables d'options associées. Cela simplifie les efforts nécessaires pour gérer plusieurs applications qui acceptent des options similaires (par exemple, des applications de test).

Deux modèles permettent de définir le paramètre OptionSetsone permettant d'initialiser une instance de la structure OptionSet elle-même : en tant que global statique, ou sous-classe OptionSetBase et fournissez un constructeur. Cette dernière utilise une fonction HandleOption() virtuelle pure pour déléguer la gestion des options à la sous-classe.

Les listes d'OptionSets sont transmises à la fonction ParseArgs() en tant que tableau de pointeurs clôturé par une valeur NULL. E.g.:

static OptionSet gToolOptions =
{
    HandleOption,        // handler function
    gToolOptionDefs,  // array of option definitions
    "GENERAL OPTIONS",   // help group
    gToolOptionHelp   // option help text
};

static OptionSet *gOptionSets[] =
{
    &gToolOptions,
    &gNetworkOptions,
    &gTestingOptions,
    &gHelpOptions,
    NULL
};

int main(int argc, char *argv[])
{
    if (!ParseArgs("test-app", argc, argv, gOptionSets))
    {
        ...
    }
}

DÉFINITIONS DES OPTION

Les options sont définies à l'aide de la structure OptionDef. Les définitions d'option sont organisées sous la forme d'un tableau d'éléments OptionDef, où chaque élément contient: le nom de l'option, un ID d'entier utilisé pour identifier l'option et si l'option attend/autorise un argument. La fin du tableau d'options est signalée par un champ "NULL Name". E.g.:

enum
{
    kOpt_Listen = 1000,
    kOpt_Length,
    kOpt_Count,
};

static OptionDef gToolOptionDefs[] =
{
    // NAME         REQUIRES/ALLOWS ARG?  ID/SHORT OPTION CHAR
    // ============================================================
    {  "listen",    kNoArgument,          kOpt_Listen     },
    {  "length",    kArgumentRequired,    kOpt_Length     },
    {  "count",     kArgumentRequired,    kOpt_Count      },
    {  "num",       kArgumentRequired,    kOpt_Count      }, // alias for --count
    {  "debug",     kArgumentOptional,    'd'             },
    {  "help",      kNoArgument,          'h'             },
    {  NULL }
};

ID D'OPTION

Les identifiants d'option identifient les options du code qui les gère (fonction OptionHandler). Les identifiants d'option se rapportent au OptionSet dans lequel ils apparaissent. Ils peuvent donc être réutilisés dans différents ensembles d'options (voir la section "OPTIONS COURT" ci-dessous). En règle générale, les ID d'option de numérotation commencent à 1 000, mais tout nombre > 128. Les options d'alias peuvent être créées en utilisant le même identifiant d'option avec des noms d'option différents.

OPTIONS COURTES

Contrairement à getopt_long(3), ParseArgs() ne nécessite pas de chaîne distincte spécifiant la liste des caractères d'option abrégés. Par contre, toute option dont la valeur d'ID est comprise dans la plage de caractères ASCII graphiques autorise l'utilisation de ce caractère en tant qu'option abrégée.

ParseArgs() nécessite que les caractères d'option courts soient uniques dans tous les ensembles d'options. Pour cette raison, l'utilisation d'options courtes est déconseillée pour les ensembles d'options partagés entre les programmes en raison du risque important de collision. Les caractères des options abrégées peuvent être réutilisés dans un même OptionSet pour permettre la création de noms d'options longs pour les alias.

AIDE SUR LES OPTION

Chaque OptionSet contient une chaîne OptionHelp qui décrit l'objectif et la syntaxe des options associées. Ces chaînes sont utilisées par la fonction PrintOptionHelp() pour générer des informations sur l'utilisation des options.

Par convention, les chaînes d'aide sur les options sont constituées d'un exemple de syntaxe suivi d'une description textuelle de l'option. Si l'option comporte une version courte ou un nom d'alias, il est placé avant le nom long principal. Par souci de cohérence, les lignes de syntaxe sont mises en retrait avec 2 espaces, tandis que les lignes de description sont en retrait de 7 espaces. Une seule ligne vide suit chaque description d'option, y compris la dernière.

E.g.:

static const char *const gToolOptionHelp =
    "  --listen\n"
    "       Listen and respond to requests sent from another node.\n"
    "\n"
    "  --length \n"
    "       Send requests with the specified number of bytes in the payload.\n"
    "\n"
    "  --num, --count \n"
    "       Send the specified number of requests and exit.\n"
    "\n"
    "  -d, --debug []\n"
    "       Set debug logging to the given level. (Default: 1)\n"
    "\n"
    "  -h, --help\n"
    "       Print help information.\n"
    "\n";

GROUPES D'AIDE SUR LES OPTION

Les ensembles d'options contiennent une chaîne HelpGroupName qui permet de regrouper les options dans le résultat de l'aide. La fonction PrintOptionHelp() utilise "HelpGroupName" comme titre de section dans le résultat d'utilisation généré. Si plusieurs OptionSets ont le même HelpGroupName, PrintOptionHelp() imprime l'aide sur les options pour les différents ensemble d'options ensemble sous un titre de section commun.

ParseArgs

bool ParseArgs(
  const char *progName,
  int argc,
  char *argv[],
  OptionSet *optSets[]
)

bool ParseArgsFromEnvVar(
  const char *progName,
  const char *varName,
  OptionSet *optSets[],
  NonOptionArgHandlerFunct nonOptArgHandler,
  bool ignoreUnknown
)

bool ParseArgsFromEnvVar(
  const char *progName,
  const char *varName,
  OptionSet *optSets[]
)

bool ParseArgsFromEnvVar(
  const char *progName,
  const char *varName,
  OptionSet *optSets[],
  NonOptionArgHandlerFunct nonOptArgHandler
)

bool ParseArgsFromString(
  const char *progName,
  const char *argStr,
  OptionSet *optSets[],
  NonOptionArgHandlerFunct nonOptArgHandler,
  bool ignoreUnknown
)

--listen --count 10 --sw-version '1.0 (DEVELOPMENT)' "--hostname=nest.com"

bool ParseArgsFromString(
  const char *progName,
  const char *argStr,
  OptionSet *optSets[],
  NonOptionArgHandlerFunct nonOptArgHandler
)

bool ParseArgsFromString(
  const char *progName,
  const char *argStr,
  OptionSet *optSets[]
)

bool ParseBoolean(
  const char *str,
  bool & output
)

bool ParseFabricId(
  const char *str,
  uint64_t & fabricId,
  bool allowReserved
)

bool ParseHexString(
  const char *hexStr,
  uint32_t strLen,
  uint8_t *outBuf,
  uint32_t outBufSize,
  uint32_t & outDataLen
)

bool ParseIPAddress(
  const char *str,
  IPAddress & output
)

bool ParseInt(
  const char *str,
  uint64_t & output,
  int base
)

bool ParseInt(
  const char *str,
  uint32_t & output,
  int base
)

bool ParseInt(
  const char *str,
  int32_t & output,
  int base
)

bool ParseInt(
  const char *str,
  uint64_t & output
)

bool ParseInt(
  const char *str,
  uint32_t & output
)

bool ParseInt(
  const char *str,
  int32_t & output
)

bool ParseInt(
  const char *str,
  uint16_t & output
)

bool ParseInt(
  const char *str,
  int16_t & output
)

bool ParseInt(
  const char *str,
  uint8_t & output
)

bool ParseNodeId(
  const char *str,
  uint64_t & nodeId
)

bool ParseSubnetId(
  const char *str,
  uint16_t & subnetId
)

void PrintOptionHelp(
  OptionSet *optSets[],
  FILE *s
)

void PutStringWithBlankLine(
  FILE *s,
  const char *str
)

void PutStringWithNewLine(
  FILE *s,
  const char *str
)

int32_t SplitArgs(
  char *argStr,
  char **& argList,
  char *initialArg
)