nl::ArgParser

一連のコマンドライン スタイルの引数を解析し、処理オプションを呼び出して各オプションとオプション以外の引数を処理します。

ParseArgs() は引数のリスト（argv）を取り、指定されたオプション定義のセットに従って解析します。この関数は、長いオプション（opt）と短いオプション（-o）の両方をサポートし、GNU getopt_long(3) 関数と同じオプション構文を実装します。

オプション定義は、OptionSet 構造体（optSets）の配列として ParseArgs() に渡されます。各 OptionSet には、オプション定義の配列とハンドラ関数が含まれています。ParseArgs() は、指定された順序でオプション引数を処理し、認識されたオプションごとにそれぞれのハンドラ関数を呼び出します。すべてのオプションが解析されると、オプションの引数以外の関数（nonOptArgHandler）が 1 回呼び出され、残りの引数が処理されます。

オプションセット

OptionSet には、オプション定義のセットと、関連付けられたオプションのいずれかが発生したときに呼び出されるハンドラ関数へのポインタが含まれています。オプション セットには、各オプションの構文と目的を説明するヘルプテキストも含まれています（以下のオプションのヘルプを参照）。オプション セットは、関連するオプションの再利用可能なコレクションを作成できるように設計されています。これにより、同じようなオプションを受け入れる複数のアプリケーション（テスト アプリケーションなど）を維持するのに必要な労力が軽減されます。

OptionSetsone を定義するには 2 つのパターンがあります。これは、OptionSet 構造体自体のインスタンスを静的なグローバルとして初期化する方法と、OptionSetBase のサブクラスを作成してコンストラクタを提供する方法です。後者は、純粋な仮想 HandleOption() 関数を使用して、オプション処理をサブクラスに委任します。

OptionSets のリストは、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 で再利用できます（ただし、以下の SHORT OPTIONS を参照）。通常は 1000 から始まりますが、任意の数値 128 を使用できます。エイリアス オプションは、異なるオプション名で同じオプション ID を使用して作成できます。

短いオプション

getopt_long(3) とは異なり、ParseArgs() では短いオプション文字のリストを指定する別の文字列は使用されません。ID 値がグラフィカル ASCII 文字の範囲に収まるオプションであれば、その文字を短いオプションとして使用できます。

ParseArgs() では、短いオプション文字をすべての OptionSet にわたって一意にする必要があります。そのため、競合が発生する可能性が非常に高いため、プログラム間で共有されている OptionSet では短いオプションの使用は推奨されません。短いオプション文字は、1 つの OptionSet 内で再利用して、エイリアスの長いオプション名を作成できます。

オプションのヘルプ

各 OptionSet には、関連するオプションの目的と構文を説明する OptionHelp 文字列が含まれています。これらの文字列は、PrintOptionHelp() 関数でオプションの使用状況情報を生成するために使用されます。

慣例により、オプションのヘルプ文字列は、構文テキストの例とそれに続くテキスト形式の説明で構成されます。短いバージョンやエイリアス名がある場合は、メインロングネームの前に付けられます。一貫性を保つため、構文の行はスペース 2 つでインデントし、説明文はスペース 7 つでインデントします。各オプションの説明（最後の説明を含む）の後に空白行が 1 行あります。

例:

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

オプションのヘルプグループ

OptionSets には 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
)