nl :: ArgParser

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

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

As definições de opções são passadas para ParseArgs () como uma matriz de estruturas de OptionSet ( optSets ). Cada OptionSet contém uma matriz de definições de opção e uma função de manipulador. ParseArgs () processa argumentos de opção na ordem dada, chamando a respectiva função de tratamento para cada opção reconhecida. Depois que todas as opções forem analisadas, uma função de manipulador não opcional separada ( nonOptArgHandler ) é chamada uma vez para processar quaisquer 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 do manipulador 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 AJUDA DE OPÇÕES abaixo). Os conjuntos de opções são 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).

Existem dois padrões para definir OptionSetsone pode inicializar uma instância da própria estrutura OptionSet , por exemplo, como um global estático, ou subclasseOptionSetBase e fornecer um construtor. O último usa uma função HandleOption() virtual pura para delegar a manipulação de opções à subclasse.

Listas de OptionSets são passadas para a função ParseArgs () como uma matriz terminada em NULL de ponteiros. 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 de opções são organizadas como uma matriz de elementos OptionDef , em que cada elemento contém: o nome da opção, um ID de número inteiro que é usado para identificar a opção e se a opção espera / permite um argumento. O fim do array de opções é assinalado por um campo NULL Name. Ex:

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

OPÇÃO IDS

Os IDs de opção identificam opções para o código que os manipula (a função OptionHandler). IDs de opção são relativos ao OptionSet em que aparecem e, portanto, podem ser reutilizados em diferentes OptionSets (no entanto, consulte OPÇÕES RESUMIDAS abaixo). A convenção comum é começar a numerar os ids de opção em 1000; no entanto, 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ção diferentes.

OPÇÕES CURTAS

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

ParseArgs () requer que os caracteres de opção curtos sejam exclusivos em todos os OptionSets. Por causa disso, o uso de opções curtas é desencorajado para quaisquer OptionSets que são 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ções longos de alias.

AJUDA DE 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 alternativo, ela será fornecida antes do nome longo principal. Para consistência, as linhas de sintaxe são indentadas com 2 espaços, enquanto as linhas de descrição são indentadas com 7 espaços. Uma única linha em branco segue a descrição de cada opção, 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ÇÕES

OptionSets contém uma string HelpGroupName que é usada para agrupar opções na saída de ajuda. A função PrintOptionHelp() usa 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 juntos sob 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
)