nl :: ArgParser

Analiza un conjunto de argumentos de estilo de línea de comando, llamando a funciones de manejo para procesar cada opción y argumento que no es de opción.

ParseArgs () toma una lista de argumentos ( argv ) y los analiza de acuerdo con 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 GNU getopt_long (3).

Definiciones de las opciones se pasan a ParseArgs () como una matriz de optionset estructuras ( optSets ). Cada OptionSet contiene una matriz de definiciones de opciones y una función de controlador. ParseArgs () procesa los argumentos de las opciones en el orden dado, llamando a la función del controlador respectivo para cada opción reconocida. Una vez que se han analizado todas las opciones, se llama una vez a una función de controlador que no es de opción ( nonOptArgHandler ) para procesar los argumentos restantes.

CONJUNTOS OPCIONALES

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 (consulte AYUDA DE 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 necesario para mantener múltiples aplicaciones que aceptan opciones similares (por ejemplo, aplicaciones de prueba).

Hay dos patrones para definir OptionSetsone que puede inicializar una instancia de la estructura OptionSet en sí, por ejemplo, como un global estático, o una subclaseOptionSetBase y proporcionar un constructor. Este último usa una función puramente virtual HandleOption() para delegar el manejo de opciones a la subclase.

Las listas de OptionSets se pasan a la función ParseArgs () como una matriz de punteros terminada en NULL. Por ejemplo:

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 mediante la estructura OptionDef . Las definiciones de las opciones están organizadas como una matriz de elementos OptionDef , donde cada elemento contiene: el nombre de la opción, un ID entero que se usa para identificar la opción y si la opción espera / permite un argumento. El final de la matriz de opciones se indica mediante un campo de nombre NULL. Por ejemplo:

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 opción identifican opciones para el código que las maneja (la función OptionHandler). Los identificadores de opciones son relativos al OptionSet en el que aparecen y, por lo tanto, pueden reutilizarse en diferentes OptionSets (sin embargo, consulte OPCIONES CORTAS a continuación). La convención común es comenzar a numerar los ID de opción en 1000, sin embargo, se puede usar 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 CORTAS

A diferencia de getopt_long (3), ParseArgs () no toma una cadena separada que especifique la lista de caracteres de opción cortos. Por el contrario, cualquier opción cuyo valor de identificación se encuentre en el rango de caracteres gráficos ASCII permitirá que ese carácter se utilice como una opción corta.

ParseArgs () requiere que los caracteres de opción cortos sean únicos en todos los OptionSets. Debido a esto, se desaconseja el uso de opciones cortas para los OptionSets que se comparten entre programas debido a la gran posibilidad de colisiones. Los caracteres de opciones cortos se pueden reutilizar dentro de un único OptionSet para permitir la creación de nombres de opciones largos de alias.

AYUDA DE OPCIÓN

Cada OptionSet contiene una cadena OptionHelp que describe el propósito y la sintaxis de las opciones asociadas. Estas cadenas son utilizadas por la función PrintOptionHelp() para generar información de uso de opciones.

Por convención, las cadenas de ayuda de opciones 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 alias, se da antes del nombre largo principal. Para mantener la coherencia, las líneas de sintaxis se sangran con 2 espacios, mientras que las líneas descriptivas se sangran con 7 espacios. Una sola línea en blanco sigue a la descripción de cada opción, incluida la última.

Por ejemplo:

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

OPCIÓN GRUPOS DE AYUDA

Los OptionSets contienen una cadena HelpGroupName que se utiliza para agrupar opciones en la salida de ayuda. La función PrintOptionHelp() utiliza HelpGroupName como título de sección en la salida de uso generada. 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
)