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 de no 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 tanto largas (opt) como cortas (-o) e implementa la misma sintaxis de opciones 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 argumentos de opciones en el orden determinado y llama a la función de controlador respectiva para cada opción reconocida. Una vez que se analizaron todas las opciones, se llama a una función de controlador independiente (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 de controlador a la 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 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 para mantener múltiples aplicaciones que aceptan opciones similares (p.ej., aplicaciones de prueba).

Existen dos patrones para definir OptionSetsone que puede inicializar una instancia del struct OptionSet en sí, p.ej., como un global estático o una subclase OptionSetBase, y proporciona un constructor. Este último 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 OPCIONES

Las opciones se definen con la estructura OptionDef. Las definiciones de opciones se organizan como un array de elementos OptionDef, en el que cada elemento contiene lo siguiente: 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 OPCIONES

Los IDs de opción identifican opciones para el código que los administra (función OptionHandler). Los ID de opción están relacionados con el OptionSet en el que aparecen y, por lo tanto, se pueden volver a usar en diferentes OptionSets (sin embargo, consulta SHORT OPTIONS a continuación). Convención común es comenzar los IDs de las opciones de numeración en 1000; sin embargo, cualquier número > 128. Las opciones de alias se pueden crear usando el mismo ID de opción con diferentes nombres de opción.

OPCIONES BREVE

A diferencia de getopt_long(3), ParseArgs() no toma una cadena separada que especifica 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 utilice como una opción corta.

ParseArgs() requiere que los caracteres de opciones cortos sean únicos en todos los OptionSets. Por este motivo, no se recomienda el uso de opciones cortas para los OptionSets que se comparten entre programas debido a la posibilidad significativa de colisiones. Los caracteres de opciones cortas se pueden volver a usar en un solo OptionSet para permitir la creación de nombres de opciones largos de alias.

AYUDA CON LA OPCIÓN

Cada OptionSet contiene una cadena 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 de opción consisten en 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 proporciona antes del nombre largo principal. Para que haya 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. Una sola línea en blanco sigue a la descripción de cada opción, incluida la última.

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 LAS OPCIONES

Los OptionSets contienen 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 OptionSets juntos bajo un título de sección 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
)