nl::ArgParser 语

解析一组命令行样式参数，调用处理函数来处理每个选项和非选项参数。

ParseArgs() 接受参数列表 (argv) 并根据提供的一组选项定义对其进行解析。该函数支持长选项 (opt) 和短选项 (-o)，并实现与 GNU getopt_long(3) 函数相同的选项语法。

选项定义作为一组 OptionSet 结构 (optSets) 传递给 ParseArgs()。每个 OptionSet 都包含一组选项定义和一个处理程序函数。ParseArgs() 会按指定顺序处理选项参数，并针对每个识别出的选项调用相应的处理程序函数。所有选项都解析完毕后，系统会调用一次单独的非选项处理程序函数 (nonOptArgHandler) 来处理所有剩余的参数。

选项集

OptionSet 包含一组选项定义以及指向处理程序函数的指针（当遇到某个关联选项时，系统会调用该函数）。选项集还包含介绍每个选项的语法和用途的帮助文本（请参阅下面的“选项帮助”）。选项集旨在允许创建可重复使用的相关选项集合。这简化了维护多个接受类似选项的应用（例如测试应用）所需的工作。

定义 OptionSetsone 有两种模式，其可以初始化 OptionSet 结构本身的实例（例如作为静态全局对象），或初始化 OptionSetBase 并提供构造函数。后者使用纯虚拟 HandleOption() 函数将选项处理委托给子类。

OptionSet 列表将作为 NULL 终止的指针数组传递给 ParseArgs() 函数。例如：

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))
    {
        ...
    }
}

选项定义

选项使用 OptionDef 结构定义。选项定义整理为 OptionDef 元素的数组，其中每个元素都包含：选项的名称、用于标识选项的整数 ID，以及选项是否要求/允许参数。选项数组的结尾通过 NULL Name 字段发出信号。例如：

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

选项 ID

选项 ID 用于标识处理这些选项的代码的选项（OptionHandler 函数）。选项 ID 是相对于它们在其中出现的 OptionSet 而言的，因此可重复用于不同的 OptionSet（不过，请参阅下面的“短选项”）。常见的惯例是从 1000 开始对选项 ID 进行编号，但 128 以下的任意数字均可使用。可以使用具有不同选项名称的相同选项 ID 来创建别名选项。

简短选项

与 getopt_long(3) 不同，ParseArgs() 不接受用于指定短选项字符列表的单独字符串。ID 值在图形 ASCII 字符范围内的任何选项都将允许将该字符用作简短选项。

ParseArgs() 要求所有选项集的短选项字符都是唯一的。因此，不建议在程序之间共享任何选项集，因为这会发生明显的冲突。短选项字符可以在单个 OptionSet 中重复使用，以允许创建别名长选项名称。

选项帮助

每个 OptionSet 都包含一个 OptionHelp 字符串，用于描述相关选项的用途和语法。PrintOptionHelp() 函数使用这些字符串来生成选项用法信息。

按照惯例，选项帮助字符串由语法示例后跟选项的文字说明组成。如果该选项具有简称或别名，则会在主要长名称之前显示。为了保持一致性，语法行缩进 2 个空格，而说明行缩进 7 个空格。每个选项说明（包括最后一个选项说明）后面都会有一个空白行。

例如：

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

选项的帮助论坛

选项集包含一个 HelpGroupName 字符串，用于将帮助输出中的选项分组在一起。PrintOptionHelp() 函数在生成的用法输出中会使用 HelpGroupName 作为部分标题。如果多个 OptionSet 具有相同的 HelpGroupName，PrintOptionHelp() 会在通用部分的标题下方输出适用于不同 OptionSet 的选项帮助。

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
)