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「名稱」欄位發出信號。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 (但請看下方的 SHORT OPTIONS)。常見的慣例是使用 1000 的編號選項 ID 開始編號，但可以使用任何大於 128 的數字。您可以使用相同的選項 ID 搭配不同的選項名稱來建立別名選項。

簡短選項

與 getopt_long(3) 不同的是，ParseArgs() 不會使用另一個字串來指定短選項字元清單。相反地，只要選項的 ID 值落在圖形 ASCII 字元範圍內，該字元就會成為簡短選項。

ParseArgs() 要求所有 OptionSet 中的簡短選項字元不得重複。因此，我們不建議對跨程式共用的 OptionSets 使用，因為這樣極有可能碰到衝突。短選項字元可在單一 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
)