nl::ArgParser

Analiza un conjunto de argumentos de estilo de línea de comandos y llama a las funciones de control para procesar cada opción y argumento que no sea de opciones.

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 la opción en el orden dado y llama a la función del controlador correspondiente para cada opción reconocida. Una vez que se analizaron todas las opciones, se llama una vez a una función separada que no es controlador de opciones (nonOptArgHandler) para procesar los argumentos restantes.

CONFIGURACIÓN DE OPCIONES

Un OptionSet contiene un conjunto de definiciones de opciones junto con un puntero a una función de 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 la AYUDA DE LA OPCIÓN 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 necesario de mantener múltiples aplicaciones que aceptan opciones similares (p.ej., aplicaciones de prueba).

Existen dos patrones para definir OpciónSetsone que puede inicializar una instancia de la estructura OptionSet, p.ej., como un global estático, o una subclase OptionSetBase y proporcionar un constructor. Esta última usa una función HandleOption() virtual pura para delegar el control de opciones a la subclase.

Las listas de OptionSets se pasan a la función ParseArgs() como un array de punteros terminado en 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))
    {
        ...
    }
}

DEFINICIONES DE LAS OPCIONES

Las opciones se definen con la estructura OptionDef. Las definiciones de las opciones se organizan como un array 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 array de opciones se indica con un campo 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 }
};

IDS DE OPCIÓN

Los IDs de opción identifican opciones en el código que los maneja (la función OptionHandler). Los IDs de opción están relacionados con el OptionSet en el que aparecen y, por lo tanto, se pueden volver a usar en diferentes OptionsSets (sin embargo, consulta las OPCIONES CORTAS a continuación). La convención habitual es comenzar a numerar los ID de las opciones en 1000; sin embargo, se puede usar cualquier número superior a 128. Se pueden crear opciones de alias usando el mismo ID de opción con diferentes nombres de opción.

OPCIONES CORTAS

A diferencia de getopt_long(3), ParseArgs() no toma una cadena separada que especifique la lista de caracteres de opciones cortos. En cambio, cualquier opción cuyo valor de ID se encuentre dentro del rango de caracteres ASCII gráficos permitirá que ese carácter se use como una opción corta.

ParseArgs() requiere que los caracteres de opciones cortos sean únicos en todos los OptionSets. Debido a esto, no se recomienda el uso de opciones cortas para ningún Conjunto de opciones que se comparta entre programas debido a la gran posibilidad de colisiones. Los caracteres de opciones cortas se pueden volver a usar dentro de un solo OptionSet para permitir la creación de nombres de opciones largos de alias.

AYUDA DE 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 cadenas para generar información de uso de opciones.

Por convención, las cadenas de ayuda opcional 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 muestra antes del nombre largo principal. Para mantener la coherencia, las líneas de sintaxis tienen una sangría de 2 espacios, mientras que las líneas descriptivas tienen una sangría de 7 espacios. Después de la descripción de cada opción, incluida la última, se agrega una sola línea en blanco.

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

GRUPOS DE AYUDA DE OPCIONES

OpciónSets contiene una cadena HelpGroupName que se usa para agrupar opciones en el resultado de ayuda. La función PrintOptionHelp() usa HelpGroupName como título de sección en el resultado de uso generado. Si varios OptionSets tienen el mismo HelpGroupName, PrintOptionHelp() imprimirá la ayuda de opciones para los diferentes OptionsSets juntos bajo un título de sección en comú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
)