nl::ArgParser

Analizar un conjunto de argumentos de estilo de línea de comandos, llamar a funciones de control para procesar cada opción y argumento que no es una opción

ParseArgs() toma una lista de argumentos (argv) y los analiza según un conjunto de definiciones de opciones proporcionadas. La función admite opciones largas (opt) y cortas (-o) e implementa la misma sintaxis de opción que la función getopt_long(3) de GNU.

Las definiciones de opciones se pasan a ParseArgs() como un array de estructuras OptionSet (optSets). Cada OptionSet contiene un array de definiciones de opciones y una función de controlador. ParseArgs() procesa los argumentos de opciones en el orden dado, llamando a la función del controlador respectiva para cada opción reconocida. Una vez que se analizaron todas las opciones, se llama a una función del controlador independiente de opciones (nonOptArgHandler) una vez para procesar los argumentos restantes.

Conjuntos de opciones

Un OptionSet contiene un conjunto de definiciones de opciones junto con un puntero para una función del controlador que se llamará cuando se encuentre una de las opciones asociadas. Los conjuntos de opciones también contienen texto de ayuda que describe la sintaxis y el propósito de cada opción (consulta AYUDA PARA OPCIONES a continuación). Los conjuntos de opciones están diseñados para permitir la creación de colecciones reutilizables de opciones relacionadas. Esto simplifica el esfuerzo que se necesita para mantener varias aplicaciones que aceptan opciones similares (p.ej., aplicaciones de prueba).

Hay dos patrones para definir una opción SetSetsone que pueden inicializar una instancia de la estructura OptionSet en sí misma, p.ej., como un global estático o una subclase OptionSetBase y proporcionar un constructor. Este último usa una función HandleOption() pura para delegar el control de opciones a la subclase.

Las listas de OptionSets se pasan a la función ParseArgs() como un arreglo de punteros finalizado con NULL. P.ej.:

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))
    {
        ...
    }
}

DEFINICIONES DE LA OPCIÓN

Las opciones se definen con la estructura OptionDef. Las definiciones de las opciones se organizan como un arreglo de elementos OptionDef, en el que cada elemento contiene: el nombre de la opción, un ID de número entero que se usa para identificar la opción y si la opción espera o permite un argumento. El final del arreglo de opciones se indica mediante un campo NULL Name. P.ej.:

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 DE OPCIÓN

Los ID de opciones identifican las opciones del código que las administra (la función OptionHandler). Los ID de opciones se relacionan con el OptionSet en el que aparecen y, por lo tanto, se pueden volver a usar en diferentes SetSets (sin embargo, consulta SHORT OPTIONS a continuación). Una convención común es comenzar con la numeración de los ID de la opción en 1,000, pero se puede usar cualquier cifra de 128. Las opciones de alias se pueden crear usando el mismo ID de opción con diferentes nombres de opción.

OPCIONES SHORT

A diferencia de getopt_long(3), ParseArgs() no acepta una string separada que especifique la lista de caracteres de opciones cortas. Más bien, cualquier opción cuyo valor de ID se encuentre dentro del rango de caracteres ASCII gráficos permitirá que se use como una opción corta.

ParseArgs() requiere que los caracteres cortos de opciones sean únicos en todos los SetSets. Debido a esto, no se recomienda el uso de opciones cortas en los OpciónSets que se comparten entre programas debido a la posibilidad significativa de colisión. Los caracteres de opción corta se pueden volver a usar dentro de un mismo OptionSet para permitir la creación de nombres largos de opciones de alias.

AYUDA DE LA OPCIÓN

Cada OptionSet contiene una string OptionHelp que describe el propósito y la sintaxis de las opciones asociadas. La función PrintOptionHelp() usa estas strings para generar información de uso de las opciones.

Por convención, las strings de ayuda de opciones constan de un ejemplo de sintaxis seguido de una descripción textual de la opción. Si la opción tiene una versión corta o un nombre de alias, se asigna antes que el nombre largo principal. Por motivos de coherencia, las líneas de sintaxis tienen una sangría de 2 espacios, mientras que las de descripción tienen 7 espacios de sangría. Una sola línea en blanco aparece después de cada descripción de opción, incluida la última.

P.ej.:

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";

GRUPOS DE AYUDA DE LA OPCIÓN

Los SetSets contienen una string HelpGroupName que se usa para agrupar las opciones en el resultado de ayuda. La función PrintOptionHelp() usa el HelpGroupName como título de sección en el resultado de uso generado. Si varios SetSets tienen el mismo HelpGroupName, PrintOptionHelp() imprimirá la opción de ayuda para los diferentes SetSets en un mismo título de sección.

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
)