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

Option ID 會針對處理選項的程式碼指出相關選項 (OptionHandler 函式)。選項 ID 與顯示選項的 OptionSet 相關，因此可能可以在不同的 OptionSet 中重複使用 (請參閱下方的 SHORT OPTIONS)。常見的慣例是，選項編號的開頭是 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
)