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 () recebe uma lista de argumentos ( argv ) e analisa-los 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).

Definições de opções são passados para ParseArgs () como uma matriz de optionset estruturas ( optSets ). Cada optionset contém uma série de definições de opções e uma função de manipulador. ParseArgs () processa os argumentos das opções na ordem dada, chamando a respectiva função de tratamento para cada opção reconhecida. Uma vez que todas as opções foram analisadas, uma função separada manipulador de não-opção ( nonOptArgHandler ) é chamado uma vez para processar todos os demais argumentos.

CONJUNTOS DE OPÇÕES

Um optionset contém um conjunto de definições de opções, juntamente com um ponteiro para uma função de manipulador que será chamado quando uma das opções associadas é encontrado. Os conjuntos de opções também contêm texto de ajuda que descreve a sintaxe e o propósito 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 do optionset struct em si, por exemplo, como estática global, ou subclasseOptionSetBase e fornecer um construtor. Estas últimas utilizações um virtual pura HandleOption() função delegar manuseamento opção para a 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 o OptionDef estrutura. Definições de opções são organizadas como uma série de optiondef elementos, em que cada elemento contém: o nome da opção, um ID de número inteiro que é usada para identificar a opção, e se as espera opção / permite um argumento. O fim do array de opções é sinalizado por um campo NULL Name. 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 }
};

OPÇÃO IDS

Os IDs de opção identificam opções para o código que os manipula (a função OptionHandler). Ids opção são relativas ao optionset em que eles aparecem, e, portanto, podem ser reutilizados em diferentes OptionSets (no entanto, ver SHORT opções 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 no intervalo de caracteres ASCII gráficos permitirá que esse caractere seja usado como uma opção curta.

ParseArgs () requer que os caracteres curtas de opções ser exclusivo em todos 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. Opções curtas caracteres podem ser reutilizados dentro de um único optionset para permitir a criação de nomes de alias longo de opção.

AJUDA DE OPÇÃO

Cada optionset contém um OptionHelp cadeia que descreve a finalidade ea sintaxe das opções associadas. Essas seqüências são usados pelo PrintOptionHelp() função para gerar informações de uso 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 conter uma HelpGroupName corda que é usado para opções de agrupar na saída ajuda. O PrintOptionHelp() função utiliza o HelpGroupName como um título de secção no uso de saída gerados. 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
)