nl::ArgParser

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

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

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

选项集

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

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

OptionSet 的列表以以 NULL 结尾的指针数组的形式传递给 ParseArgs() 函数。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))
    {
        ...
    }
}

选项定义

选项是使用 OptionDef 结构定义的。选项定义以 OptionDef 元素的数组的形式进行组织，其中每个元素都包含：选项的名称、用于标识选项的整数 ID，以及选项是否需要/允许参数。选项数组的结尾通过 NULL Name 字段发出信号。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 }
};

选项 ID

选项 ID 用于标识处理这些选项的代码（OptionHandler 函数）的选项。选项 ID 是相对于显示它们的 OptionSet 的，因此可以在不同的 OptionSet 中重复使用（但请参阅下面的简短选项）。常见惯例是从 1000 开始编号选项 ID，但可以使用任何大于 128 的数字。可通过使用相同选项 ID 和不同选项名称创建别名选项。

短视频选项

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

ParseArgs() 要求短选项字符在所有 OptionSet 中必须是唯一的。因此，不建议对在程序之间共享的任何 OptionSet 使用短选项，因为这样很有可能发生冲突。可以在单个 OptionSet 中重复使用简短的选项字符，以便创建别名长选项名称。

选项帮助

每个 OptionSet 均包含一个 OptionHelp 字符串，用于说明相关选项的用途和语法。PrintOptionHelp() 函数使用这些字符串生成选项使用情况信息。

按照惯例，选项帮助字符串由语法示例和选项文本说明组成。如果选项具有简称或别名，则会在主长名称之前指定。为了保持一致性，语法行会缩进 2 个空格，而广告内容描述行会缩进 7 个空格。每个选项说明后面有一个空白行，包括最后一行。

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

选项帮助群组

OptionSet 包含一个 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
)