nl::ArgParser

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

ParseArgs() mengambil daftar argumen (argv) dan mengurainya sesuai dengan serangkaian definisi opsi yang disediakan. Fungsi ini mendukung opsi long (opt) dan short (-o) dan mengimplementasikan sintaks 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 diuraikan, fungsi pengendali non-opsi yang 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 dirancang untuk memungkinkan pembuatan koleksi 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 yang dapat menginisialisasi instance struktur OptionSet, misalnya sebagai global statis, atau membuat subclass OptionSetBase dan menyediakan konstruktor. Yang 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, dengan setiap elemen berisi: nama opsi, ID bilangan bulat yang digunakan untuk mengidentifikasi opsi, dan apakah opsi mengharapkan/mengizinkan argumen. Akhir dari array opsi ditandai oleh kolom Name 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 }
};

IDS OPSI

ID opsi mengidentifikasi opsi ke kode yang menanganinya (fungsi OptionHandler). ID opsi relatif terhadap OptionSet tempatnya muncul, dan dengan demikian dapat digunakan kembali di berbagai OptionSets (namun lihat OPSI PENDEK di bawah). Konvensi yang umum adalah dengan mulai penomoran ID opsi pada 1.000, namun angka > 128 dapat digunakan. Opsi alias dapat dibuat dengan menggunakan ID opsi yang sama dengan nama opsi yang berbeda.

OPSI SINGKAT

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

ParseArgs() memerlukan karakter opsi singkat yang unik di semua OptionSets. Karena itu, penggunaan opsi singkat tidak disarankan untuk setiap OptionSets yang digunakan bersama di seluruh program karena adanya peluang terjadinya konflik yang signifikan. Karakter opsi pendek dapat digunakan kembali dalam satu OptionSet untuk memungkinkan pembuatan nama opsi panjang alias.

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 dari opsi tersebut. Jika opsi memiliki versi pendek, atau nama alias, opsi tersebut 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

OptionSets 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 OptionSets memiliki HelpGroupName yang sama, PrintOptionHelp() akan mencetak bantuan opsi untuk OptionSets yang berbeda secara bersamaan di bawah 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
)