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 analiza de acuerdo a un conjunto de definiciones de las opciones suministrados. 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 las 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, una función de controlador no sea una opción separada ( nonOptArgHandler ) se llama una vez para procesar cualquier resto de argumentos.

CONJUNTOS OPCIONALES

Un optionset contiene un conjunto de definiciones de las opciones, junto con un puntero a una función de controlador que se llamará cuando se encuentra 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 la 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 puede inicializar ya sea una instancia de la optionset struct sí mismo, por ejemplo, como una estática global, o subclaseOptionSetBase y proporcionan un constructor. Este último utiliza un virtual pura HandleOption() de función de delegar la configuración futura de la subclase.

Las listas de OptionSets se pasan a la función ParseArgs () como una matriz de punteros terminada en NULL. 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 OPCIONES

Las opciones se definen mediante la OptionDef estructura. Definiciones de las opciones se organizan como una matriz de optiondef elementos, donde cada elemento contiene: el nombre de la opción, un identificador de número entero que se utiliza para identificar la opción, y si las Espera opción / permite un argumento. El final de la matriz de opciones se indica mediante un campo de nombre NULL. 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 opción identifican opciones para el código que las maneja (la función OptionHandler). Ids de opción son en relación con la optionset en que aparecen, y por lo tanto pueden ser reutilizados en diferentes OptionSets (sin embargo ver SHORT OPCIONES abajo). La convención común es comenzar a numerar los ID de las opciones 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 ser únicos en todas 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. Opciones cortos caracteres pueden ser reutilizados dentro de un solo optionset para permitir la creación de nombres de alias opción larga.

AYUDA OPCIONAL

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

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 nombre de alias, se da antes del nombre largo principal. Por 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.

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

OPCIÓN GRUPOS DE AYUDA

OptionSets contienen una HelpGroupName cadena que se utiliza para agrupar opciones en el resultado de la ayuda. El PrintOptionHelp() función utiliza el HelpGroupName como un título de la 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
)