nl::ArgParser

Analisa um conjunto de argumentos em estilo de linha de comando, chamando funções de manipulação para processar cada opção e argumento que não seja de opção.

ParseArgs() recebe uma lista de argumentos (argv) e os analisa de acordo com um conjunto de definições de opção fornecidas. A função suporta as opções longas (opt) e curtas (-o) e implementa a mesma sintaxe de opção que a função GNU getopt_long(3).

As definições de opção são transmitidas para ParseArgs() como uma matriz de estruturas OptionSet (optSets). Cada OptionSet contém uma matriz de definições de opções e uma função de gerenciador. ParseArgs() processa argumentos de opção na ordem indicada, chamando a respectiva função de gerenciador para cada opção reconhecida. Depois que todas as opções forem analisadas, uma função de gerenciador separada sem opção (nonOptArgHandler) será chamada uma vez para processar os argumentos restantes.

CONJUNTOS DE OPÇÕES

Um OptionSet contém um conjunto de definições de opções e um ponteiro para uma função do gerenciador que será chamada quando uma das opções associadas for encontrada. Os conjuntos de opções também contêm texto de ajuda que descreve a sintaxe e a finalidade de cada opção (consulte a AJUDA DA OPÇÃO abaixo). Os conjuntos de opções foram projetados para permitir a criação de coleções reutilizáveis de opções relacionadas. Isso simplifica o esforço necessário para manter vários aplicativos que aceitam opções semelhantes (por exemplo, aplicativos de teste).

Há dois padrões para definir OptionSetsone e inicializar uma instância do próprio struct OptionSet. Por exemplo: como um global estático ou uma subclasse OptionSetBase e forneça um construtor. O último usa uma função HandleOption() virtual pura para delegar o processamento de opções à subclasse.

As listas de OptionSets são transmitidas para a função ParseArgs() como uma matriz de ponteiros terminada em 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))
    {
        ...
    }
}

DEFINIÇÕES DE OPÇÕES

As opções são definidas usando a estrutura OptionDef. As definições de opção são organizadas como uma matriz de elementos OptionDef, em que cada elemento contém o nome da opção, um código inteiro usado para identificar a opção e se a opção espera/permite um argumento. O fim da matriz de opções é indicado por um 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 OPÇÕES

Os IDs de opção identificam opções para o código que as processa (a função OptionHandler). Os IDs das opções são relativos ao OptionSet em que aparecem e, portanto, podem ser reutilizados em diferentes OptionSets. No entanto, confira as OPÇÕES BREVES abaixo. Uma convenção comum é numerar os IDs das opções em 1.000, porém qualquer número > 128 pode ser usado. As opções de alias podem ser criadas usando o mesmo ID de opção com nomes de opções diferentes.

OPÇÕES SHORTS

Ao contrário de getopt_long(3), ParseArgs() não usa uma string separada para especificar a lista de caracteres de opção curta. Em vez disso, qualquer opção cujo valor do ID esteja no intervalo de caracteres gráficos ASCII permitirá que esse caractere seja usado como uma opção curta.

ParseArgs() requer que caracteres de opção curtos sejam exclusivos em todos os OptionSets. Por isso, o uso de opções curtas não é recomendado para OptionSets compartilhados entre programas devido à grande chance de colisões. Os caracteres de opções curtas podem ser reutilizados em um único OptionSet para permitir a criação de nomes de opção longos de alias.

AJUDA COM OPÇÕES

Cada OptionSet contém uma string OptionHelp que descreve a finalidade e a sintaxe das opções associadas. Essas strings são usadas pela função PrintOptionHelp() para gerar informações de uso da opção.

Por convenção, as strings de ajuda de opção consistem em um exemplo de sintaxe seguido por uma descrição textual da opção. Se a opção tiver uma versão curta ou um nome de alias, ela será fornecida antes do nome longo principal. Para manter a consistência, as linhas de sintaxe são recuadas com dois espaços, enquanto as linhas de descrição são recuadas com sete espaços. Uma única linha em branco após a descrição de cada opção, incluindo a ú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 AJUDA DE OPÇÕES

OptionSets contêm uma string HelpGroupName que é usada para agrupar opções na saída de ajuda. A função PrintOptionHelp() usa o HelpGroupName como um título de seção na saída de uso gerada. Se vários OptionSets tiverem o mesmo HelpGroupName, PrintOptionHelp() imprimirá a ajuda da opção para os diferentes OptionSets em um título de seção comum.

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
)