nl::ArgParser

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

ParseArgs() 接受一个参数列表 (argv)，并根据提供的一组选项定义对其进行解析。该函数支持 long (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 中重复使用（不过，请参阅下面的“简短选项”）。常见惯例是将选项 ID 从 1000 开始编号，但任何大于号的数字可以使用 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
)