nl::ArgParser

Analisar um conjunto de argumentos no estilo da linha de comando, chamando funções de processamento para processar cada opção e argumento sem opção

O ParseArgs() usa uma lista de argumentos (argv) e os analisa de acordo com um conjunto de definições de opções fornecidas. A função é compatível com opções longas (opt) e curtas (-o) e implementa a mesma sintaxe de opções da função GNU getopt_long(3).

As definições da 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ção e uma função de gerenciador. O ParseArgs() processa os argumentos de opção na ordem especificada, chamando a respectiva função de gerenciador para cada opção reconhecida. Depois que todas as opções forem analisadas, uma função separada de gerenciador não opcional (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ção junto com um ponteiro para uma função de gerenciador que será chamada quando uma das opções associadas for encontrada. Os conjuntos de opções também contêm um texto explicativo que descreve a sintaxe e a finalidade de cada opção (consulte AJUDA DE OPÇÃO abaixo). Os conjuntos de opções foram criados 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 o OptionSetsone. Ele pode inicializar uma instância da estrutura OptionSet propriamente dita, por exemplo, como um global estático ou a subclasse OptionSetBase e fornecer um construtor. O último usa uma função HandleOption() pura virtual para delegar o gerenciamento de opções à subclasse.

As listas de OptionSets são transmitidas para a função ParseArgs() como uma matriz de ponteiros terminada em NULL. Por exemplo:

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 DA OPÇÃO

As opções são definidas usando a estrutura OptionDef. As definições da 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 de número inteiro usado para identificar a opção e se a opção espera/permite um argumento. O final da matriz de opções é sinalizado por um campo de nome NULL. Por exemplo:

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ÇÃO

Os IDs das opções identificam opções para o código que as processa (a função OptionHandler). Os IDs das opções são relativos aos OptionSet em que aparecem e, portanto, podem ser reutilizados em diferentes SetSets (consulte a seção SHORT OPTIONS abaixo). A convenção comum é começar a numeração de IDs de opção em 1.000, mas qualquer número > 128 pode ser usado. As opções de alias podem ser criadas usando o mesmo ID de opção com diferentes nomes de opções.

OPÇÕES CURTA

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

O ParseArgs() exige que os caracteres de opção curtos sejam exclusivos em all OptionSets. Por isso, o uso de opções curtas não é recomendado para nenhum conjunto de Option compartilhado entre os programas devido à possibilidade significativa de colisões. Os caracteres das opções curtas podem ser reutilizados em um único OptionSet para permitir a criação de nomes de opções longas de alias.

AJUDA DA OPÇÃO

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 de opções.

Por convenção, as strings de ajuda são um exemplo de sintaxe seguido de 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 em dois espaços, e as linhas de descrição são recuadas em sete. Uma única linha em branco segue cada descrição das opções, incluindo a última.

Por exemplo:

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ÇÃO

OptionSets contém uma string HelpGroupName 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, o PrintOptionHelp() imprimirá a ajuda para os diferentes SetSets juntos 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
)