nl::ArgParser

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

ParseArgs() usa uma lista de argumentos (argv) e os analisa de acordo com um conjunto de definições de opção fornecidas. A função oferece suporte a opções longas (opt) e curtas (-o) e implementa a mesma sintaxe de opção que a função do 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ção e uma função de gerenciador. ParseArgs() processa argumentos de opção na ordem determinada, chamando a respectiva função do gerenciador para cada opção reconhecida. Depois que todas as opções forem analisadas, uma função gerenciadora 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ções, junto com um ponteiro para uma função de gerenciador que é chamada quando uma das opções associadas é encontrada. Os conjuntos de opções também contêm um texto de ajuda que descreve a sintaxe e a finalidade de cada opção (consulte a AJUDA DE OPÇÕES 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: cada um pode inicializar uma instância do próprio struct OptionSet, por exemplo, como um valor global estático, ou uma subclasse OptionSetBase, e fornecer 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 DA OPÇÃO

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 de número inteiro que é usado para identificar a opção e se a opção espera/permite um argumento. O fim da matriz de opções é sinalizado por um campo "Nome NULL". 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 DAS OPÇÕES

Os IDs de opção identificam opções para o código que as processa (a função OptionHandler). Os códigos de opção são relativos ao OptionSet em que aparecem e, portanto, podem ser reutilizados em diferentes OptionSets (no entanto, confira "SHORT OPTIONS" abaixo). A convenção comum é começar a numerar os IDs de opção em 1.000, porém qualquer número maior que 128 pode ser usado. As opções de alias podem ser criadas usando o mesmo código de opção com nomes de opção diferentes.

OPÇÕES CURTAS

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

ParseArgs() exige que os caracteres curtos de opção sejam exclusivos em todos os OptionSets. Por isso, o uso de opções curtas não é recomendado para OptionSets compartilhados entre programas, devido à chance significativa 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 do 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 da opção.

Por convenção, as strings de ajuda da 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, ele será fornecido 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 segue 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 DAS 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, o PrintOptionHelp() exibirá a ajuda da opção para os diferentes OptionSets 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
)