nl::ArgParser

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

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

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

オプション セット

OptionSet には、一連のオプション定義と、関連付けられているオプションのいずれかが検出されたときに呼び出されるハンドラ関数へのポインタが含まれます。オプション セットには、各オプションの構文と目的を説明するヘルプテキストも含まれています（下記の「オプション ヘルプ」をご覧ください）。オプション セットは、関連するオプションの再利用可能なコレクションを作成できるように設計されています。これにより、同様のオプションを受け入れる複数のアプリケーション（テスト アプリケーションなど）を維持するために必要な作業が簡素化されます。

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

OptionSet のリストは、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 間で再利用できます（ただし、下記の「短いオプション」をご覧ください）。一般的な慣例では、オプション ID の番号は 1, 000 から開始しますが、任意の数 >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";

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

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
)