nl::ArgParser

Mengurai kumpulan argumen gaya command line, memanggil fungsi penanganan untuk memproses setiap opsi dan argumen non-opsi.

ParseArgs() mengambil daftar argumen (argv) dan mengurainya sesuai dengan sekumpulan definisi opsi yang disediakan. Fungsi ini mendukung opsi long (opt) dan short (-o) dan mengimplementasikan sintaksis opsi yang sama dengan fungsi GNU getopt_long(3).

Definisi opsi diteruskan ke ParseArgs() sebagai array struktur OptionSet (optSets). Setiap OptionSet berisi array definisi opsi dan fungsi pengendali. ParseArgs() memproses argumen opsi dalam urutan tertentu, memanggil fungsi pengendali masing-masing untuk setiap opsi yang dikenali. Setelah semua opsi diurai, fungsi pengendali non-opsi terpisah (nonOptArgHandler) dipanggil satu kali untuk memproses argumen yang tersisa.

SET OPSI

OptionSet berisi kumpulan definisi opsi beserta pointer ke fungsi pengendali yang akan dipanggil saat salah satu opsi terkait ditemukan. Kumpulan opsi juga berisi teks bantuan yang menjelaskan sintaksis dan tujuan setiap opsi (lihat BANTUAN OPSI di bawah). Kumpulan opsi didesain untuk memungkinkan pembuatan kumpulan opsi terkait yang dapat digunakan kembali. Hal ini menyederhanakan upaya yang diperlukan untuk mengelola beberapa aplikasi yang menerima opsi serupa (mis. aplikasi pengujian).

Ada dua pola untuk menentukan OptionSetsone dapat melakukan inisialisasi instance struct OptionSet itu sendiri, misalnya sebagai global statis, atau membuat subclass OptionSetBase dan menyediakan konstruktor. Kode kedua menggunakan fungsi HandleOption() virtual murni untuk mendelegasikan penanganan opsi ke subclass.

Daftar OptionSets diteruskan ke fungsi ParseArgs() sebagai array pointer yang dihentikan NULL. 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))
    {
        ...
    }
}

DEFINISI OPSI

Opsi ditentukan menggunakan struktur OptionDef. Definisi opsi disusun sebagai array elemen OptionDef, yang setiap elemennya berisi: nama opsi, ID bilangan bulat yang digunakan untuk mengidentifikasi opsi, dan apakah opsi tersebut mengharapkan/mengizinkan argumen. Akhir dari array opsi diberi sinyal oleh isian Nama 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 OPSI

ID opsi mengidentifikasi opsi pada kode yang menanganinya (fungsi OptionHandler). ID opsi bersifat relatif terhadap OptionSet tempat ID tersebut muncul, sehingga dapat digunakan kembali di berbagai OptionSet (tetapi lihat OPSI PENDEK di bawah). Konvensi umumnya adalah memulai ID opsi penomoran dari 1000, tetapi angka berapa pun > 128 dapat digunakan. Opsi alias dapat dibuat menggunakan ID opsi yang sama dengan nama opsi yang berbeda.

OPSI PENDEK

Tidak seperti getopt_long(3), ParseArgs() tidak mengambil string terpisah yang menentukan daftar karakter opsi singkat. Sebaliknya, opsi apa pun yang nilai ID-nya berada dalam rentang karakter ASCII grafis akan memungkinkan karakter tersebut digunakan sebagai opsi singkat.

ParseArgs() mengharuskan karakter opsi singkat bersifat unik di semua OptionSet. Oleh karena itu, penggunaan opsi singkat tidak disarankan untuk OptionSet apa pun yang dibagikan di seluruh program karena besar peluang terjadinya konflik. Karakter opsi singkat dapat digunakan kembali dalam satu OptionSet untuk memungkinkan pembuatan alias nama opsi panjang.

BANTUAN OPSI

Setiap OptionSet berisi string OptionHelp yang menjelaskan tujuan dan sintaksis opsi terkait. String ini digunakan oleh fungsi PrintOptionHelp() untuk menghasilkan informasi penggunaan opsi.

Berdasarkan konvensi, string bantuan opsi terdiri dari contoh sintaksis yang diikuti dengan deskripsi tekstual opsi tersebut. Jika opsi tersebut memiliki versi pendek, atau nama alias, opsi ini diberikan sebelum nama panjang utama. Untuk konsistensi, baris sintaksis diindentasi dengan 2 spasi, sedangkan baris deskripsi diindentasi dengan 7 spasi. Satu baris kosong mengikuti setiap deskripsi opsi, termasuk yang terakhir.

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

GRUP BANTUAN OPSI

OptionSet berisi string HelpGroupName yang digunakan untuk mengelompokkan opsi dalam output bantuan. Fungsi PrintOptionHelp() menggunakan HelpGroupName sebagai judul bagian dalam output penggunaan yang dihasilkan. Jika beberapa OptionSet memiliki HelpGroupName yang sama, PrintOptionHelp() akan mencetak bantuan opsi untuk OptionSets yang berbeda secara bersamaan pada judul bagian yang umum.

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
)