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() 関数に渡されます。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 は、オプション ID が表示される OptionSet に関連するため、異なる OptionSet 間で再利用できます（ただし、下記の短縮オプションをご覧ください）。通常、オプション ID の番号付けは 1000 から開始しますが、128 を超える任意の番号を使用できます。エイリアス オプションを作成するには、同じオプション ID に異なるオプション名を使用します。

ショートカット

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

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

オプション ヘルプ

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

慣例として、オプションのヘルプ文字列は、構文例の後にオプションの説明を続けて記述します。オプションに短縮名やエイリアス名がある場合は、メインの正式名の前に表示されます。一貫性を確保するために、構文行は 2 つのスペースでインデントされ、説明行は 7 つのスペースでインデントされます。各オプションの説明の後に、最後の 1 行を含む空白行が 1 行挿入されます。

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

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

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
)